Writing SPIN Documentation

21 May 1997

Overview

Providing clients with informative, well-written documentation is instrumental in expanding the popularity of SPIN. If cavemen cannot figure out how to write applications for SPIN, they will write applications for something else. They may even write entire operating systems for the Exokernel.

Structure

Sections of code are very different. Some are huge and critical to the entire system (e.g. Strands or Dispatcher), while others are small and provide only one service (e.g. External References). Accordingly, documentation will be very different. There is no concrete standard on how documentation should be formatted. This template is a rough guideline on what kind of information should appear in your documentation. The closer we adhere to this standard, the easier it will be to read.

The SPIN documentation tree is part of the source tree. This allows easy referencing of source code and other documentation without absolute path names (hence, the whole tree can be moved without updating links!). Please avoid URLs with absolute pathnames (e.g. use ../../src/Foo.i3 rather than file:/afs/cs/project/..../src/Foo.i3) whenever possible! Documentation is typically contained in a doc directory underneath or next to the src directory for the code being documented.

Tricks

Pathnames

There has been some interest in providing tools which simplify typing long relative pathnames. Several possibilities have been shot down for varying reasons. These include:

Filtering: Run a script over .html files which changes all occurrences of e.g. FULLTREE with the absolute pathname to the top of the source tree. The problem is what to do with filtered files. Create whole new copies? What happens if a filtered file accidentally gets checked in?
Directory of Links: Have a flat directory at the top level with links to all other files. The problem is that no two files represented in the link directory could have the same name.
Links in Each Doc Directory: Put a link to the top of the source tree in each doc directory. This would eliminate climbing up the tree with relative path names. The problem is that adding links to CVS is no trivial matter. A potential solution is to insert links in the build process (i.e. the documentation writer instruments the subdir Makefile to place a link to the toplevel in the doc directory).

Pretty Printing

SRC has a few tools which beautify Modula-3 code. At this time, the simplest to use is m3totex, which combined with latex2html can produce html code. (More info to come on using these. In the meantime, this sample .i3 file illustrates the Modula-3 coding style which m3totex assumes.) In my humble opinion, these tools are more trouble than they are worth. The Dispatcher documentation is a good example of incorporating code into documentation without any fancy tools.

Exporting Documentation

Occasionally it may be nice to extract documentation from the SPIN source tree and create a free-standing documentation tree. A tool to extract documentation is the Perl script /spin/bin/docexport.pl. docexport.pl copies all HTML files in doc directories from a SPIN source tree to a new directory. docexport.pl will also copy any source files linked to from these HTML files, as well as pictures in /projects/spin/www/pics and papers in /projects/spin/www/papers. The idea is to create a hierarchy of HTML files and supplementary files that is as self-contained as possible.

docexport.pl has several command-line options to control the documentation export:

-dir : directory in which to place the new documentation tree. The default is ./SPINDocs
-source : SPIN source directory from which to get docs. This should be a top-level spin directory. The default is the potato: /afs/cs/project/spin/build/merge/spin.
-nosrcfiles: disallow the export of .m3 and .c files. The default is to allow .m3 and .c files.
-exturl: allow references to external URLs (e.g. the Modula-3 home page at SRC). The default is to not allow external URLs.
-q: quiet mode. This will cause bad URL and other messages not to be displayed. The default is not quiet.
-h: print a message describing the command-line options.

docexport.pl has some limitations and features in parsing HTML:

It cannot yet parse references which span multiple lines. e.g.
```
    Click <a
    href="../../foo/doc/index.html">here</a> for more information.
```
This is unfortunate and largely a function of my poor Perl skills. It is on the queue to be fixed.
docexport.pl can be told to ignore entire HTML files as well as sections of certain files. In order to ignore an entire HTML file, place the following comment at the top:
```
    
```
In order to ignore a section of an HTML file, bracket the section with lines which have these comments:
```
    

    ... (ignored text) ...

    
```
This technique is crude, but I wrote it quickly and I wanted it to be blatantly obvious what was going on. To see an example of its use, view the source of spin/doc/index.html. The release notes and CVS notes are ignored because they are dependent on too many local file: links.
Pages which use latex2html icons pointing to the CSE Department default (http://www.cs.washington.edu/general/latex2html_icons/...) will be switched to use icons in the SPIN documentation tree. This makes the documentation more self-contained, and improves the presentation of documents when external URLs are not allowed.
Unfortunately, docexport.pl cannot be run reliably on only a subdirectory of SPIN documentation (e.g. to test you documentation to make sure it is parseable). Many documentation files use relative paths that assume the presence of the entire source directory structure.
docexport.pl will parse all HTML files under all doc directories in the soruce tree. It performs no reachability tests before parsing an HTML files. Thus, even if the link to an HTML file is explicitly ignored, or if the file is obsolete and no longer pointed to, it will be parsed and errors will be reported. This is okay, because if the file is unreachable than the errors will not be noticed in the exported documentation, but it's still annoying. The solution for obsolete files is to remove them from the tree!

ddion@cs.washington.edu