openkylin
/
help2man
mirror of https://gitee.com/openkylin/help2man.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity
help2man/help2man-zh_CN.info

509 lines
17 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This is help2man-zh_CN.info.tmp, produced by makeinfo version 6.8 from
help2man-zh_CN.texi.
本文档记载 GNU ‘help2man’ 命令，用以从其他命令的 ‘--help’ 和 ‘--version’
输出生成简单的手册页。
版权所有 (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
2011, 2012, 2013, 2014, 2015, 2020, 2021 自由软件基金会。
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.
INFO-DIR-SECTION 软件开发
START-INFO-DIR-ENTRY
* help2man-zh_CN: (help2man-zh_CN). 自动手册页生成。
END-INFO-DIR-ENTRY

File: help2man-zh_CN.info.tmp, Node: Top, Next: 概览, Up: (dir)
‘help2man’
**********
‘help2man’ 可从 ‘--help’ 和 ‘--version’ 其他命令的输出生成简单的手册页。
* Menu:
* 概览:: ‘help2man’ 概览。
* 调用 help2man:: 如何运行 ‘help2man’。
* --help 建议:: 建议的 ‘--help’ 输出排版。
* 包含文字:: 在输出中包括附加文本。
* Makefile 用法:: 同 ‘make’ 一起使用‘help2man’。
* 本地化手册页:: 生成原生语言手册页。
* 示例:: ‘help2man’ 示例输出。
* 报告:: 报告程序缺陷或建议。
* 可用性:: 获取 ‘help2man’。

File: help2man-zh_CN.info.tmp, Node: 概览, Next: 调用 help2man, Prev: Top, Up: Top
1 ‘help2man’ 概览
*****************
‘help2man’ 是一种从程序输出自动生成简单的手册页的工具。
Although manual pages are optional for GNU programs other projects,
such as Debian require them (*note (standards)Man Pages::)
本程序旨在为软件作者提供一个简单的方法，使得他们可以无需认真维护却可
以在软件发行中包含手册页。
给定一个程序，若其能提供合理标准的 ‘--help’ 和 ‘--version’ 输出，
‘help2man’ 可以将那些信息整理成像手册页一样的东西。

File: help2man-zh_CN.info.tmp, Node: 调用 help2man, Next: --help 建议, Prev: 概览, Up: Top
2 如何运行 ‘help2man’。
***********************
运行 ‘help2man’ 程序的格式为:
help2man [选项]... 可执行文件
‘help2man’ 支持以下选项:
‘-n 字符串’
‘--name=字符串’
使用 字符串 作为手册页的 ‘名称’ 段的描述。
By default (for want of anything better) this paragraph contains
‘manual page for PROGRAM VERSION’.
此选项覆盖一个包含文件 ‘[名称]’ 章节 (*note 包含文字::).
‘-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’ 都必须支持给定的
语区（*note 本地化手册页::）。
‘-i FILE’
‘--include=FILE’
从 文件 包含内容（*note 包含文字::）。
‘-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.

File: help2man-zh_CN.info.tmp, Node: --help 建议, Next: 包含文字, Prev: 调用 help2man, Up: Top
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 *note (standards)Command-Line Interfaces:: and *note
(standards)Man Pages::, 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.

File: help2man-zh_CN.info.tmp, Node: 包含文字, Next: Makefile 用法, Prev: --help 建议, Up: Top
4 在输出中包括附加文本
**********************
额外的静态文字可用 ‘--include’ 和 ‘--opt-include’（*note 调用
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 (*note perlre(1): (*manpages*)perlre.)
第一节前的行，或由 ‘-’ 开始的模式，将被认为是选项。其他的都将被安静地
忽略，可被用作注释、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.

File: help2man-zh_CN.info.tmp, Node: Makefile 用法, Next: 本地化手册页, Prev: 包含文字, Up: Top
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’ 专用。

File: help2man-zh_CN.info.tmp, Node: 本地化手册页, Next: 示例, Prev: Makefile 用法, Up: Top
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’ 目前支持的语言列表，以及 *note 报告:: 以学习如何提交其它翻译
。
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 系统上测试过；请告诉我们它是否对你有用（*note 报告::）。

File: help2man-zh_CN.info.tmp, Node: 示例, Next: 报告, Prev: 本地化手册页, Up: Top
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)

File: help2man-zh_CN.info.tmp, Node: 报告, Next: 可用性, Prev: 示例, Up: Top
8 报告程序缺陷或建议
********************
如果你在此程序或本手册中发现了问题，或是有什么意见或建议，都请一并报告到
<bug-help2man@gnu.org>。
翻译员们请注意: 软件翻译通过 Translation Project
(http://translationproject.org/) 管理，请访问
<http://translationproject.org/html/translators.html> 以获取更多信息。

File: help2man-zh_CN.info.tmp, Node: 可用性, Prev: 报告, Up: Top
9 获取 ‘help2man’。
*******************
此发行的最新版本可从 GNU 在线镜像获取:
<http://ftpmirror.gnu.org/help2man/>
如自动重定向失败，镜像列表位于:
<http://www.gnu.org/order/ftp.html>
必要时可以使用 GNU 主 FTP 服务器:
<http://ftp.gnu.org/gnu/help2man/>

Tag Table:
Node: Top1155
Node: 概览1954
Node: 调用 help2man2627
Node: --help 建议5304
Node: 包含文字9178
Node: Makefile 用法11033
Node: 本地化手册页12023
Node: 示例13892
Node: 报告16521
Node: 可用性16997

End Tag Table

Local Variables:
coding: utf-8
End:
Reference in New Issue View Git Blame Copy Permalink