[ < ] [ > ]   [ << ] [ 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 February 17, 2011 using texi2html 1.82.

Viewable With Any Browser   autogen Home