Coda2 Design Sepcification

Agnar Renolen
version 1.3
August 17th 2001



Coda2 is implemented in Tcl and designed into three distinct modules:

Comment Reader
Extracts comments from the source files, and strips comment symbols from the text. When a complete doc-item has been read the text is passed on to the CodaText parser.
CodaText Parser
Recieves text from the comment reader and parses it into a format similar to the format returned by the dump command of the text widget. When a doc-item has been parsed, it is passed on to the Docifier.
Recieves parsed doc-items from the CodaText parser, and outputs them in files of various formats, typically HTML, XML or LaTeX. One docifier for each output format.

The idea of Coda2 is to implement several compatible comment readers that can read comments from various types of programming languages (and other formats). Similarly, it should be possible to implement several compatible docifiers, that will produce outputs in various formats. This document specifies the interface of these modules.


A comment reader shall be implemented as a namespace having a predefined set of procs. Readers for different programming languages or commenting syntaxes should have different namespaces, which makes it really easy to extend Coda2 to accept new programming languages with any kind of commenting style (simply by implementing a new reader). In the sequel, the name of the namespace will be refferd to as CR (for comment reader).

There are two procs required to be implemented by a comment reader: GetNextItem and Init. The Init proc may take any number of arguments, the parameters to this proc must be specified internally for each comment style implemented by Coda. The purpose of the Init proc is to set up the reader to extract comments from a specific file format, and it will be called before reading each file (since one may run coda on several types of source files in one go).

GetNextItem should be called with the following syntax:

CR::GetNextItem channelID

The proc should start reading from the channel untill it encounters a Coda2 doc-item or the end of file. If a valid doc-item is found, the proc should return a list of input lines where the comment markup particular for the input language are stripped away, as for example inital pounds in tcl-comments. In theory, the proc should return pure text according to the Coda2 text format, although it is not the job of the reader to validate the text.

If the proc encounters the end of the file, it must return an empty string.


Coda2 will contain only one comment parser, which will interpret the doc-item according to the Coda2 text format specification. It will be assigned the name space CodaText, and will implement one proc which should be called with the following syntax:

CodaText::Parse headerVar textLines

It should return a list that has a similar structure that is returned by the dump command of the text widget:

key1 value1 key2 value2 ...

The possible values of key are:

Indicates a block of text, which is stored in the value variable.
Indicates the beginning of a paragraph, environment or a style tag. The value indicates the name of the tag, which is either of the following environments:
An itemized list
An enumerated list
A description list,
the following paragraph types:
A level 1 heading
A level 2 heading
A normal paragraph
The key of a descriptive list (the descripton will follow as a normal paragraph)
A block of computer voice preformatted text,
A figure
or the following style tags:
Emphasized text
A snippet of computer voice text.
A variable or metasymbol.
A reference to another doc-item. The subsequent text key will contain the name of the doc-item.
A link to an url. A begin link will immediately be followed by an url key.
A command, typically a menu command, that is to be carried out by the user.
Indicates the end of a paragraoh, environment or a style. The value will same values as for the begin key, and the param will allways be empty.
Indicates an item in a list environment. The value will contain a "*" for a unnumbered list, the item number for an enumerated item and the text of a descriptive item.
Specifies the url of a link item or a fig. It will be always occur as the first item subsequent to a begin link item.


A docifier reader shall be implemented as a namespace having a predefined set of procs. Docifiers for different output formats should have different namespaces, which makes it really easy to extend Coda to produce new formats (simply by implementing a new docifier) with any kind of obscure commenting format. In the sequel, the name of the namespace will be refferd to as CD (for coda docifier).

The docifier namespace need to implement several procs, which should have the following call syntax:

CD::StartProject ?options?

Typically, a project will comprise several files which is to be documented. A set of files will be referred to as a project. The projectName identifies the name of the project. The following options should be supported:

dir dirName
Specifies the name of the directory where to put the output files.

The following proc will be called when all items of a project are docified:


Specifies that all files in the project has been parsed and docified. This is a good time to write out indexes contents and main files.

CD::Docify headerVar docText

in file: "design.txt"