本文档记载 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 其他命令的输出生成简单的手册页。

help2man 概览
***********

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

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

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.

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

如何运行 help2man。
**************

运行 help2man 程序的格式为:

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

help2man 支持以下选项:

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

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

     This option overrides an include file [name] section (see 包含文字).

-s 章节
--section 章节
     Use SECTION as the section for the man page.  The default section is 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
     Select output locale (default C).  Both the program and help2man must support the given LOCALE (see 已本地化的手册页).

-i FILE
--include=FILE
     Include material from 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.

--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 (GNU Coding Standards) and Man Pages (GNU Coding 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.

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

Additional static text may be included in the generated manual page by using the --include and --opt-include options (see 调用 help2man).  While these files can be named anything, for consistency we suggest to use the extension .h2m for help2man include files.

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) (The perlre(1) manual page))

第一节前的行，或由 - 开始的模式，将被认为是选项。其他的都将被安静地忽略，可被用作注释、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.

同 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 专用。

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

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

See http://translationproject.org/domain/help2man.html for the languages currently supported by help2man, and see 报告 for how to submit other translations.

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.

  * This preload has only been tested against eglibc 2.11.2 and gettext 0.18.1.1 on a GNU/Linux system; let me know if it does (or doesn't) work for you (see 报告).

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

            should give you access to the complete manual.

     foo 1.1                          2011 五月                           FOO(1)

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

If you find problems or have suggestions about this program or manual, please report them to bug-help2man@gnu.org.

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

获取 help2man。
************

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

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

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

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

必要时可以使用 GNU 主 FTP 服务器:

     http://ftp.gnu.org/gnu/help2man/