[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [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:

  1. always create itself, ignoring any ds-types by this name. These are marked, below, as ao-only.
  2. create, if none was provided. These are marked, alternate.
  3. create, but augment if the doc-section was provided. These are marked, augments.
  4. do nothing, but inserts them into the output in a prescribed order. These are marked, known
  5. 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

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

This document was generated by Bruce Korb on August 30, 2014 using texi2html 1.82.