global option attributes (GNU AutoGen - The Automated Program Generator)

Previous: Per option documentation attributes, Up: Man and Info doc Attributes [Contents][Index]

7.5.9.2 Global documentation attributes ¶

‘cmd-section’ ¶

If your command is a game or a system management command, specify this attribute with the value 5 or 8, respectively. The default is a user command (section 1).

‘detail’ ¶

This attribute is used to add a very short explanation about what a program is used for when the title attribute is insufficient. If there is no doc-section stanza of type DESCRIPTION, then this text is used for the man page DESCRIPTION section, too.

‘addtogroup’ ¶

This attribute tells the template that the generated code should be surrounded with the following doxygen comments:

/** @file <header-or-code-file-name>
 *  @addtogroup <value-of-addtogroup>
 *  @{
 */

and

/** @} */

‘option-format’ ¶

Specify the default markup style for the doc stanzas. By default, it is texi, but man and mdoc may also be selected. There are nine converter programs that do a partial job of converting one form of markup into another. texi2texi, man2man and mdoc2mdoc work pretty well.

You may also post process the document by using doc-sub stanzas, see below.

‘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-format

This describes the format of the associated ds-text section. man, mdoc and texi formats are supported. Regardless of the chosen format, the formatting tags in the output text will be converted to man macros for man pages, mdoc macros for mdoc pages, and texi macros for texinfo pages.

ds-text

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

ds-type

This describes the section type. Basically, the title of the section that will be added to all output documentation. There may be only one doc-section for any given ds-type. If there are duplicates, the results are undefined (it might work, it might not).

There are five categories of ds-type sections. They are those that the documentation templates would otherwise:

always create itself, ignoring any ds-types by this name. These are marked, below, as ao-only.
create, if none was provided. These are marked, alternate.
create, but augment if the doc-section was provided. These are marked, augments.
do nothing, but inserts them into the output in a prescribed order. These are marked, known
knows nothing about them. They will be alphabetized and inserted after the list of leading sections and before the list of trailing sections. These are not marked because I don’t know their names.

Some of these are emitted by the documentation templates only if certain conditions are met. If there are conditions, they are explained below. If there are no conditions, then you will always see the named section in the output.

The output sections will appear in this order:

‘NAME’: ao-only.
‘SYNOPSIS’: alternate.
‘DESCRIPTION’: augments.
‘OPTIONS’: ao-only.
‘OPTION PRESETS’: ao-only, if environment presets or configuration file processing has been specified.
‘unknown’: At this point, the unknown, alphabetized sections are inserted.
‘IMPLEMENTATION NOTES’: known
‘ENVIRONMENT’: augments, if environment presets have been specified.
‘FILES’: augments, if configuration file processing has been specified.
‘EXAMPLES’: known
‘EXIT STATUS’: augments.
‘ERRORS’: known
‘COMPATIBILITY’: known
‘SEE ALSO’: known
‘CONFORMING TO’: known
‘HISTORY’: known
‘AUTHORS’: alternate, if the copyright stanza has either an author or an owner attribute.
‘COPYRIGHT’: alternate, if there is a copyright stanza.
‘BUGS’: augments, if the copyright stanza has an eaddr attribute.
‘NOTES’: augments.

Here is an example of a doc-section for a SEE ALSO type.

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_;
};

‘doc-sub’ ¶

This attribute will cause the resulting documentation to be post-processed. This is normally with sed, see doc-sub-cmd below. This attribute has several sub-attributes:

‘sub-name’: This is the name of an autogen text definition value, like prog-name or version. In the sub-text field, occurrences of this name preceded by two less than characters and followed by two greater than characters will be replaced by the text value of the definition, e.g. ‘<<prog-name>>’.
‘sub-text’: The text that gets added to the command file for the post processing program.
‘sub-type’: If this command only applies to certain types of output, specify this with a regular expression that will match one of the valid output format types, e.g. ‘man|mdoc’ will match those two kinds, but not texi output. If omitted, it will always apply.

For example, if you want to reference the program name in the doc text for an option common to two programs, put ‘#PROG#’ into the text. The following will replace all occrrences of ‘#PROG#’ with the current value for prog:

doc-sub = {
  sub-name = prog-name;
  sub-text = 's/#PROG#/<<prog-name>>/g';
};

‘doc-sub-cmd’ ¶

A formatting string for constructing the post-processing command. The first parameter is the name of the file with editing commands in it, and the second is the file containing the unprocessed document. The default value is:

sed -f %s %s