/usr/share/doc/autogen-doc/autogen.html/global-option-attributes.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for GNU AutoGen version 5.18, updated December 2015.

Copyright (C) 1992-2015 by Bruce Korb.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- Created by GNU Texinfo 6.0, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU AutoGen - The Automated Program Generator: global option attributes</title>

<meta name="description" content="GNU AutoGen - The Automated Program Generator: global option attributes">
<meta name="keywords" content="GNU AutoGen - The Automated Program Generator: global option attributes">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="AutoOpts.html#AutoOpts" rel="index" title="AutoOpts">
<link href="Function-Index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="documentation-attributes.html#documentation-attributes" rel="up" title="documentation attributes">
<link href="automatic-options.html#automatic-options" rel="next" title="automatic options">
<link href="per-option-attributes.html#per-option-attributes" rel="prev" title="per option attributes">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space: nowrap}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: serif; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="global-option-attributes"></a>
<div class="header">
<p>
Previous: <a href="per-option-attributes.html#per-option-attributes" accesskey="p" rel="prev">per option attributes</a>, Up: <a href="documentation-attributes.html#documentation-attributes" accesskey="u" rel="up">documentation attributes</a> &nbsp; [<a href="Function-Index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AutoOpts.html#AutoOpts" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Global-documentation-attributes"></a>
<h4 class="subsubsection">7.5.9.2 Global documentation attributes</h4>
<dl compact="compact">
<dt>&lsquo;<samp>cmd-section</samp>&rsquo;</dt>
<dd><a name="index-cmd_002dsection"></a>
<p>If your command is a game or a system management command,
specify this attribute with the value <code>5</code> or <code>8</code>, respectively.
The default is a user command (section 1).
</p>
</dd>
<dt>&lsquo;<samp>detail</samp>&rsquo;</dt>
<dd><a name="index-detail-1"></a>
<p>This attribute is used to add a very short explanation about what
a program is used for when the <code>title</code> attribute is insufficient.
If there is no <code>doc-section</code> stanza of type <code>DESCRIPTION</code>, then
this text is used for the man page DESCRIPTION section, too.
</p>
</dd>
<dt>&lsquo;<samp>addtogroup</samp>&rsquo;</dt>
<dd><a name="index-addtogroup"></a>
<p>This attribute tells the template that the generated code should be
surrounded with the following doxygen comments:
</p><div class="example">
<pre class="example">/** @file &lt;header-or-code-file-name&gt;
 *  @addtogroup &lt;value-of-addtogroup&gt;
 *  @{
 */
</pre></div>
<p>and
</p><div class="example">
<pre class="example">/** @} */
</pre></div>

</dd>
<dt>&lsquo;<samp>option-format</samp>&rsquo;</dt>
<dd><a name="index-option_002dformat"></a>
<p>Specify the default markup style for the <code>doc</code> stanzas.
By default, it is <code>texi</code>, but <code>man</code> and <code>mdoc</code> may
also be selected.  There are nine converter programs that do a partial
job of converting one form of markup into another.  <code>texi2texi</code>,
<code>man2man</code> and <code>mdoc2mdoc</code> work pretty well.
</p>
<p>You may also post process the document by using <code>doc-sub</code> stanzas,
see below.
</p>
</dd>
<dt>&lsquo;<samp>option-info</samp>&rsquo;</dt>
<dd><a name="index-option_002dinfo"></a>
<p>This text will be inserted as a lead-in paragraph in the <code>OPTIONS</code>
section of the generated man page.
</p>
</dd>
<dt>&lsquo;<samp>doc-section</samp>&rsquo;</dt>
<dd><a name="index-doc_002dsection"></a>
<p>This is a compound attribute that requires three <i>sub</i>attributes:
</p>
<dl compact="compact">
<dt><i>ds-format</i></dt>
<dd><p>This describes the format of the associated <code>ds-text</code> section.
<code>man</code>, <code>mdoc</code> and <code>texi</code> formats are supported.
Regardless of the chosen format, the formatting tags in the output
text will be converted to <code>man</code> macros for <code>man</code> pages,
<code>mdoc</code> macros for <code>mdoc</code> pages, and <code>texi</code> macros for
<code>texinfo</code> pages.
</p>
</dd>
<dt><i>ds-text</i></dt>
<dd><p>This is the descriptive text, written according to the rules for
<code>ds-format</code> documents.
</p>
</dd>
<dt><i>ds-type</i></dt>
<dd><p>This describes the section type.  Basically, the title of the section
that will be added to all output documentation.  There may be only one
<code>doc-section</code> for any given <code>ds-type</code>.  If there are duplicates,
the results are undefined (it might work, it might not).
</p>
<p>There are five categories of <code>ds-type</code> sections.
They are those that the documentation templates would otherwise:
</p><ol>
<li> always create itself, ignoring any <code>ds-type</code>s by this name.
These are marked, below, as <code>ao-only</code>.
</li><li> create, if none was provided.
These are marked, <code>alternate</code>.
</li><li> create, but augment if the <code>doc-section</code> was provided.
These are marked, <code>augments</code>.
</li><li> do nothing, but inserts them into the output in a prescribed order.
These are marked, <code>known</code>
</li><li> 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&rsquo;t know their names.
</li></ol>

<p>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.
</p>
<p>The output sections will appear in this order:
</p><dl compact="compact">
<dt>&lsquo;<samp>NAME</samp>&rsquo;</dt>
<dd><p><code>ao-only</code>.
</p></dd>
<dt>&lsquo;<samp>SYNOPSIS</samp>&rsquo;</dt>
<dd><p><code>alternate</code>.
</p></dd>
<dt>&lsquo;<samp>DESCRIPTION</samp>&rsquo;</dt>
<dd><p><code>augments</code>.
</p></dd>
<dt>&lsquo;<samp>OPTIONS</samp>&rsquo;</dt>
<dd><p><code>ao-only</code>.
</p></dd>
<dt>&lsquo;<samp>OPTION PRESETS</samp>&rsquo;</dt>
<dd><p><code>ao-only</code>, if environment presets or configuration file processing
has been specified.
</p></dd>
<dt>&lsquo;<samp>unknown</samp>&rsquo;</dt>
<dd><p>At this point, the unknown, alphabetized sections are inserted.
</p></dd>
<dt>&lsquo;<samp>IMPLEMENTATION NOTES</samp>&rsquo;</dt>
<dd><p><code>known</code>
</p></dd>
<dt>&lsquo;<samp>ENVIRONMENT</samp>&rsquo;</dt>
<dd><p><code>augments</code>, if environment presets have been specified.
</p></dd>
<dt>&lsquo;<samp>FILES</samp>&rsquo;</dt>
<dd><p><code>augments</code>, if configuration file processing has been specified.
</p></dd>
<dt>&lsquo;<samp>EXAMPLES</samp>&rsquo;</dt>
<dd><p><code>known</code>
</p></dd>
<dt>&lsquo;<samp>EXIT STATUS</samp>&rsquo;</dt>
<dd><p><code>augments</code>.
</p></dd>
<dt>&lsquo;<samp>ERRORS</samp>&rsquo;</dt>
<dd><p><code>known</code>
</p></dd>
<dt>&lsquo;<samp>COMPATIBILITY</samp>&rsquo;</dt>
<dd><p><code>known</code>
</p></dd>
<dt>&lsquo;<samp>SEE ALSO</samp>&rsquo;</dt>
<dd><p><code>known</code>
</p></dd>
<dt>&lsquo;<samp>CONFORMING TO</samp>&rsquo;</dt>
<dd><p><code>known</code>
</p></dd>
<dt>&lsquo;<samp>HISTORY</samp>&rsquo;</dt>
<dd><p><code>known</code>
</p></dd>
<dt>&lsquo;<samp>AUTHORS</samp>&rsquo;</dt>
<dd><p><code>alternate</code>, if the <code>copyright</code> stanza has either
an <code>author</code> or an <code>owner</code> attribute.
</p></dd>
<dt>&lsquo;<samp>COPYRIGHT</samp>&rsquo;</dt>
<dd><p><code>alternate</code>, if there is a <code>copyright</code> stanza.
</p></dd>
<dt>&lsquo;<samp>BUGS</samp>&rsquo;</dt>
<dd><p><code>augments</code>, if the <code>copyright</code> stanza has an
<code>eaddr</code> attribute.
</p></dd>
<dt>&lsquo;<samp>NOTES</samp>&rsquo;</dt>
<dd><p><code>augments</code>.
</p></dd>
</dl>
</dd>
</dl>

<p>Here is an example of a <code>doc-section</code> for a <code>SEE ALSO</code> type.
</p>
<div class="example">
<pre class="example">doc-section = {
  ds-type   = 'SEE ALSO'; // or anything else
  ds-format = 'man';      // or texi or mdoc format
  ds-text   = &lt;&lt;-_EOText_
	text relevant to this section type,
	in the chosen format
	_EOText_;
};
</pre></div>

</dd>
<dt>&lsquo;<samp>doc-sub</samp>&rsquo;</dt>
<dd><a name="index-doc_002dsub"></a>
<p>This attribute will cause the resulting documentation to be post-processed.
This is normally with <code>sed</code>, see <code>doc-sub-cmd</code> below.
This attribute has several sub-attributes:
</p>
<dl compact="compact">
<dt>&lsquo;<samp>sub-name</samp>&rsquo;</dt>
<dd><p>This is the name of an autogen text definition value, like <code>prog-name</code>
or <code>version</code>.  In the <code>sub-text</code> 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. &lsquo;<samp>&lt;&lt;prog-name&gt;&gt;</samp>&rsquo;.
</p>
</dd>
<dt>&lsquo;<samp>sub-text</samp>&rsquo;</dt>
<dd><p>The text that gets added to the command file for the post processing
program.
</p>
</dd>
<dt>&lsquo;<samp>sub-type</samp>&rsquo;</dt>
<dd><p>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. &lsquo;<samp>man|mdoc</samp>&rsquo; will match those two kinds,
but not <code>texi</code> output.  If omitted, it will always apply.
</p></dd>
</dl>

<p>For example, if you want to reference the program name in the <code>doc</code>
text for an option common to two programs, put &lsquo;<samp>#PROG#</samp>&rsquo; into the
text.  The following will replace all occrrences of &lsquo;<samp>#PROG#</samp>&rsquo;
with the current value for <code>prog</code>:
</p><div class="example">
<pre class="example">doc-sub = {
  sub-name = prog-name;
  sub-text = 's/#PROG#/&lt;&lt;prog-name&gt;&gt;/g';
};
</pre></div>

</dd>
<dt>&lsquo;<samp>doc-sub-cmd</samp>&rsquo;</dt>
<dd><a name="index-doc_002dsub_002dcmd"></a>
<p>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:
</p><div class="example">
<pre class="example">sed -f %s %s
</pre></div>
</dd>
</dl>

<hr>
<div class="header">
<p>
Previous: <a href="per-option-attributes.html#per-option-attributes" accesskey="p" rel="prev">per option attributes</a>, Up: <a href="documentation-attributes.html#documentation-attributes" accesskey="u" rel="up">documentation attributes</a> &nbsp; [<a href="Function-Index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AutoOpts.html#AutoOpts" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
autogen-doc 1:5.18.7-3 / usr / share / doc / autogen-doc / autogen.html / global-option-attributes.html
