GNU AutoGen - The Automated Program Generator: 7.5.9 Man and Info doc Attributes

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

### 7.5.9 Man and Info doc Attributes

AutoOpts includes AutoGen templates for producing abbreviated man pages and for producing the invoking section of an info document. To take advantage of these templates, you must add several attributes to your option definitions.

‘`arg-name`’

  If an option has an argument, the argument should have a name for documentation purposes. It will default to `arg-type`, but it will likely be clearer with something else like, `file-name` instead of `string` (the type).

‘`doc`’

  First, every `flag` definition other than “documentation” definitions, must have a `doc` attribute defined. If the option takes an argument, then it will need an `arg-name` attribute as well. The `doc` text should be in plain sentences with minimal formatting. The Texinfo commands `@code`, and `@var` will have its enclosed text made into \fB entries in the man page, and the `@file` text will be made into \fI entries. The `arg-name` attribute is used to display the option’s argument in the man page.

  Options marked with the “documentation” attribute are for documenting the usage text. All other options should have the “doc” attribute in order to document the usage of the option in the generated man pages.

‘`man-doc`’

  Finally, if you need to add man page sections like `SEE ALSO` or `USAGE` or other, put that text in a `man-doc` definition. This text will be inserted verbatim in the man page after the `OPTIONS` section and before the `AUTHOR` section.

‘`option-info`’

  This text will be inserted as a lead-in paragraph in the `OPTIONS` section of the generated man page.

‘`doc-section`’

  This is a compound attribute that requires three subattributes:

  ds-type

    This describes the section type. This is for use in man pages.

  ds-format

    This describes the format of the associated `ds-text` section. `man`, `mdoc` and `texi` formats are supported.

  ds-text

    This is the descriptive text, written according to the rules for `ds-format` documents.

      doc-section = {
        ds-type   = 'SEE ALSO'; // or anything else
        ds-format = 'man';      // or texi or mdoc format
        ds-text   = <<-_EOText_
      	text relevant to this section type,
      	in the chosen format
      	_EOText_;
      };

‘`prog-man-descrip`’
‘`prog-info-descrip`’

  These attributes are now deprecated. Please use `doc-section` stanzas.

  Then, you need to supply a brief description of what your program does. If you already have a `detail` definition, this may be sufficient. If not, or if you need special formatting for one of the manual formats, then you will need either a definition for `prog-man-descrip` or `prog-info-descrip` or both. These will be inserted verbatim in the man page document and the info document, respectively.

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

This document was generated by Bruce Korb on March 7, 2011 using texi2html 1.82.