[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
www/software/help2man help2man.html
|
From: |
Karl Berry |
|
Subject: |
www/software/help2man help2man.html |
|
Date: |
Thu, 2 Jul 2020 17:59:28 -0400 (EDT) |
CVSROOT: /web/www
Module name: www
Changes by: Karl Berry <karl> 20/07/02 17:59:27
Modified files:
software/help2man: help2man.html
Log message:
help2man update from bod
CVSWeb URLs:
http://web.cvs.savannah.gnu.org/viewcvs/www/software/help2man/help2man.html?cvsroot=www&r1=1.16&r2=1.17
Patches:
Index: help2man.html
===================================================================
RCS file: /web/www/www/software/help2man/help2man.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -b -r1.16 -r1.17
--- help2man.html 12 Apr 2014 12:40:57 -0000 1.16
+++ help2man.html 2 Jul 2020 21:59:26 -0000 1.17
@@ -1,459 +1,439 @@
<!--#include virtual="/server/header.html" -->
-<!-- Parent-Version: 1.77 -->
+<!-- Parent-Version: 1.92 -->
+<!-- This page is derived from /server/standards/boilerplate.html -->
+
<title>help2man - GNU Project - Free Software Foundation</title>
<!--#include virtual="/server/gnun/initial-translations-list.html" -->
<!--#include virtual="/server/banner.html" -->
-<h2 class="settitle">`help2man' Reference Manual</h2>
-<a name="Top"></a>
-<h3 class="unnumbered"><samp><span class="command">help2man</span></samp></h3>
+<h2 class="settitle" align="center"><code>help2man</code> Reference Manual</h2>
-<p><samp><span class="command">help2man</span></samp> produces simple manual
-pages from the ‘<samp><span class="samp">--help</span></samp>’ and
-‘<samp><span class="samp">--version</span></samp>’ output of other
-commands.</p>
-<p><a name="Overview"></a></p>
-<h3 class="chapter">Overview of <samp><span
class="command">help2man</span></samp></h3>
-<p><samp><span class="command">help2man</span></samp> is a tool for
-automatically generating simple manual pages from program output.</p>
-<p>Although manual pages are optional for GNU programs other projects, such as
-Debian require them (see <a
-href="http://www.gnu.org/prep/standards/standards.html#Man-Pages";>Man
-Pages</a>)</p>
+<span id="SEC_Contents"></span>
+<h3 class="contents-heading">Table of Contents</h3>
-<p>This program is intended to provide an easy way for software authors
-to include a manual page in their distribution without having to
-maintain that document.</p>
+<div class="contents">
-<p>Given a program which produces reasonably standard ‘<samp><span
-class="samp">--help</span></samp>’ and ‘<samp><span
-class="samp">--version</span></samp>’ outputs, <samp><span
-class="command">help2man</span></samp> can re-arrange that output into
something
-which resembles a manual page.</p>
+<ul>
+ <li><a id="toc-Overview-of-help2man" href="#Overview">Overview of
<code>help2man</code></a></li>
+ <li><a id="toc-How-to-Run-help2man" href="#Invoking-help2man">How to Run
<code>help2man</code></a></li>
+ <li><a id="toc-_002d_002dhelp-Recommendations"
href="#g_t_002d_002dhelp-recommendations"><samp>--help</samp>
Recommendations</a></li>
+ <li><a id="toc-Including-Additional-Text-in-the-Output"
href="#Including-text">Including Additional Text in the Output</a></li>
+ <li><a id="toc-Using-help2man-With-make" href="#Makefile-usage">Using
<code>help2man</code> With <code>make</code></a></li>
+ <li><a id="toc-Producing-Native-Language-Manual-Pages"
href="#Localised-man-pages">Producing Native Language Manual Pages</a>
+ <ul>
+ <li><a id="toc-Changing-the-Location-of-Message-Catalogs"
href="#Changing-the-Location-of-Message-Catalogs">Changing the Location of
Message Catalogs</a></li>
+ </ul></li>
+ <li><a id="toc-Example-help2man-Output" href="#Example">Example
<code>help2man</code> Output</a></li>
+ <li><a id="toc-Reporting-Bugs-or-Suggestions" href="#Reports">Reporting Bugs
or Suggestions</a></li>
+ <li><a id="toc-Obtaining-help2man" href="#Availability">Obtaining
<code>help2man</code></a></li>
+</ul>
+</div>
-<p><a name="Invoking-help2man"></a></p>
-<h3 class="chapter">How to Run <samp><span
class="command">help2man</span></samp></h3>
+<span id="Top"></span><span id="help2man"></span><h2
class="top"><code>help2man</code></h2>
-<p>The format for running the <samp><span
class="command">help2man</span></samp>
-program is:</p>
+<p><code>help2man</code> produces simple manual pages from the
‘<samp>--help</samp>’
+and ‘<samp>--version</samp>’ output of other commands.
+</p>
-<pre class="example"> <samp><span class="command">help2man</span></samp>
[<var>option</var>]... <var>executable</var>
-</pre>
-<p><samp><span class="command">help2man</span></samp> supports the following
-options:</p>
+<hr>
+<span id="Overview"></span><span id="Overview-of-help2man"></span><h3
class="chapter">Overview of <code>help2man</code></h3>
- <dl>
-<dt>‘<samp><span class="samp">-n
</span><var>string</var></samp>’<br />
-‘<samp><span
class="samp">--name=</span><var>string</var></samp>’</dt>
+<p><code>help2man</code> is a tool for automatically generating simple
+manual pages from program output.
+</p>
+<p>Although manual pages are optional for GNU programs other projects,
+such as Debian require them (see <a
href="https://www.gnu.org/prep/standards/standards.html#Man-Pages";>Man
Pages</a> in <cite>GNU
+Coding Standards</cite>)
+</p>
+<p>This program is intended to provide an easy way for software authors
+to include a manual page in their distribution without having to
+maintain that document.
+</p>
+<p>Given a program which produces reasonably standard
‘<samp>--help</samp>’ and
+‘<samp>--version</samp>’ outputs, <code>help2man</code> can
re-arrange that
+output into something which resembles a manual page.
+</p>
+<hr>
+<span id="Invoking-help2man"></span><span id="How-to-Run-help2man"></span><h3
class="chapter">How to Run <code>help2man</code></h3>
-<dd>Use <var>string</var> as the description for the ‘<samp><span
-class="samp">NAME</span></samp>’ paragraph of the manual page.
+<p>The format for running the <code>help2man</code> program is:
+</p>
+<div class="example">
+<pre class="example"><code>help2man</code> [<var>option</var>]…
<var>executable</var>
+</pre></div>
+<p><code>help2man</code> supports the following options:
+</p>
+<dl compact="compact">
+<dt>‘<samp>-n <var>string</var></samp>’</dt>
+<dt>‘<samp>--name=<var>string</var></samp>’</dt>
+<dd><p>Use <var>string</var> as the description for the
‘<samp>NAME</samp>’ paragraph of
+the manual page.
+</p>
<p>By default (for want of anything better) this paragraph contains
-‘<samp><span class="samp">manual page for </span><var>program</var>
-<var>version</var></samp>’.</p>
-
-<p>This option overrides an include file ‘<samp><span
-class="samp">[name]</span></samp>’ section (see <a
-href="#Including-text">Including text</a>).</p>
-</dd>
-
-<dt>‘<samp><span class="samp">-s </span><var>section</var></samp>’
-<br />
-‘<samp><span class="samp">--section
-</span><var>section</var></samp>’</dt>
-
-<dd>Use <var>section</var> as the section for the man page. The default
-section is 1.</dd>
-
-<dt>‘<samp><span class="samp">-m </span><var>manual</var></samp>’
-<br />
-‘<samp><span class="samp">--manual=</span><var>manual</var></samp>’
-</dt>
-
-<dd>Set the name of the manual section to <var>section</var>, used as a centred
-heading for the manual page. By default ‘<samp><span class="samp">User
-Commands</span></samp>’ is used for pages in section 1,
‘<samp><span
-class="samp">Games</span></samp>’ for section 6 and ‘<samp><span
-class="samp">System Administration Utilities</span></samp>’ for sections
8
-and 1M.</dd>
-
-<dt>‘<samp><span class="samp">-S </span><var>source</var></samp>’
-<br />
-‘<samp><span
-class="samp">--source=</span><var>source</var></samp>’</dt>
-
-<dd>The program source is used as a page footer, and often contains the name
+‘<samp>manual page for <var>program</var>
<var>version</var></samp>’.
+</p>
+<p>This option overrides an include file ‘<samp>[name]</samp>’
section
+(see <a href="#Including-text">Including text</a>).
+</p>
+</dd>
+<dt>‘<samp>-s <var>section</var></samp>’</dt>
+<dt>‘<samp>--section <var>section</var></samp>’</dt>
+<dd><p>Use <var>section</var> as the section for the man page. The default
+section is 1.
+</p>
+</dd>
+<dt>‘<samp>-m <var>manual</var></samp>’</dt>
+<dt>‘<samp>--manual=<var>manual</var></samp>’</dt>
+<dd><p>Set the name of the manual section to <var>section</var>, used as a
centred
+heading for the manual page. By default ‘<samp>User
Commands</samp>’ is used
+for pages in section 1, ‘<samp>Games</samp>’ for section 6 and
‘<samp>System
+Administration Utilities</samp>’ for sections 8 and 1M.
+</p>
+</dd>
+<dt>‘<samp>-S <var>source</var></samp>’</dt>
+<dt>‘<samp>--source=<var>source</var></samp>’</dt>
+<dd><p>The program source is used as a page footer, and often contains the name
of the organisation or a suite of which the program is part. By default
-the value is the package name and version.</dd>
-
-<dt>‘<samp><span class="samp">-L </span><var>locale</var></samp>’
-<br />
-‘<samp><span
-class="samp">--locale=</span><var>locale</var></samp>’</dt>
-
-<dd>Select output locale (default ‘<samp><span
-class="samp">C</span></samp>’). Both the program and <samp><span
-class="command">help2man</span></samp> must support the given <var>locale</var>
-(see <a href="#Localised-man-pages">Localised man pages</a>).</dd>
-
-<dt>‘<samp><span class="samp">-i </span><var>file</var></samp>’
-<br />
-‘<samp><span
-class="samp">--include=</span><var>file</var></samp>’</dt>
-
-<dd>Include material from <var>file</var> (see <a
-href="#Including-text">Including text</a>).</dd>
-
-<dt>‘<samp><span class="samp">-I </span><var>file</var></samp>’
-<br />
-‘<samp><span
-class="samp">--opt-include=</span><var>file</var></samp>’</dt>
-
-<dd>A variant of ‘<samp><span class="samp">--include</span></samp>’
-for use in Makefile pattern rules which does not require <var>file</var> to
-exist.</dd>
-
-<dt>‘<samp><span class="samp">-o </span><var>file</var></samp>’
-<br />
-‘<samp><span
-class="samp">--output=</span><var>file</var></samp>’</dt>
-
-<dd>Send output to <var>file</var> rather than <code>stdout</code>.</dd>
-
-<dt>‘<samp><span class="samp">-p
-</span><var>text</var></samp>’
-<br />‘<samp><span
-class="samp">--info-page=</span><var>text</var></samp>’</dt>
-
-<dd>Name of Texinfo
-manual.</dd>
-
-<dt>‘<samp><span
-class="samp">-N</span></samp>’
-<br />‘<samp><span
-class="samp">--no-info</span></samp>’</dt>
-
-<dd>Suppress inclusion of a ‘<samp><span class="samp">SEE
-ALSO</span></samp>’ paragraph directing the reader to the Texinfo
-documentation.</dd>
-
-<dt>‘<samp><span
-class="samp">-l</span></samp>’
-<br />‘<samp><span
-class="samp">--libtool</span></samp>’</dt>
-
-<dd>Drop <samp><span class="file">lt-</span></samp> prefix from instances of
the
-program name in the synopsis (<samp><span class="command">libtool</span></samp>
-creates wrapper scripts in the build directory which invoke <samp><span
-class="command">foo</span></samp> as <samp><span
-class="command">.libs/lt-foo</span></samp>).</dd>
-
-<dt>‘<samp><span
-class="samp">--help</span></samp>’
-<br />‘<samp><span
-class="samp">--version</span></samp>’</dt>
-
-<dd>Show help or version information.
+the value is the package name and version.
+</p>
+</dd>
+<dt>‘<samp>-L <var>locale</var></samp>’</dt>
+<dt>‘<samp>--locale=<var>locale</var></samp>’</dt>
+<dd><p>Select output locale (default ‘<samp>C</samp>’). Both the
program and
+<code>help2man</code> must support the given <var>locale</var>
+(see <a href="#Localised-man-pages">Localised man pages</a>).
+</p>
+</dd>
+<dt>‘<samp>-i <var>file</var></samp>’</dt>
+<dt>‘<samp>--include=<var>file</var></samp>’</dt>
+<dd><p>Include material from <var>file</var> (see <a
href="#Including-text">Including text</a>).
+</p>
</dd>
+<dt>‘<samp>-I <var>file</var></samp>’</dt>
+<dt>‘<samp>--opt-include=<var>file</var></samp>’</dt>
+<dd><p>A variant of ‘<samp>--include</samp>’ for use in Makefile
pattern rules which
+does not require <var>file</var> to exist.
+</p>
+</dd>
+<dt>‘<samp>-o <var>file</var></samp>’</dt>
+<dt>‘<samp>--output=<var>file</var></samp>’</dt>
+<dd><p>Send output to <var>file</var> rather than <code>stdout</code>.
+</p>
+</dd>
+<dt>‘<samp>-p <var>text</var></samp>’</dt>
+<dt>‘<samp>--info-page=<var>text</var></samp>’</dt>
+<dd><p>Name of Texinfo manual.
+</p>
+</dd>
+<dt>‘<samp>-N</samp>’</dt>
+<dt>‘<samp>--no-info</samp>’</dt>
+<dd><p>Suppress inclusion of a ‘<samp>SEE ALSO</samp>’ paragraph
directing the reader
+to the Texinfo documentation.
+</p>
+</dd>
+<dt>‘<samp>-l</samp>’</dt>
+<dt>‘<samp>--libtool</samp>’</dt>
+<dd><p>Drop <samp>lt-</samp> prefix from instances of the program name in the
+synopsis (<code>libtool</code> creates wrapper scripts in the build
+directory which invoke <code>foo</code> as <code>.libs/lt-foo</code>).
+</p>
+</dd>
+<dt>‘<samp>--help</samp>’</dt>
+<dt>‘<samp>--version</samp>’</dt>
+<dd><p>Show help or version information.
+</p></dd>
</dl>
-<p>By default <samp><span class="command">help2man</span></samp> passes the
-standard ‘<samp><span class="samp">--help</span></samp>’ and
-‘<samp><span class="samp">--version</span></samp>’ options to the
-executable although alternatives may be specified using:</p>
-
-<dl>
-<dt>‘<samp><span class="samp">-h </span><var>option</var></samp>’
-<br />‘<samp><span
-class="samp">--help-option=</span><var>option</var></samp>’</dt>
-
-<dd>Help option string.</dd>
-
-<dt>‘<samp><span class="samp">-v </span><var>option</var></samp>’
-<br />‘<samp><span
-class="samp">--version-option=</span><var>option</var></samp>’</dt>
-
-<dd>Version option string.</dd>
-
-<dt>‘<samp><span
-class="samp">--version-string=</span><var>string</var></samp>’</dt>
-
-<dd>Version string.</dd>
-
-<dt>‘<samp><span
-class="samp">--no-discard-stderr</span></samp>’</dt>
-
-<dd>Include stderr when parsing option output.</dd>
+<p>By default <code>help2man</code> passes the standard
‘<samp>--help</samp>’ and
+‘<samp>--version</samp>’ options to the executable although
alternatives may
+be specified using:
+</p>
+<dl compact="compact">
+<dt>‘<samp>-h <var>option</var></samp>’</dt>
+<dt>‘<samp>--help-option=<var>option</var></samp>’</dt>
+<dd><p>Help option string.
+</p>
+</dd>
+<dt>‘<samp>-v <var>option</var></samp>’</dt>
+<dt>‘<samp>--version-option=<var>option</var></samp>’</dt>
+<dd><p>Version option string.
+</p>
+</dd>
+<dt>‘<samp>--version-string=<var>string</var></samp>’</dt>
+<dd><p>Version string.
+</p>
+</dd>
+<dt>‘<samp>--no-discard-stderr</samp>’</dt>
+<dd><p>Include stderr when parsing option output.
+</p></dd>
</dl>
-<p><a name="--help-recommendations"></a>
-<a name="g_t_002d_002dhelp-recommendations"></a></p>
-
-<h3 class="chapter"><samp><span class="option">--help</span></samp>
Recommendations</h3>
-
-<p>Here are some recommendations for what to include in your <samp><span
-class="option">--help</span></samp> output. Including these gives <samp><span
-class="command">help2man</span></samp> the best chance at generating a
-respectable man page, as well as benefitting users directly.</p>
-
-<p>See <a
-href="http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces";>Command-Line
-Interfaces</a>, and <a
-href="http://www.gnu.org/prep/standards/standards.html#Man-Pages";>Man
Pages</a>,
-for the official GNU standards relating to <samp><span
-class="option">--help</span></samp> and man pages.</p>
+<hr>
+<span id="g_t_002d_002dhelp-recommendations"></span><span
id="g_t_002d_002dhelp-Recommendations"></span><h3
class="chapter"><samp>--help</samp> Recommendations</h3>
+<p>Here are some recommendations for what to include in your
+<samp>--help</samp> output. Including these gives <code>help2man</code> the
+best chance at generating a respectable man page, as well as
+benefitting users directly.
+</p>
+<p>See <a
href="https://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces";>Command-Line
Interfaces</a> in <cite>GNU Coding Standards</cite>
+and <a href="https://www.gnu.org/prep/standards/standards.html#Man-Pages";>Man
Pages</a> in <cite>GNU Coding Standards</cite>, for the
+official GNU standards relating to <samp>--help</samp> and man pages.
+</p>
<ul>
-<li>A synopsis of how to invoke the program. If different usages of the
+<li> A synopsis of how to invoke the program. If different usages of the
program have different invocations, then list them all. For example
(edited for brevity):
- <pre class="smallexample"> Usage: cp [OPTION]... SOURCE DEST
+<div class="example">
+<pre class="example">Usage: cp [OPTION]... SOURCE DEST
or: cp [OPTION]... SOURCE... DIRECTORY
- ...
-</pre>
+…
+</pre></div>
+
<p>Use <code>argv[0]</code> for the program name in these synopses, just as it
is, with no directory stripping. This is in contrast to the canonical
-(constant) name of the program which is used in <samp><span
-class="option">--version</span></samp>.</p>
-</li>
-
-<li>A very brief explanation of what the program does, including default and/or
-typical behaviour. For example, here is <samp><span
-class="command">cp</span></samp>'s:
-
-<pre class="example"> Copy SOURCE to DEST, or multiple SOURCE(s) to
DIRECTORY.
-</pre>
-</li>
-<li>A list of options, indented to column 2. If the program supports
+(constant) name of the program which is used in <samp>--version</samp>.
+</p>
+</li><li> A very brief explanation of what the program does, including default
+and/or typical behaviour. For example, here is <code>cp</code>’s:
+
+<div class="example">
+<pre class="example">Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
+</pre></div>
+
+</li><li> A list of options, indented to column 2. If the program supports
one-character options, put those first, then the equivalent long option
(if any). If the option takes an argument, include that too, giving it
a meaningful name. Align the descriptions in a convenient column, if
-desired. Note that to be correctly recognised by <samp><span
class="command">help2man</span></samp>
+desired. Note that to be correctly recognised by <code>help2man</code>
the description must be separated from the options by at least two
spaces and descriptions continued on subsequent lines must start at
the same column.
-<p>Here again is an (edited) excerpt from <samp><span
-class="command">cp</span></samp>, showing a short option with an equivalent
long
-option, a long option only, and a short option only:</p>
-
- <pre class="smallexample"> -a, --archive same
as -dpR
+<p>Here again is an (edited) excerpt from <code>cp</code>, showing a short
+option with an equivalent long option, a long option only, and a short
+option only:
+</p>
+<div class="example">
+<pre class="example"> -a, --archive same as -dpR
--backup[=CONTROL] make a backup of each ...
-b like --backup but ...
-</pre>
+</pre></div>
+
<p>For programs that take many options, it may be desirable to split the
-option list into sections such as `Global', `Output control', or
+option list into sections such as ‘<samp>Global</samp>’,
‘<samp>Output control</samp>’, or
whatever makes sense in the particular case. It is usually best to
alphabetise (by short option name first, then long) within each section,
-or the entire list if there are no sections.</p></li>
-</ul>
-
-<ul>
-<li>Any useful additional information about program behaviour, such as
-influential environment variables, further explanation of options, etc. For
-example, <samp><span class="command">cp</span></samp> discusses <samp><span
-class="env">VERSION_CONTROL</span></samp> and sparse files.</li>
+or the entire list if there are no sections.
+</p>
+</li><li> Any useful additional information about program behaviour, such as
+influential environment variables, further explanation of options, etc.
+For example, <code>cp</code> discusses <code>VERSION_CONTROL</code> and sparse
+files.
-<li>A few examples of typical usage, at your discretion. One good example
+</li><li> A few examples of typical usage, at your discretion. One good
example
is usually worth a thousand words of description, so this is
-highly recommended.</li>
-
-<li><a name="index-address-for-bug-reports-1"></a><a
-name="index-bug-reports-2"></a>In closing, a line stating how to email bug
-reports. Typically, <var>mailing-address</var> will be ‘<samp><span
-class="samp">bug-</span><var>program</var><span
-class="samp">@gnu.org</span></samp>’; please use this form for GNU
-programs whenever possible. It's also good to mention the home page of the
-program, other mailing lists, etc.</li>
-</ul>
+highly recommended.
-<p>The <code>argp</code> and <code>popt</code> programming interfaces let you
-specify option descriptions for <samp><span class="option">--help</span></samp>
-in the same structure as the rest of the option definition; you may wish to
-consider using these routines for option parsing instead of
-<code>getopt</code>.</p>
-
-<p><a name="Including-text"></a></p>
-
-<h3 class="chapter">Including Additional Text in the Output</h3>
-
-<p>Additional static text may be included in the generated manual page by using
-the ‘<samp><span class="samp">--include</span></samp>’ and
-‘<samp><span class="samp">--opt-include</span></samp>’ options (see
-<a href="#Invoking-help2man">Invoking help2man</a>). While these files can be
-named anything, for consistency we suggest to use the extension
-<code>.h2m</code> for help2man include files.</p>
-
-<p>The format for files included with these option is simple:</p>
-
-<pre class="example"> [section]
- text
-
- /pattern/
- text
-</pre>
-<p>Blocks of verbatim *roff text are inserted into the output either at the
-start of the given ‘<samp><span
-class="samp">[section]</span></samp>’ (case insensitive), or after a
-paragraph matching ‘<samp><span
-class="samp">/pattern/</span></samp>’.</p>
-
-<p>Patterns use the Perl regular expression syntax and may be followed by the
-‘<samp><span class="samp">i</span></samp>’, ‘<samp><span
-class="samp">s</span></samp>’ or ‘<samp><span
-class="samp">m</span></samp>’ modifiers (see <a
-href="http://perldoc.perl.org/perlre.html#perlre";>perlre(1)</a>)</p>
+</li><li> <span id="index-address-for-bug-reports"></span>
+<span id="index-bug-reports"></span>
+In closing, a line stating how to email bug reports. Typically,
+<var>mailing-address</var> will be
‘<samp>bug-<var>program</var>@gnu.org</samp>’; please
+use this form for GNU programs whenever possible. It’s also good to
+mention the home page of the program, other mailing lists, etc.
+
+</li></ul>
+
+<p>The <code>argp</code> and <code>popt</code> programming interfaces let you
specify
+option descriptions for <samp>--help</samp> in the same structure as the
+rest of the option definition; you may wish to consider using these
+routines for option parsing instead of <code>getopt</code>.
+</p>
+<p>By default <code>help2man</code> has some heuristics for identifying
+manual page sections: a line consisting of ‘<samp>Options:</samp>’
for example
+will cause the following text to appear in the <code>OPTIONS</code> section,
+and a line beginning with ‘<samp>Copyright</samp>’ will appear in
the
+<code>COPYRIGHT</code> section. Outside of these heuristics, a line
+consisting of ‘<samp>*Words*</samp>’ will start a new section, and
+‘<samp>Words:</samp>’ a new sub-section.
+</p>
+<hr>
+<span id="Including-text"></span><span
id="Including-Additional-Text-in-the-Output"></span><h3
class="chapter">Including Additional Text in the Output</h3>
-<p>Lines before the first section or pattern which begin with
‘<samp><span class="samp">-</span></samp>’
+<p>Additional static text may be included in the generated manual page by
+using the ‘<samp>--include</samp>’ and
‘<samp>--opt-include</samp>’ options
+(see <a href="#Invoking-help2man">Invoking help2man</a>). While these files
can be named anything,
+for consistency we suggest to use the extension <code>.h2m</code> for
+<code>help2man</code> include files.
+</p>
+<p>The format for files included with these option is simple:
+</p>
+<div class="example">
+<pre class="example">[section]
+text
+
+/pattern/
+text
+</pre></div>
+
+<p>Blocks of verbatim *roff text are inserted into the output either at
+the start of the given ‘<samp>[section]</samp>’ (case
insensitive), or after a
+paragraph matching ‘<samp>/pattern/</samp>’.
+</p>
+<p>Patterns use the Perl regular expression syntax and may be followed by
+the ‘<samp>i</samp>’, ‘<samp>s</samp>’ or
‘<samp>m</samp>’ modifiers (see <a
href="http://perldoc.perl.org/perlre.html"#perlre";>perlre(1)</a> in <cite>The
<code>perlre(1)</code> manual page</cite>)
+</p>
+<p>Lines before the first section or pattern which begin with
‘<samp>-</samp>’
are processed as options. Anything else is silently ignored and may
-be used for comments, RCS keywords and the like.</p>
-
-<p>The section output order (for those included) is:</p>
-
-<pre class="example"> NAME
- SYNOPSIS
- DESCRIPTION
- OPTIONS
- ENVIRONMENT
- FILES
- EXAMPLES
- <em>other</em>
- AUTHOR
- REPORTING BUGS
- COPYRIGHT
- SEE ALSO
-</pre>
-<p>Any ‘<samp><span class="samp">[name]</span></samp>’ or
-‘<samp><span class="samp">[synopsis]</span></samp>’ sections
-appearing in the include file will replace what would have automatically been
-produced (although you can still override the former with ‘<samp><span
-class="samp">--name</span></samp>’ if required).</p>
-
+be used for comments, RCS keywords and the like.
+</p>
+<p>The section output order (for those included) is:
+</p>
+<div class="example">
+<pre class="example">NAME
+SYNOPSIS
+DESCRIPTION
+OPTIONS
+<em>other</em>
+ENVIRONMENT
+FILES
+EXAMPLES
+AUTHOR
+REPORTING BUGS
+COPYRIGHT
+SEE ALSO
+</pre></div>
+
+<p>Any ‘<samp>[name]</samp>’ or
‘<samp>[synopsis]</samp>’ sections appearing in the
+include file will replace what would have automatically been produced
+(although you can still override the former with
‘<samp>--name</samp>’ if
+required).
+</p>
<p>Other sections are prepended to the automatically produced output for
the standard sections given above, or included at <em>other</em> (above)
-in the order they were encountered in the include file.</p>
+in the order they were encountered in the include file.
+</p>
+<p>Placement of the text within the section may be explicitly requested
+by using the syntax ‘<samp>[<section]</samp>’,
‘<samp>[=section]</samp>’ or
+‘<samp>[>section]</samp>’ to place the additional text before,
in place of, or
+after the default output respectively.
+</p>
+<hr>
+<span id="Makefile-usage"></span><span
id="Using-help2man-With-make"></span><h3 class="chapter">Using
<code>help2man</code> With <code>make</code></h3>
-<p><a name="Makefile-usage"></a></p>
+<p>A suggested use of <code>help2man</code> in Makefiles is to have the
+manual page depend not on the binary, but on the source file(s) in
+which the ‘<samp>--help</samp>’ and
‘<samp>--version</samp>’ output are defined.
+</p>
+<p>This usage allows a manual page to be generated by the maintainer and
+included in the distribution without requiring the end-user to have
+<code>help2man</code> installed.
+</p>
+<p>An example rule for the program <code>prog</code> could be:
+</p>
+<div class="example">
+<pre class="example">prog.1: $(srcdir)/main.c
+ -$(HELP2MAN) --output=$@ --name='an example program' ./prog
+</pre></div>
-<h3 class="chapter">Using <samp><span class="command">help2man</span></samp>
With <samp><span class="command">make</span></samp></h3>
+<p>The value of <code>HELP2MAN</code> may be set in <code>configure.in</code>
using
+either of:
+</p>
+<div class="example">
+<pre class="example">AM_MISSING_PROG(HELP2MAN, help2man)
+</pre></div>
-<p>A suggested use of <samp><span class="command">help2man</span></samp> in
Makefiles is to have the
-manual page depend not on the binary, but on the source file(s) in
-which the ‘<samp><span class="samp">--help</span></samp>’ and
-‘<samp><span class="samp">--version</span></samp>’ output are
-defined.</p>
+<p>for <code>automake</code>, or something like:
+</p>
+<div class="example">
+<pre class="example">AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
+</pre></div>
- <p>This usage allows a manual page to be generated by the maintainer and
-included in the distribution without requiring the end-user to have
-<samp><span class="command">help2man</span></samp> installed.</p>
+<p>for <code>autoconf</code> alone.
+</p>
+<hr>
+<span id="Localised-man-pages"></span><span
id="Producing-Native-Language-Manual-Pages"></span><h3
class="chapter">Producing Native Language Manual Pages</h3>
- <p>An example rule for the program <code>prog</code> could be:</p>
+<p>Manual pages may be produced for any locale supported by both the
+program and <code>help2man</code> with the ‘<samp>--locale</samp>’
(‘<samp>-L</samp>’)
+option.
+</p>
+<div class="example">
+<pre class="example">help2man -L fr_FR@euro -o cp.fr.1 cp
+</pre></div>
+
+<p>See <a
href="http://translationproject.org/domain/help2man.html";>http://translationproject.org/domain/help2man.html</a>
for the
+languages currently supported by <code>help2man</code>, and
+see <a href="#Reports">Reports</a> for how to submit other translations.
+</p>
+<span id="Changing-the-Location-of-Message-Catalogs"></span><h4
class="section">Changing the Location of Message Catalogs</h4>
-<pre class="example"> prog.1: $(srcdir)/main.c
- -$(HELP2MAN) --output=$@ --name='an example program' ./prog
-</pre>
-<p>The value of <code>HELP2MAN</code> may be set in <code>configure.in</code>
-using either of:</p>
-
-<pre class="example"> AM_MISSING_PROG(HELP2MAN, help2man, $missing_dir)
-</pre>
-<p>for <samp><span class="command">automake</span></samp>, or something
-like:</p>
-
-<pre class="example"> AC_PATH_PROG(HELP2MAN, help2man, false // No
help2man //)
-</pre>
-<p>for <samp><span class="command">autoconf</span></samp> alone.</p>
-
-<p><a name="Localised-man-pages"></a></p>
-
-<h3 class="chapter">Producing Native Language Manual Pages</h3>
-
-<p>Manual pages may be produced for any locale supported by both the program
and
-<samp><span class="command">help2man</span></samp> with the ‘<samp><span
-class="samp">--locale</span></samp>’ (‘<samp><span
-class="samp">-L</span></samp>’) option.</p>
-
-<pre class="example"> help2man -L fr_FR@euro -o cp.fr.1 cp
-</pre>
-<p>See <a href="http://translationproject.org/domain/help2man.html";>
-http://translationproject.org/domain/help2man.html</a> for the languages
-currently supported by <samp><span class="command">help2man</span></samp>, and
-see <a href="#Reports">Reports</a> for how to submit other translations.</p>
-
-<h4 class="section">Changing the Location of Message Catalogs</h4>
-
-<p>When creating localised manual pages from a program's build directory it is
-probable that the translations installed in the standard location will not be
-(if installed at all) correct for the version of the program being built.</p>
-
-<p>A preloadable library is provided with <samp><span
-class="command">help2man</span></samp> which will intercept
-<code>bindtextdomain</code> calls configuring the location of message catalogs
-for the domain given by <samp><span class="env">$TEXTDOMAIN</span></samp> and
-override the location to the path given by <samp><span
-class="env">$LOCALEDIR</span></samp>.</p>
-
-<p>So for example:</p>
-
-<pre class="example"> mkdir -p tmp/fr/LC_MESSAGES
- cp po/fr.gmo tmp/fr/LC_MESSAGES/<var>prog</var>.mo
- LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
+<p>When creating localised manual pages from a program’s build directory
it
+is probable that the translations installed in the standard location
+will not be (if installed at all) correct for the version of the
+program being built.
+</p>
+<p>A preloadable library is provided with <code>help2man</code> which will
+intercept <code>bindtextdomain</code> calls configuring the location of message
+catalogs for the domain given by <code>$TEXTDOMAIN</code> and override the
+location to the path given by <code>$LOCALEDIR</code>.
+</p>
+<p>So for example:
+</p>
+<div class="example">
+<pre class="example">mkdir -p tmp/fr/LC_MESSAGES
+cp po/fr.gmo tmp/fr/LC_MESSAGES/<var>prog</var>.mo
+LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
LOCALEDIR=tmp \
TEXTDOMAIN=<var>prog</var> \
help2man -L fr_FR@euro -i <var>prog</var>.fr.h2m -o
<var>prog</var>.fr.1 <var>prog</var>
- rm -rf tmp
-</pre>
-<p>will cause <var>prog</var> to load the message catalog from
-‘<samp><span class="samp">tmp</span></samp>’ rather than
-‘<samp><span class="samp">/usr/share/locale</span></samp>’.</p>
+rm -rf tmp
+</pre></div>
-<p>Notes:</p>
-<ul>
-<li>The generalisation of ‘<samp><span
-class="samp">fr_FR@euro</span></samp>’ to ‘<samp><span
-class="samp">fr</span></samp>’ in the example above is done by
-<code>gettext</code>, if a more specific match were available it would also
have
-been re-mapped.</li>
-
-<li>This preload has only been tested against <samp><span
-class="command">eglibc</span></samp> 2.11.2 and <samp><span
-class="command">gettext</span></samp> 0.18.1.1 on a GNU/Linux system; let me
-know if it does (or doesn't) work for you (see <a
-href="#Reports">Reports</a>).</li>
-</ul>
+<p>will cause <var>prog</var> to load the message catalog from
‘<samp>tmp</samp>’
+rather than ‘<samp>/usr/share/locale</samp>’.
+</p>
+<p>Notes:
+</p><ul>
+<li> The generalisation of ‘<samp>fr_FR@euro</samp>’ to
‘<samp>fr</samp>’ in the example
+above is done by <code>gettext</code>, if a more specific match were available
+it would also have been re-mapped.
+
+</li><li> This preload has only been tested against <code>eglibc</code> 2.11.2
and
+<code>gettext</code> 0.18.1.1 on a GNU/Linux system; let me know if it
+does (or doesn’t) work for you (see <a href="#Reports">Reports</a>).
+</li></ul>
-<p><a name="Example"></a></p>
+<hr>
+<span id="Example"></span><span id="Example-help2man-Output"></span><h3
class="chapter">Example <code>help2man</code> Output</h3>
-<h3 class="chapter">Example <samp><span class="command">help2man</span></samp>
Output</h3>
+<p>Given a hypothetical program <code>foo</code> which produces the following
output:
+</p>
-<p>Given a hypothetical program <samp><span class="command">foo</span></samp>
-which produces the following output:</p>
-<!-- Default values strong/em to be used in Examples, these are -->
-<!-- overridden for info, which doesn't have real bold/italic. -->
-<!-- No-op version for info: -->
-<pre class="example"> <strong>$ foo --version</strong>
- GNU foo 1.1
-
- Copyright (C) 2011 Free Software Foundation, Inc.
- This is free software; see the source for copying conditions. There is NO
- warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
+<div class="example">
+<pre class="example"><strong>$ foo --version</strong>
+GNU foo 1.1
+
+Copyright (C) 2011 Free Software Foundation, Inc.
+This is free software; see the source for copying conditions. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+Written by A. Programmer.
+<strong>$ foo --help</strong>
+GNU `foo' does nothing interesting except serve as an example for
+`help2man'.
- Written by A. Programmer.
- <strong>$ foo --help</strong>
- GNU `foo' does nothing interesting except serve as an example for
- `help2man'.
-
- Usage: foo [OPTION]...
+Usage: foo [OPTION]...
- Options:
+Options:
-a, --option an option
-b, --another-option[=VALUE]
another option
@@ -461,30 +441,31 @@
--help display this help and exit
--version output version information and exit
- Examples:
+Examples:
foo do nothing
foo --option the same thing, giving `--option'
- Report bugs to <bug-gnu-utils@gnu.org>.
-</pre>
-<p><samp><span class="command">help2man</span></samp> will produce <samp><span
-class="command">nroff</span></samp> input for a manual page which will be
-formatted something like this:</p>
+Report bugs to <bug-gnu-utils@gnu.org>.
+</pre></div>
-<pre class="example"> FOO(1) User Commands
FOO(1)
+<p><code>help2man</code> will produce <code>nroff</code> input for a manual
+page which will be formatted something like this:
+</p>
+<div class="example">
+<pre class="example">FOO(1) User Commands
FOO(1)
- <strong>NAME</strong>
+<strong>NAME</strong>
foo - manual page for foo 1.1
- <strong>SYNOPSIS</strong>
+<strong>SYNOPSIS</strong>
foo [OPTION]...
- <strong>DESCRIPTION</strong>
+<strong>DESCRIPTION</strong>
GNU `foo' does nothing interesting except serve as an example for
`help2man'.
- <strong>OPTIONS</strong>
+<strong>OPTIONS</strong>
<strong>-a</strong>, <strong>--option</strong>
an option
@@ -496,25 +477,25 @@
<strong>--version</strong>
output version information and exit
- <strong>EXAMPLES</strong>
+<strong>EXAMPLES</strong>
foo do nothing
foo <strong>--option</strong>
the same thing, giving `--option'
- <strong>AUTHOR</strong>
+<strong>AUTHOR</strong>
Written by A. Programmer.
- <strong>REPORTING BUGS</strong>
+<strong>REPORTING BUGS</strong>
Report bugs to <bug-gnu-utils@gnu.org>.
- <strong>COPYRIGHT</strong>
+<strong>COPYRIGHT</strong>
Copyright © 2011 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
- <strong>SEE ALSO</strong>
+<strong>SEE ALSO</strong>
The full documentation for <strong>foo</strong> is maintained as a
Texinfo manual.
If the <strong>info</strong> and <strong>foo</strong> programs
are properly installed at your site,
the command
@@ -524,66 +505,43 @@
should give you access to the complete manual.
- foo 1.1 May 2011 FOO(1)
-</pre>
-<p><a name="Reports"></a></p>
+foo 1.1 May 2011 FOO(1)
+</pre></div>
-<h3 class="chapter">Reporting Bugs or Suggestions</h3>
+<hr>
+<span id="Reports"></span><span id="Reporting-Bugs-or-Suggestions"></span><h3
class="chapter">Reporting Bugs or Suggestions</h3>
<p>If you find problems or have suggestions about this program or
-manual, please report them to <a
-href="mailto:bug-help2man@gnu.org";>bug-help2man@gnu.org</a>.</p>
+manual, please report them to <a
href="mailto:bug-help2man@gnu.org";>bug-help2man@gnu.org</a>.
+</p>
+<p>Note to translators: Translations are handled though the
+<a href="http://translationproject.org/";>Translation Project</a> see
+<a
href="http://translationproject.org/html/translators.html";>http://translationproject.org/html/translators.html</a>
for details.
+</p>
+<hr>
+<span id="Availability"></span><span id="Obtaining-help2man"></span><h3
class="chapter">Obtaining <code>help2man</code></h3>
-<p>Note to translators: Translations are handled though the <a
-href="http://translationproject.org/";>Translation Project</a> see <a
-href="http://translationproject.org/html/translators.html";>
-http://translationproject.org/html/translators.html</a> for details.</p>
+<p>The latest version of this distribution is available online from GNU
+mirrors:
+</p>
+<div class="example">
+<pre class="example"><a
href="http://ftpmirror.gnu.org/help2man/";>http://ftpmirror.gnu.org/help2man/</a>
+</pre></div>
-<p><a name="Availability"></a></p>
+<p>If automatic redirection fails, the list of mirrors is at:
+</p>
+<div class="example">
+<pre class="example"><a
href="http://www.gnu.org/order/ftp.html";>http://www.gnu.org/order/ftp.html</a>
+</pre></div>
+
+<p>Or if need be you can use the main GNU ftp server:
+</p><div class="example">
+<pre class="example"><a
href="http://ftp.gnu.org/gnu/help2man/";>http://ftp.gnu.org/gnu/help2man/</a>
+</pre></div>
-<h3 class="chapter">Obtaining <samp><span
class="command">help2man</span></samp></h3>
+<hr>
-<p>The latest version of this distribution is available online from GNU
-mirrors:</p>
-<pre class="example"> <a
href="http://ftpmirror.gnu.org/help2man/";>http://ftpmirror.gnu.org/help2man/</a>
-</pre>
-<p>If automatic redirection fails, the list of mirrors is at:</p>
-
-<pre class="example"> <a
href="http://www.gnu.org/order/ftp.html";>http://www.gnu.org/order/ftp.html</a>
-</pre>
-<p>Or if need be you can use the main GNU ftp server:</p>
-<pre class="example"> <a
href="http://ftp.gnu.org/gnu/help2man/";>http://ftp.gnu.org/gnu/help2man/</a>
-</pre>
- <div class="contents">
-<h3>Table of Contents</h3>
-<ul>
-<li><a name="toc_Top" href="#Top"><samp><span
-class="command">help2man</span></samp></a></li>
-<li><a name="toc_Overview" href="#Overview">Overview of <samp><span
-class="command">help2man</span></samp></a></li>
-<li><a name="toc_Invoking-help2man" href="#Invoking-help2man">How to Run
-<samp><span class="command">help2man</span></samp></a></li>
-<li><a name="toc__002d_002dhelp-recommendations"
-href="#_002d_002dhelp-recommendations"><samp><span
-class="option">--help</span></samp> Recommendations</a></li>
-<li><a name="toc_Including-text" href="#Including-text">Including Additional
-Text in the Output</a></li>
-<li><a name="toc_Makefile-usage" href="#Makefile-usage">Using <samp><span
-class="command">help2man</span></samp> With <samp><span
-class="command">make</span></samp></a></li>
-<li><a name="toc_Localised-man-pages" href="#Localised-man-pages">Producing
-Native Language Manual Pages</a>
-<ul>
-<li><a href="#Localised-man-pages">Changing the Location of Message
Catalogs</a>
-</li></ul></li>
-<li><a name="toc_Example" href="#Example">Example <samp><span
-class="command">help2man</span></samp> Output</a></li>
-<li><a name="toc_Reports" href="#Reports">Reporting Bugs or
Suggestions</a></li>
-<li><a name="toc_Availability" href="#Availability">Obtaining <samp><span
-class="command">help2man</span></samp></a></li>
-</ul>
-</div>
</div><!-- for id="content", starts in the include above -->
<!--#include virtual="/server/footer.html" -->
@@ -594,7 +552,7 @@
<a href="mailto:gnu@gnu.org";><gnu@gnu.org></a>.
There are also <a href="/contact/">other ways to contact</a>
the FSF. Broken links and other corrections or suggestions can be sent
-to <a href="mailto:webmasters@gnu.org";><webmasters@gnu.org></a>.</p>
+to <a href="mailto:bug-help2man@gnu.org";><bug-help2man@gnu.org></a>.</p>
<p><!-- TRANSLATORS: Ignore the original text in this paragraph,
replace it with the translation of these two:
@@ -605,19 +563,19 @@
to <a href="mailto:web-translators@gnu.org";>
<web-translators@gnu.org></a>.</p>
- <p>For information on coordinating and submitting translations of
+ <p>For information on coordinating and contributing translations of
our web pages, see <a
href="/server/standards/README.translations.html">Translations
README</a>. -->
Please see the <a
href="/server/standards/README.translations.html">Translations
-README</a> for information on coordinating and submitting translations
+README</a> for information on coordinating and contributing translations
of this article.</p>
</div>
<!-- Regarding copyright, in general, standalone pages (as opposed to
files generated as part of manuals) on the GNU web server should
- be under CC BY-ND 3.0 US. Please do NOT change or remove this
+ be under CC BY-ND 4.0. Please do NOT change or remove this
without talking with the webmasters or licensing team first.
Please make sure the copyright date is consistent with the
document. For web pages, it is ok to list just the latest year the
@@ -632,20 +590,20 @@
There is more detail about copyright years in the GNU Maintainers
Information document, www.gnu.org/prep/maintain. -->
-<p>Copyright © 2014 Free Software Foundation, Inc.</p>
+<p>Copyright © 2020 Free Software Foundation, Inc.</p>
<p>This page is licensed under a <a rel="license"
-href="http://creativecommons.org/licenses/by-nd/3.0/us/";>Creative
-Commons Attribution-NoDerivs 3.0 United States License</a>.</p>
+href="http://creativecommons.org/licenses/by-nd/4.0/";>Creative
+Commons Attribution-NoDerivatives 4.0 International License</a>.</p>
<!--#include virtual="/server/bottom-notes.html" -->
<p class="unprintable">Updated:
<!-- timestamp start -->
-$Date: 2014/04/12 12:40:57 $
+$Date: 2020/07/02 21:59:26 $
<!-- timestamp end -->
</p>
</div>
-</div>
+</div><!-- for class="inner", starts in the banner include -->
</body>
</html>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- www/software/help2man help2man.html,
Karl Berry <=