Command Line Arguments

Up: Contents Next: Man Pages for Hypertext Documents Previous: Other Formatting Options

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

doctext *.[ch] 
Command-line options to doctext allow you to change the details of how doctext generates output.

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:

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

If neither of these is used, the output is in man (nroff) format.

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.
Suppress the generation of a line that indicates the source file that contained the structured comment.
Enable the use of single quotes and back quotes to use code and emphasis fonts.
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.

The following options control the generation of additional data about HTML-format output that may be used by other programs to automatically generate links to the files created by doctext.
-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:/" 
-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.

The following options control the output filenames and the list of files to process.
-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.

The following options control the input format of the file, allowing doctext to be used with documentation in source files for Fortran or shell scripts.
-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 fortranfoo - An example of using Fortran with doctext 
C Input Parameters: 
C+ foo - bar 
C. bar - stool 
C- stool - pidgeon 
      function fortranfoo( foo, bar stool ) 
      integer foo, bar stool 
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 ) 

After the command-line arguments come the names of the files from which documents are to be extracted.

Up: Contents Next: Man Pages for Hypertext Documents Previous: Other Formatting Options