Copyright © 2003, 2004 Dave Bayer. Subject to the terms and conditions of the MIT License.
annote is a command line tool for creating annotated C source listings as HTML files. This documentation was created by annote.
This is the version of July 23, 2004. The complete source is available as annote.tar.gz. The web site for annote is www.math.columbia.edu/~bayer/annote/
To compile annote using gcc, change directories to the source directory, and execute the shell script
Scripts/build.sh
Note that the source code is divided into subdirectories, so it is necessary to tell compilers to search each of these subdirectories for include files.
To use annote, change directories to the project source directory, and enter either on a command line or in a build phase script
annote [files]
where [files] is the list of .txt documentation files for the project. The extension .txt is arbitrary, and can be changed. The command line option -detab n changes the detabbing setting to n spaces; the default is 4, and 0 turns off detabbing. The command line option -nocss prevents annote from writing the style file style.css, so that custom user modifications are preserved.
For example, to turn off detabbing and to use all .txt files in the current directory or in immediate subdirectories, enter
annote -detab 0 *.txt */*.txt
annote combines each documentation file with included source files to produce output .html files, matching comments in the source files with corresponding comments in the documentation file and substituting the text that follows. annote doesn't understand C syntax, but it creates links to and headers for local or global identifiers that are explicitly marked. The documentation files are basically plain text; annote supports a 'pidgeon html' that avoids the need most of the time to explicitly write html constructs in the documentation. The syntax for .txt files is most quickly learned by imitation; study the source for annote itself. The appearance of the output is controlled by a style sheet that can be modified as desired.
I am aware of alternatives; I prefer a minimalist approach that I can control myself, and I don't like the appearance of the alternatives that I have seen. When I'm editing code, I like to see the code and little else; I dislike lengthy comments in the code itself. When I'm reading code, however, I want to see it in the form displayed by annote, so that I have some chance of remembering what I was thinking when I wrote the code.
memory provides a debugging interface for malloc and free.
root provides code we want available everywhere. root.h is the first file included in every .c file.
file provides buffered, filtered text file input and output, and supports the manipulation of linked lists of lines of text.
filter provides a finite state machine filter stateFilter for processing lines during input and output by file.
cstring is a command line tool for converting a text file into an array of C strings. It demonstrates a simple use of file and filter.
rules specifies the finite state machines for filtering documentation.
dict generates HTML anchor elements linking identifiers with their definitions.
merge processes documentation files, merging source files and substituting documentation text for matching comments.
html handles file input and output, and calls merge to combine documentation .txt files with source files to form the .html documentation.
annote is a command line tool for creating annotated C source listings as HTML files. annote provides a main routine which handles command line arguments, and relies on html to do the work.
annote writes .html files from documentation .txt files, annotating and including source files as instructed. annote is most easily understood by browsing an example of its use, such as these .txt and .html files that document its own source code. These notes are an introduction to annote, and its source code.
HTML produced by annote invokes the style sheet style.css, which provides styles for the HTML elements <body>, <pre>, <samp>, <code>, <strong>, and the combinations <pre class=code>, <pre class=samp>, <code><a>, <samp><a>, and <strong><ul>. These styles can be changed by the user, by rewriting style.css.
The <body> element contains the document body.
The <code> and <pre class=code> elements denotes source code. The <pre> element denotes preformatted text. annote wraps blocks of included source code with these elements. Leading and trailing blank lines of the source code block are omitted, and runs of blank lines within source code are output as a single blank line.
The <samp> element denotes sample input or output. annote wraps documentation text found in double quotes " with this element, replacing the quotes. Escaped quotes \" are processed literally. Quoted text may extend over multiple lines.
The <a> element defines HTML anchors, naming locations in a document and creating links to these locations. style.css provides styles for the combinations <code><a> and <samp><a>, so links from C identifiers to their definitions can have a distinct look.
The <strong> element gives strong emphasis to its contents. annote wraps unmatched comment lines and other errors with this element.
The <ul> element defines an unordered list. The style sheet defines the combination <strong><ul> for convenience in manually writing to-do lists in the documentation.
A typical .txt file written for annote looks like
Notes before filename //@ filename Notes following link to filename // comment Notes to replace matching comment in filename //, identifier Description of \"identifier\", local to these files //. identifier Description of \"identifier\", global to all files //@ Notes after filename //@ filename2 Notes following link to filename2 /* comment */ Notes to replace matching comment in filename2
annote copies any initial text in an input .txt file to the body of the output .html file. When copying documentation text, annote encloses groups of nonblank lines in the <p> element, and transforms quoted passages into <samp> elements.
When annote encounters a line of the form //@ filename in the .txt file, it writes a link to this file in the output. If filename is not a .html file, then annote treats it as a source file, and enters merge mode for this source file.
In merge mode, any text in the .txt file preceding the next comment line is copied to the output. Then the source file is copied to the output, enclosed in <code><pre> elements. Any line whose initial nonblank characters are // or /* is handled as a comment line, which annote tries to match between the .txt file and the source file. In particular, C code should not follow a leading /* */ comment on the same line. Matching comment lines in the source file are replaced in the output by the documentation text that follows the corresponding comment line in the .txt file.
Any line whose initial nonblank characters are //, or /*, or //. or /*. is handled as above, and additionally creates an HTML header using the first nonblank characters of the comment, parsed as a C identifier. The header location is named by this same identifier using an HTML anchor element, and any occurrence of this identifier within <code> and <samp> elements is linked to this location.
//, and /*, indicate identifiers local to the current .html file, while //. and /*. indicate identifiers global to all files processed by this program execution. This linking pass for all files takes place after every file has been read, so identifiers that appear before their definition are correctly linked.
After the source file is copied to the output, annote resumes copying from the .txt file, beginning with the next line which starts with //@. This string may be used by itself to terminate merge mode.
When merge mode terminates for a given source file, annote copies the unmatched comments from the .txt file to the output, enclosed in <strong> elements and followed by the unmatched text. style.css styles <strong> elements to draw attention, suggesting that the enclosed text represents an error.
annote quotes special source characters within <code> and <samp> elements, replacing < by < and > by > and & by &. This takes place inside all <code> and <samp> elements, whether generated manually or by annote.
The elements <pre class=code> and <pre class=samp> are preformatted versions of <code> and <samp>; annote wraps source code in <pre class=code> elements.
<strong> elements are recognized within <pre class=code> and <pre class=samp> elements if they enclose entire lines. This is because annote highlights source comments it cannot match using <strong> elements.
Otherwise, there is no mechanism for disabling the quotation of <, >, and & within <code>, <samp>, <pre class=code>, and <pre class=samp> elements.
annote generates valid HTML 4.01 Strict output, and labels it as such. However, it passes along any HTML present in the .txt file, whether it is valid or not. annote also automatically marks paragraph elements, detecting certain block-level elements such as <ol>, <ul>, <pre>, and <table>; support for other block-level elements can easily be added to the code. However, annote can be fooled by unfamiliar or nested elements, such as nested lists. To temporarily disable automatic paragraph markup (and assume responsibility for paragraph markup), enclose the relevant section in the .txt file with the comments
<!-- par off --> ... <!-- par on -->
To validate the resulting HTML, one can use the validation service WDG HTML Validator.