Coda 2 User Manual

INTRODUCTION

Coda2 comes in two versions: coda which is the command-line version and wcoda which provides a GUI on top of coda.

Coda reads specially formatted comments in the source code, and produces output in various formats. This version of Coda support output in HTML and LaTeX. Support for WinHelp and Unix man pages are on the wish list. Coda can also read comments from several programming languages. Coda is packaged with support for Tcl, Perl, C, C++, C#, Java, Pascal, Emacs Lisp and Visual Basic. Coda also support reading pure text files containing raw CodaText. However, Coda can be customized to support other formats as well.

RUNNING CODA

The calling syntax of coda is as follows:

coda [-q] [-t format] [-d dir] [-r pattern] [-f file] pattern1 [pattern2 ...]

The parameters have the following meaning.

-t

Specifies the output format. Legal values of format are:

html

Will generate an index.html file, along with a table of contents file (toc.html), and one file for each doc-item. Those doc-items which are of type "item" (whichever is the default), will be included in the table of contents, the others not.

latex

Will generate a main.tex file, and one file for each doc-item. Those doc-items which are of type "document" will generate standalone latex articles, the others will be included in the main file.

If ommited, the target format defaults to html.

-d

Specifies the target directory where coda is to put the output files. The default value is doc

-r

Specifies that all files in the current directory and in all subdirectories matching a pattern is to be docified. This options can be repeated many times with different patterns.

-f

Specifies that a file named file contains a list of files to docify. This option is also repeatable.

-q

Tells coda to be quiet, that is, no output will be given during progress.

The remaining arguments, pattern1, pattern2 and so forth, specifies the files to docify in the current directory.

THE CODA FORMAT

The text format recognized by coda is called CodaText. It is a text format designed for documenting source code by writing the documentation as comments within the source files. The main purpose of designing this format is to provide a text format that is:

• easy to read
• easy to write
• easy to remember
• fairly easy to parse

HOW CODA READS COMMENTS

Coda has implemented two readers that extract comments from various file formats. These readers handle two distinct types of commenting syntax:

embrace style comments

This types of comments are recognized by a sequence of characters that identifies the beginning of a comment, and another sequence identifying the end of a comment. Typical examples of this type of comments syntax is implemented in C/C++ where comments are started by the sequence "/*" and ended by the sequence "*/", and pascal, where comments are embraced between a pair of curly braces.

prefix style comments

This type of comments are recognized by a sequence of characters that start a comment, which is ended by the subsequent newline. Typical exapmles of this type of comment syntax is implemented in Tcl and Perl where comments are prefixed by a "#" character and C++ where comments can be prefixed by a pair of forwards slashes ("//").

Coda has implemented three readers:

EmbraceReader

Reads comments with embrace style comments.

PrefixReader

Reads comments with prefix style comments.

PlainReader

Reads text files containing pure CodaText.

Each of these readers needs some parameters to interpret the source file correctly. These parameters are

coda prefix

This is the prefix that starts a coda comment. This prefix must begin with the string that opens a normal comment, must contain at least one extra character so coda distinguish the comments written for coda, and those that are not. It is recommended that no other characters than the prefix is included in the first line of a coda comment.

line prefix

For prefix style comments, this will be the sequence of characters that identifies comments in general. For embrace style comments, this is a character that you can add at the beginning of the line to make the comment stand out from the source code, and that coda will ignore during input. This character must be contained in the prefix, and it must be in the same column as the first occurence of the same character in the prefix.

comment suffix

This is the character sequence that identifies the end of a embrace-style comment.

Coda has implemented the following comment styles:

  comment      comment             coda        line     comment
  type         reader             prefix      prefix    suffix
  -------------------------------------------------------------
  pascal       EmbraceReader        {**         *          } 
  c            EmbraceReader        /**         *          /* 
 
  script       PrefixReader         ##          # 
  lisp         PrefixReader         ;;          ; 
  basic        PrefixReader         ''          ' 
  
  coda         PlainReader
  ------------------------------------------------------------

Coda has set up the following mapping between the comment type and the extensions of files.

pascal

.pas

c

.c .h .cp .cpp .hp .hpp .java .cs

script

.tcl .pl .cgi

lisp

.el

basic

.bas

coda

.txt .coda

CUSTOMIZING CODA TO READ MORE COMMENT TYPES

Suppose that you want to add suport for PostScript files. PostScript uses prefix style comments, and "%" as the comment prefix. In order to distinguish comments written for coda from other comments (including DSC comments), we want to prefix all coda-comments with a triple percent ("%%%").

In your home directory (for windows users, that'l be "C:\" or the directory specified by your "HOME" environment variable), add a file named .codarc. This is a tcl file that will be 'sourced' in by coda upon startup, if it exists. Note that coda will be sourced in within the coda namespace, so you can only manipualte the variables within the coda namespace, unless you use the global namespace qualifier.

First, we must define a new comment type. For this, coda maintains an array variable named formatMap. Each entry in this array contains a two-element list where the first element is the name of the name space that implements the reader, and the second element is the intialization parameters to the reader. Hence we include following line in the .codarc file:

set formatMap(postscript) {PrefixReader {"%%%" "%"}}

The next thing we do, is to provide a mapping between file extensions and our new postscript comment type. It is the array named extMap which holds this mapping. The following lines will map files with extensions ".ps" and ".eps" to the postscript comment type:

set extMap(.ps) postscript
set extMap{.eps) postscript

And that's all you have to do to make coda accept coda comments from postscript files.

For comprehensivenes, we also provide an example for reading html comments, just to show an example of embrace-style comments:

set formatMap(html) {EmbraceReader {"<!----" "-" "-->"}}
set extMap(.html) html
set extMap(.htm)  html

HOW TO IMPLEMENT NEW OUTPUT FORMATS