Command Line Arguments

To use doctext, you need only to give it the name of the files to process:

 
doctext *.[ch] 

A complete list of the command line options follows. Some of these will be used often (e.g., -ext and -mpath); others are needed only in special cases (e.g., -outfile).

The choice of output format is selected with these switches:

-latex

Generate LaTeX output rather than man (nroff) format files.

-html

Generate HTML (WWW) output rather than man (nroff) format files.

The following options control some aspects of the appearance and content of the generated page, as well as the name of the output file.

-mpath path

Set the path where the man pages will be written.

-ext n

Set the extension (1-9,l, etc.). The default value is 3. This is the man page chapter and is used as the extension on the filename. For example, doctext creates the file Swap.3 for the Swap routine.

-heading name

Name for the heading (middle of top line). The default value is PETSc. This is used only for Unix man-page (nroff) format.

-nolocation

Suppress the generation of a line that indicates the source file that contained the structured comment.

-quotefmt

Enable the use of single quotes and back quotes to use code and emphasis fonts.

-dosnl

End every line with return-newline instead of just newline. This makes that file easier to read on Windows systems, and is quite helpful for HTML output.

-defn filename

Load the output definitions in file filename, in addition to the defaults.

-I filename

filename contains the public includes needed by these routines; it will automatically be added to the synopsis of the routines. The file should contain exactly the text to be added to the synopsis. For example, to specify that the include <stdio.h> be included, use a file with only the text #include <stdio.h> in it.

-index filename

Generate an index file appropriate for tohtml [(ref tohtml)] (for generating WWW files). This appends to any existing file; make sure that you don't add duplicate entries.

-indexdir dirname

Set the root directory for the index file entries. This allows you to specify an absolute URL for the generated files to be used in the generated index, for example,

 
-index foo.cit -indexdir "http:/www.mcs.anl.gov/home/gropp/man" 

-mapref filename

Use file filename as a source of names that should be automatically mapped to URLs. One source of a properly formatted mapref file is the output from doctext in the file specified with the -index filename command.

-outfile filename

Put the man pages in the indicated file. Normally, a separate file is created for each routine. This may be appropriate for HTML output. The output filename is normally made up of the name of the routine, followed by the extension (-ext n) for nroff, .tex for LaTeX, or .html for HTML files.

-keyword filename

Append the keywords (from .k commands) to the given file. If the filename is -, use standard output.

-skipprefix name

Set the characters to be skipped at the beginning of each line. The default is the empty string. Use

 
    -skipprefix C 

for Fortran 77 programs. You can use -skipprefix # for shell scripts and -skipprefix \! for Fortran 90 programs.

For example, with -skipprefix C, a Fortran program can use the D (not @) mode:

 
C/*D 
C fortranfoo - An example of using Fortran with doctext 
C 
C Input Parameters: 
C 
C+ foo - bar 
C. bar - stool 
C- stool - pidgeon 
CD*/ 
      function fortranfoo( foo, bar stool ) 
      integer foo, bar stool 
      end 

This option is new and has not been extensively tested.

-ignore name

Skip over name when processing a function definition. This is particularly useful when a special (non-standard) keyword is needed to build a dynamic link library (DLL) (e.g., Microsoft C/C++) or to simplify the construction of export lists (IBM's AIX). For example, say that EXPORT is used to indicate a routine that will be exported as part of a DLL. The source code then looks like

 
/*@ myroutine - a routine visible as part of a DLL 
 @*/ 
EXPORT void myroutine( int a ) 

Using the command line option -ignore EXPORT will cause doctext to skip the EXPORT keyword; the synopsis will contain only

 
    void myroutine( int a )