Running the Script

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:

Source Language and Formatting Language Options

Option Language Meaning
-c++ Source Code Use comment characters and other commands suitable for processing a C++ or C source code file.
-generic Formatting Use verbatim definitions and other commands suitable for processing a file with generically formatted comments. This is the default (and recommended) setting. It is required if comment characters are to be stripped off of verbatim environments.
-fortran Source Code Use comment characters and other commands suitable for processing a Fortran source code file.
-java Source Code Use comment characters and other commands suitable for processing a Java source code file.
-latex Source Code Use comment characters and other commands suitable for processing a LATEX source code file.
-m4 Source Code Use comment characters and other commands suitable for processing an m4 source code file.
-prolog Source Code Use comment characters and other commands suitable for processing a Prolog source code file.
-shell Source Code Use comment characters and other commands suitable for processing a shell script (csh, sh, awk, perl).

General Options

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