本文档记载 GNU ‘help2man’ 命令，用以从其他命令的 ‘--help’ 和 ‘--version’
输出生成简单的手册页。

   版权所有 (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
2011, 2012, 2013, 2014, 2015 自由软件基金会。

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

‘help2man’
**********

‘help2man’ 可从 ‘--help’ 和 ‘--version’ 其他命令的输出生成简单的手册页。

1 ‘help2man’ 概览
*****************

‘help2man’ 是一种从程序输出自动生成简单的手册页的工具。

   Although manual pages are optional for GNU programs other projects,
such as Debian require them (see Man Pages (standards))

   本程序旨在为软件作者提供一个简单的方法，使得他们可以无需认真维护却可
以在软件发行中包含手册页。

   给定一个程序，若其能提供合理标准的 ‘--help’ 和 ‘--version’ 输出，
‘help2man’ 可以将那些信息整理成像手册页一样的东西。

2 如何运行 ‘help2man’。
***********************

运行 ‘help2man’ 程序的格式为:

     help2man [选项]... 可执行文件

   ‘help2man’ 支持以下选项:

‘-n 字符串’
‘--name=字符串’
     使用 字符串 作为手册页的 ‘名称’ 段的描述。

     By default (for want of anything better) this paragraph contains
     ‘manual page for PROGRAM VERSION’.

     此选项覆盖一个包含文件 ‘[名称]’ 章节 (see 包含文字).

‘-s 章节’
‘--section 章节’
     将 章节 作为手册页的分类号。默认值为 1。

‘-m MANUAL’
‘--manual=MANUAL’
     Set the name of the manual section to SECTION, used as a centred
     heading for the manual page.  By default ‘User Commands’ is used
     for pages in section 1, ‘Games’ for section 6 and ‘System
     Administration Utilities’ for sections 8 and 1M.

‘-S SOURCE’
‘--source=SOURCE’
     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.

‘-L LOCALE’
‘-L LOCALE’
     设置输出语区（默认为 ‘C’）。程序本身和 ‘help2man’ 都必须支持给定的
     语区（see 本地化手册页）。

‘-i FILE’
‘--include=FILE’
     从 文件 包含内容（see 包含文字）。

‘-I FILE’
‘--opt-include=FILE’
     A variant of ‘--include’ for use in Makefile pattern rules which
     does not require FILE to exist.

‘-o FILE’
‘--output=FILE’
     将输出写入到 FILE 而非 ‘stdout’。

‘-p TEXT’
‘--info-page=TEXT’
     Texinfo 手册名称。

‘-N’
‘--no-info’
     Suppress inclusion of a ‘SEE ALSO’ paragraph directing the reader
     to the Texinfo documentation.

‘-l’
‘--libtool’
     Drop ‘lt-’ prefix from instances of the program name in the
     synopsis (‘libtool’ creates wrapper scripts in the build directory
     which invoke ‘foo’ as ‘.libs/lt-foo’).

‘--help’
‘--version’
     显示帮助或版本信息。

   By default ‘help2man’ passes the standard ‘--help’ and ‘--version’
options to the executable although alternatives may be specified using:

‘-h OPTION’
‘--help-option=OPTION’
     帮助选项字串。

‘-v OPTION’
‘-h OPTION’
     版本选项字串。

‘--version-string=STRING’
     版本字串。

‘--no-discard-stderr’
     Include stderr when parsing option output.

3 ‘--help’ 建议
***************

Here are some recommendations for what to include in your ‘--help’
output.  Including these gives ‘help2man’ the best chance at generating
a respectable man page, as well as benefitting users directly.

   See Command-Line Interfaces (standards) and
Man Pages (standards), for the official GNU standards relating to
‘--help’ and man pages.

   • 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):

          Usage: cp [OPTION]... SOURCE DEST
            or:  cp [OPTION]... SOURCE... DIRECTORY
          ...

     Use ‘argv[0]’ 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
     ‘--version’.

   • A very brief explanation of what the program does, including
     default and/or typical behaviour.  For example, here is ‘cp’’s:

          将 SOURCE 拷贝到 DEST，或将多个 SOURCE 拷贝到 DIRECTORY。

   • 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 ‘help2man’ 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.

     Here again is an (edited) excerpt from ‘cp’, showing a short option
     with an equivalent long option, a long option only, and a short
     option only:

            -a, --archive                相当于 -dpR
                --backup[=CONTROL]       对每个文件备份 ...
            -b                           就像 --backup 不过 ...

     For programs that take many options, it may be desirable to split
     the option list into sections such as ‘Global’, ‘Output control’,
     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.

   • Any useful additional information about program behaviour, such as
     influential environment variables, further explanation of options,
     etc.  For example, ‘cp’ discusses ‘VERSION_CONTROL’ and sparse
     files.

   • 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.

   • In closing, a line stating how to email bug reports.  Typically,
     MAILING-ADDRESS will be ‘bug-PROGRAM@gnu.org’; 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.

   The ‘argp’ and ‘popt’ programming interfaces let you specify option
descriptions for ‘--help’ in the same structure as the rest of the
option definition; you may wish to consider using these routines for
option parsing instead of ‘getopt’.

   By default ‘help2man’ has some heuristics for identifying manual page
sections: a line consisting of ‘Options:’ for example will cause the
following text to appear in the ‘OPTIONS’ section, and a line beginning
with ‘Copyright’ will appear in the ‘COPYRIGHT’ section.  Outside of
these heuristics, a line consisting of ‘*Words*’ will start a new
section, and ‘Words:’ a new sub-section.

4 在输出中包括附加文本
**********************

额外的静态文字可用 ‘--include’ 和 ‘--opt-include’（see 调用 help2man
）加入生成的手册页中。尽管这些文件可以任意命名，我们还是推荐使
用将 ‘.h2m’ 拓展名用于 ‘help2man’ 包含文件以保证一致性。

   The format for files included with these option is simple:

     [章节]
     文本

     /正则表达式/
     文本

   逐字 *roff 文字块将在给定的 ‘[章节]’（大小写不敏感）开始处，或在匹配
‘/正则表达式/’ 的段后加入。

   Patterns use the Perl regular expression syntax and may be followed
by the ‘i’, ‘s’ or ‘m’ modifiers (see perlre(1) (*manpages*))

   第一节前的行，或由 ‘-’ 开始的模式，将被认为是选项。其他的都将被安静地
忽略，可被用作注释、RCS 关键字等。

   章节输出（包含的）顺序为：

     NAME
     SYNOPSIS
     DESCRIPTION
     OPTIONS
     _other_
     ENVIRONMENT
     FILES
     EXAMPLES
     AUTHOR
     REPORTING BUGS
     COPYRIGHT
     SEE ALSO

   Any ‘[name]’ or ‘[synopsis]’ sections appearing in the include file
will replace what would have automatically been produced (although you
can still override the former with ‘--name’ if required).

   其他章节会自动附加到以上自动生成章节之上，或按照它们在包含文件中出现
的顺序包含于 _其他_（以上）章节上。

   Placement of the text within the section may be explicitly requested
by using the syntax ‘[<section]’, ‘[=section]’ or ‘[>section]’ to place
the additional text before, in place of, or after the default output
respectively.

5 同 ‘make’ 一起使用 ‘help2man’。
*********************************

A suggested use of ‘help2man’ in Makefiles is to have the manual page
depend not on the binary, but on the source file(s) in which the
‘--help’ and ‘--version’ output are defined.

   This usage allows a manual page to be generated by the maintainer and
included in the distribution without requiring the end-user to have
‘help2man’ installed.

   An example rule for the program ‘prog’ could be:

     prog.1: $(srcdir)/main.c
             -$(HELP2MAN) --output=$@ --name='an example program' ./prog

   The value of ‘HELP2MAN’ may be set in ‘configure.in’ using either of:

     AM_MISSING_PROG(HELP2MAN, help2man)

   ‘automake’，或类似如下例子：

     AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)

   仅为 ‘autoconf’ 专用。

6 生成原生语言手册页
********************

Manual pages may be produced for any locale supported by both the
program and ‘help2man’ with the ‘--locale’ (‘-L’) option.

     help2man -L fr_FR@euro -o cp.fr.1 cp

   参见 <http://translationproject.org/domain/help2man.html> 以获取
‘help2man’ 目前支持的语言列表，以及 报告 以学习如何提交其它翻译
。

6.1 Changing the Location of Message Catalogs
=============================================

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.

   A preloadable library is provided with ‘help2man’ which will
intercept ‘bindtextdomain’ calls configuring the location of message
catalogs for the domain given by ‘$TEXTDOMAIN’ and override the location
to the path given by ‘$LOCALEDIR’.

   举个例子:

     mkdir -p tmp/fr/LC_MESSAGES
     cp po/fr.gmo tmp/fr/LC_MESSAGES/PROG.mo
     LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
       LOCALEDIR=tmp \
       TEXTDOMAIN=PROG \
       help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
     rm -rf tmp

   will cause PROG to load the message catalog from ‘tmp’ rather than
‘/usr/share/locale’.

   注：
   • The generalisation of ‘fr_FR@euro’ to ‘fr’ in the example above is
     done by ‘gettext’, if a more specific match were available it would
     also have been re-mapped.

   • 此预加载库只配合 ‘eglibc’ 2.11.2 和 ‘gettext’ 0.18.1.1 在一个
     GNU/Linux 系统上测试过；请告诉我们它是否对你有用（see 报告）。

7 ‘help2man’ 示例输出。
***********************

Given a hypothetical program ‘foo’ which produces the following output:

     $ foo --version
     GNU foo 1.1

     版权所有 (C) 2011 自由软件基金会。
     本软件为自由软件；请参阅源代码以获取许可条款。此软件不对包括商业使用以及其他
     特殊用途提供任何担保。

     Written by A. Programmer.
     $ foo --help
     GNU `foo' does nothing interesting except serve as an example for
     `help2man'.

     用法: foo [选项] ...

     Options:
       -a, --option      an option
       -b, --another-option[=VALUE]
                         another option

           --help           显示此帮助信息并退出
           --version     输出版本信息并退出

     示例:
       foo               什么都不做
       foo --option      效果一致，传入参数 `--option'

     请将问题报告给 <bug-gnu-utils@gnu.org>。

   ‘help2man’ will produce ‘nroff’ input for a manual page which will be
formatted something like this:

     FOO(1)                         用户命令                        FOO(1)

     NAME
            foo - manual page for foo 1.1

     SYNOPSIS
            foo [OPTION]...

     DESCRIPTION
            GNU  `foo'  does nothing interesting except serve as an example for
            `help2man'.

     OPTIONS
            -a, --option
                   an option

            -b, --another-option[=VALUE]
                   another option

     	--help 显示此帮助信息并推出

           --version
                   输出版本信息并退出

     EXAMPLES
            foo    do nothing

            foo --option
                   the same thing, giving `--option'

     AUTHOR
            Written by A. Programmer.

     REPORTING BUGS
            Report bugs to <bug-gnu-utils@gnu.org>.

     COPYRIGHT
            版权所有 (C) 2011 自由软件基金会。
           本软件为自由软件；请参阅源代码以获取许可条款。
            此软件不对提供任何担保，甚至不保证适销性或对某一特定用途的适用性的保证。
     SEE ALSO
            The full documentation for foo is maintained as a  Texinfo  manual.
            If  the  info and foo programs are properly installed at your site,
            the command

                   info foo

            应可给您显示完整的手册页。

     foo 1.1                          2011 五月                           FOO(1)

8 报告程序缺陷或建议
********************

如果你在此程序或本手册中发现了问题，或是有什么意见或建议，都请一并报告到
<bug-help2man@gnu.org>。

   翻译员们请注意: 软件翻译通过 Translation Project
(http://translationproject.org/) 管理，请访问
<http://translationproject.org/html/translators.html> 以获取更多信息。

9 获取 ‘help2man’。
*******************

此发行的最新版本可从 GNU 在线镜像获取:

     <http://ftpmirror.gnu.org/help2man/>

   如自动重定向失败，镜像列表位于:

     <http://www.gnu.org/order/ftp.html>

   必要时可以使用 GNU 主 FTP 服务器:
     <http://ftp.gnu.org/gnu/help2man/>