Once the source code with the documentation imbedded in the comments has been produced, it can be processed by Document in any of the following ways:
% Document [options and files] > outfile % cat file1 [file2, etc.] | Document [options] > outfile
The options and files may be in any order on the command line. The files are processed in the command line order. The available options are:
Option | Meaning |
-blanks=number | The number of blanks to match and remove after comment keywords. The default is one. |
-dir=dirname | Output any named files to the specified directory. |
-headeronly | Ignore any Document keywords in the file and output the file header only, verbatim, to standard out. The file header consists of all lines that are comment lines at the beginning of a file - the first non-commented line marks the end. If there are files named .doc_header and .doc_footer located in the current directory, they will be prepended and appended to the output. See the Unmodified Files section for more information. |
-self | Use the self-documentation mode which extracts a shell script from the file and runs it. Note that a source code language must still be specified (or defaulted) so that the proper comment characters are used. |
-selftest | Use the self-test mode which extracts a shell script from the file and runs it. This is a synonym for the -self flag. |
-silent | Do not output anything to STDERR. This includes informational output. Also, do not query the user for verification before executing scripts. |
-verbatim | Ignore any Document keywords in the file and output the entire file, verbatim, to standard out. If there are files named .doc_header and .doc_footer located in the current directory, they will be prepended and appended to the output. See the Unmodified Files section for more information. |
The Document package can be used with any formatting language, and can be easily extended to other source code languages.
If an option is specified for the source code language on the command line, then it applies to all of the files being processed. If no source code language option is given on the command line, then the first twenty lines of each file are checked for a line containing:
Document options: [options]
which will specify options for that file only. If the source code language is still undefined, then the directory that contains the input file is searched for a file named .doc_options, which contains a single line with only the desired options. If the source code language is still undefined, the suffix of the file type will be checked for matches with defined suffix types for each source code language:
Source Code Language | File Suffixes |
C++ | .C, .cc, .c, .H, .hh, .Cpp, .cpp, .hxx, .cxx |
Fortran | .F, .f, .h, .F90, .FCM, .inc, .fm4 |
Java | .java |
LATEX | .tex |
M4 | .m4, .gm4 |
Prolog | .ari, .pro, .nl |
Shell | .awk, .pl, .perl, .sed, .tcl, no suffix |
If the source code language is still undefined, then it will default to -fortran.
Michael L. Hall