[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.14 Automated Man Pages

AutoOpts provides two templates for producing man pages. The command (‘man1’) pages are derived from the options definition file, and the library (‘man3’) pages are derived from stylized comments (see section Invoking getdefs).

Man pages include a date in the footer. By default, this is derived from the current date. However, this may be overridden with the MAN_PAGE_DATE environment variable. If set and not empty, its contents will be copied into where the output of date '+%d %b %Y' would otherwise go.

Man pages may be formatted as either traditional man pages or using mdoc formatting. The format is selected by selecting the appropriate template.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.14.1 command line man pages

Man pages for commands are documented using the ‘agman-cmd.tpl’ and ‘agmdoc-cmd.tpl’ templates. If the options specify pulling information from ‘RC’/‘ini’/‘cfg’ files, then you may use the ‘rc-sample.tpl’ template to produce an example config file for your program.

Using the option definitions for an AutoOpts client program, the ‘agman-cmd.tpl’ template will produce an nroff document suitable for use as a ‘man(1)’ page document for a command line command. The description section of the document is either the ‘prog-man-descrip’ text, if present, or the ‘detail’ text.

Each option in the option definitions file is fully documented in its usage. This includes all the information documented above for each option (see section Option Attributes), plus the ‘doc’ attribute is appended. Since the ‘doc’ text is presumed to be designed for texinfo documentation, sed is used to convert some constructs from texi to nroff-for-man-pages. Specifically,

 
convert @code, @var and @samp into \fB...\fP phrases
convert @file into \fI...\fP phrases
Remove the '@' prefix from curly braces
Indent example regions
Delete the example commands
Replace ‘end example’ command with ".br"
Replace the ‘@*’ command with ".br"

This document is produced by invoking the following command:

 
autogen -L ${prefix}/share/autogen -Tagman-cmd.tpl options.def

Where ‘${prefix}’ is the AutoGen installation prefix and ‘options.def’ is the name of your product’s option definition file. I do not use this very much, so any feedback or improvements would be greatly appreciated.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.14.2 library man pages

Man pages for libraries are documented using the ‘agman3.tpl’ template.

Two global definitions are required, and then one library man page is produced for each export_func definition that is found. It is generally convenient to place these definitions as ‘getdefs’ comments (see section Invoking getdefs) near the procedure definition, but they may also be a separate AutoGen definitions file (see section Definitions File). Each function will be cross referenced with their sister functions in a ‘SEE ALSO’ section. A global see_also definition will be appended to this cross referencing text.

The two global definitions required are:

libraryThis is the name of your library, without the ‘lib’ prefix. The AutoOpts library is named ‘libopts.so...’, so the library attribute would have the value opts.
headerGenerally, using a library with a compiled program entails #include-ing a header file. Name that header with this attribute. In the case of AutoOpts, it is generated and will vary based on the name of the option definition file. Consequently, ‘your-opts.h’ is specified.

The export_func definition should contain the following attributes:

nameThe name of the procedure the library user may call.
whatA brief sentence describing what the procedure does.
docA detailed description of what the procedure does. It may ramble on for as long as necessary to properly describe it.
errA short description of how errors are handled.
ret_typeThe data type returned by the procedure. Omit this for void procedures.
ret_descDescribe what the returned value is, if needed.
privateIf specified, the function will not be documented. This is used, for example, to produce external declarations for functions that are not available for public use, but are used in the generated text.
argThis is a compound attribute that contains:
arg_typeThe data type of the argument.
arg_nameA short name for it.
arg_descA brief description.

As a ‘getdefs’ comment, this would appear something like this:

 
/*=--subblock=arg=arg_type,arg_name,arg_desc =*/
/*=*
 * library: opts
 * header:  your-opts.h
=*/
/*=export_func optionProcess
 *
 * what: this is the main option processing routine
 * arg:  + tOptions* + pOpts + program options descriptor +
 * arg:  + int       + argc  + program arg count  +
 * arg:  + char**    + argv  + program arg vector +
 * ret_type:  int
 * ret_desc:  the count of the arguments processed
 *
 * doc:  This is what it does.
 * err:  When it can't, it does this.
=*/

Note the subblock and library comments. subblock is an embedded ‘getdefs’ option (see getdefs subblock) that tells it how to parse the arg attribute. The library and header entries are global definitions that apply to all the documented functions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.