File Format

The idea behind the Document package is that all documentation keywords are placed in the comments of the source code document being processed. The source code can then be processed by the compiler or interpreter without additional changes. The Document keywords instruct the Document package how to extract documentation from the source code file without affecting the operation of the source code file itself.

Document keywords are different for each command line option that is specified. In this description, the Document keywords for the default options (-generic and -fortran) will be used, with the name of the perl list variable for the specific keyword in parantheses. For the values of the keywords for other options, consult the Coding Details section.

To start the documentation process, enter the Begin_Doc (start_documentation) keyword, on a line by itself, in the comments of the file:

  c This line of text will not be in the documentation file.
  c Begin_Doc
  c This line of text will be entered into the documentation file.

To terminate the documentation process, enter the End_Doc (end_documentation) keyword, on a line by itself, in the comments of the file:

  c This line of text will be entered into the documentation file.
  c End_Doc 
  c This line of text will not be in the documentation file.

The format given above will send the documentation output to standard output. An optional filename may be appended to the Begin_Doc keyword to redirect output. This filename will be valid only for the current documentation block. If the same filename is specified more than once, the first specification will open the file and subsequent specifications will append to the file. This feature can be used to change the order of input for the documentation, as is shown in this example:

  c Begin_Doc main.tex
  c % Note that the order of files a.tex and b.tex has been switched.
  c \input{b}
  c \input{a}
  c End_Doc
  c
  c Begin_Doc a.tex
  c This line is in file a.tex.
  c End_Doc
  c
  c Begin_Doc b.tex
  c This line is in file b.tex.
  c End_Doc
  c
  c Begin_Doc a.tex
  c This line is appended to file a.tex.
  c End_Doc

The default documentation mode removes the comment characters from the documentation before printing. For Fortran, the comment character keywords (comment_characters) are either a ``c'' or whitespace and an exclamation point (``!'') at the beginning of the line. In-line comments with coding followed by an exclamation point and a comment are not modified. For example, in the default documentation mode these lines:

  c Begin_Doc
  c 
  c Comment.
  c 
        ! Bang-style comment.
         do i = 1, 10
           a(i) = i**2  ! In-line comment
         end do
  c End_Doc

would appear like this in the output:

   
   Comment.
   
   Bang-style comment.
         do i = 1, 10
           a(i) = i**2  ! In-line comment
         end do

To stop the removal of comment character keywords from the output (i.e. to leave lines unmodified), surround the text with the Begin_Verbatim (start_verbatim) keyword, on a line by itself, and the End_Verbatim (end_verbatim) keyword, on a line by itself, in the comments of the file:

  c Begin_Doc
  c These lines will have
  c their comment characters removed
  c
  c \begin{verbatim}
  c Begin_Verbatim
  c
  c But these lines won't.
  c
  c End_Verbatim
  c \end{verbatim}
  c End_Doc

which will appear as follows in the output:

   These lines will have
   their comment characters removed
  
   \begin{verbatim}
  c
  c But these lines won't.
  c
   \end{verbatim}

Notice the use of the L^ATEX verbatim environment on the outside of the Document verbatim keywords. This is a common construct for situations where quoting code and preserving the comments is desired.

Two last Document keywords are always_print and never_print. If any line is found with either of these keywords (even if there are other things on the line), the specified action will be taken. The never_print keyword takes precedence, and is primarily used for the self-documentation option (see the Self-Documentation section). For always_print, comments will be stripped off unless currently inside a verbatim environment. always_print is not used with either the -generic or -fortran options.