Documenting Data Sources

Templating System : Developer Guide : User Guide

Effective coordination between the developer and designer is one of the major challenges of any publishing team. The templating system provides a set of simple documentation directives so that developer comments on data sources can be extracted from Tcl scripts and summarized for non-technical members of the publishing team automatically.

To take advantage of this capability, the developer must structure comments on a datasource in the following way:

  # @datasource cars multirow
  # The cars owned by a user.
  # @column make The make of the car, i.e. Toyota
  # @column model The model of the car, i.e. Camry
  # @column year The year of manufacture
  # @datasource name onevalue
  # the name of the user
  # @data_input add_entry form
  # a form for adding entries to user's address book 
  # @input first_names text 
  # entry subject's first and middle names
  # @input last_name text
  # @input title text form of address for entry subject
  # @input birthday date birthdate w/ "MONTH DD YYYY" format
  # @input gender radio
  # either "m" for male or "f" for female

A few formatting guidelines:

Once the templates have been enabled, the designer can simply visit the URL from which the page will be served, substituting acs with the dat extension.