Generating Documentation

The Opal Compilation System contains support for generating documentation in either HTML or DVI format from the source code. The full documentation gives details for the operation of the documentation system DOSFOP. This document gives a short introduction into the usage of the documentation system.

Adding Documentation to the Source Code

Documentation is included in the form of special comments. Every comment which starts with a percent (`%') sign is treated as a comment. Source code is written in Texinfo (the same language which is used for the documentation of many GNU tools, e.g. emacs, gcc, ...). The most important Texinfo commands are:

@@, @{, @} The only special characters are `@' (at sign), `{' and `}' (curly braces) which must be preceded by @ (at sign). All other characters are included literally.
@code{text} is used for references to identifiers from the source code.
@emph{text} is used to emphasize text.
@ref{@Overview{structure name}} inserts a (hyper-)link to the documentation of structure name.

Generating Documentation with ocs

The ocs command knows several targets for generating documentation. Some preparation is necessary, though:

If you have used the ocs -top or ocs -sub command, create a link from the generated SysDefs file to a file just named `SysDefs'
Define an environment variable PROJECTROOT which contains the absolute path to the directory where the Opal sources are located.

Then use one of

ocs doc to generate HTML documentation
ocs dvi to generate DVI documentation

The result is placed in doc/out.html or doc/out.dvi.

If you use bash, type

-> export PROJECTROOT=$PWD
-> ocs doc

If you use csh or tcsh, type

-> setenv PROJECTROOT $PWD
-> ocs doc

The Opal Group

Last modified: Thu Sep 16 21:37:15 MEST 1999