Running Document on Unmodified Files

To reap the full benefits of using the Document package, one must make modifications to the source code files. However, there are situations where it is desireable to have some form of rudimentary documentation for a package that for some reason has unmodified source. For instance, it could be source that is not maintained by the person doing the documentation, or it could be the first attempt at using Document before making specialized modifications to the source.

Document provides two options that are useful in this situation, -verbatim and -headeronly . The -verbatim option outputs the entire contents of the file with no changes to standard out. The -headeronly option outputs only the header of the file, which is defined as every line until a non-comment line is reached. Additionally, both options will prepend and append the files .doc_header and .doc_footer if they exist. The .doc_header and .doc_footer files can contain the following strings which will have the correct values substituted in:

String	Substitution
doc_filename	The complete filename, without the directory.
doc_filename_base	The filename without any suffix, without the directory.
doc_dirname	The immediate directory name (not the full directory name, but only the directory name one level up from the input file).

The header and footer files may be configured for use with any formatting language. A common choice for the header and footer files for use with L^ATEX and L^ATEX2HTML is:

.doc_header:

  \subsection{doc_filename_base \label{doc_filename_base}}
  \index{doc_dirname!doc_filename}
  \begin{verbatim}

.doc_footer:

  \end{verbatim}

The desired options for processing the files (for example, the -verbatim or the -headeronly option) may be specified in a .doc_options file that is placed in the same directory.