help2man-zh_CN.info

   1 This is help2man-zh_CN.info.tmp, produced by makeinfo version 6.5 from
   2 help2man-zh_CN.texi.
   3
   4 本文档记载 GNU ‘help2man’ 命令，用以从其他命令的 ‘--help’ 和 ‘--version’
   5 输出生成简单的手册页。
   6
   7    版权所有 (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
   8 2011, 2012, 2013, 2014, 2015 自由软件基金会。
   9
  10    Permission is granted to make and distribute verbatim copies of this
  11 manual provided the copyright notice and this permission notice are
  12 preserved on all copies.
  13
  14    Permission is granted to copy and distribute modified versions of
  15 this manual under the conditions for verbatim copying, provided that the
  16 entire resulting derived work is distributed under the terms of a
  17 permission notice identical to this one.
  18
  19    Permission is granted to copy and distribute translations of this
  20 manual into another language, under the above conditions for modified
  21 versions, except that this permission notice may be stated in a
  22 translation approved by the Foundation.
  23 INFO-DIR-SECTION 软件开发
  24 START-INFO-DIR-ENTRY
  25 * help2man-zh_CN: (help2man-zh_CN).  自动手册页生成。
  26 END-INFO-DIR-ENTRY
  27
  28 \1f
  29 File: help2man-zh_CN.info.tmp,  Node: Top,  Next: 概览,  Up: (dir)
  30
  31 ‘help2man’
  32 **********
  33
  34 ‘help2man’ 可从 ‘--help’ 和 ‘--version’ 其他命令的输出生成简单的手册页。
  35
  36 * Menu:
  37
  38 * 概览::               ‘help2man’ 概览。
  39 * 调用 help2man::  如何运行 ‘help2man’。
  40 * --help 建议::        建议的 –help 输出排版。
  41 * 包含文字::         在输出中包括附加文本。
  42 * Makefile 用法::  同 ‘make’ 一起使用‘help2man’。
  43 * 本地化手册页::   生成原生语言手册页。
  44 * 示例::               ‘help2man’ 示例输出。
  45 * 报告::               报告程序缺陷或建议。
  46 * 可用性::    获取 ‘help2man’。
  47
  48 \1f
  49 File: help2man-zh_CN.info.tmp,  Node: 概览,  Next: 调用 help2man,  Prev: Top,  Up: Top
  50
  51 1 ‘help2man’ 概览
  52 *****************
  53
  54 ‘help2man’ 是一种从程序输出自动生成简单的手册页的工具。
  55
  56    Although manual pages are optional for GNU programs other projects,
  57 such as Debian require them (*note (standards)Man Pages::)
  58
  59    本程序旨在为软件作者提供一个简单的方法，使得他们可以无需认真维护却可
  60 以在软件发行中包含手册页。
  61
  62    给定一个程序，若其能提供合理标准的 ‘--help’ 和 ‘--version’ 输出，
  63 ‘help2man’ 可以将那些信息整理成像手册页一样的东西。
  64
  65 \1f
  66 File: help2man-zh_CN.info.tmp,  Node: 调用 help2man,  Next: --help 建议,  Prev: 概览,  Up: Top
  67
  68 2 如何运行 ‘help2man’。
  69 ***********************
  70
  71 运行 ‘help2man’ 程序的格式为:
  72
  73      help2man [选项]... 可执行文件
  74
  75    ‘help2man’ 支持以下选项:
  76
  77 ‘-n 字符串’
  78 ‘--name=字符串’
  79      使用 字符串 作为手册页的 ‘名称’ 段的描述。
  80
  81      By default (for want of anything better) this paragraph contains
  82      ‘manual page for PROGRAM VERSION’.
  83
  84      此选项覆盖一个包含文件 ‘[名称]’ 章节 (*note 包含文字::).
  85
  86 ‘-s 章节’
  87 ‘--section 章节’
  88      将 章节 作为手册页的分类号。默认值为 1。
  89
  90 ‘-m MANUAL’
  91 ‘--manual=MANUAL’
  92      Set the name of the manual section to SECTION, used as a centred
  93      heading for the manual page.  By default ‘User Commands’ is used
  94      for pages in section 1, ‘Games’ for section 6 and ‘System
  95      Administration Utilities’ for sections 8 and 1M.
  96
  97 ‘-S SOURCE’
  98 ‘--source=SOURCE’
  99      The program source is used as a page footer, and often contains the
 100      name of the organisation or a suite of which the program is part.
 101      By default the value is the package name and version.
 102
 103 ‘-L LOCALE’
 104 ‘-L LOCALE’
 105      设置输出语区（默认为 ‘C’）。程序本身和 ‘help2man’ 都必须支持给定的
 106      语区（*note 本地化手册页::）。
 107
 108 ‘-i FILE’
 109 ‘--include=FILE’
 110      从 文件 包含内容（*note 包含文字::）。
 111
 112 ‘-I FILE’
 113 ‘--opt-include=FILE’
 114      A variant of ‘--include’ for use in Makefile pattern rules which
 115      does not require FILE to exist.
 116
 117 ‘-o FILE’
 118 ‘--output=FILE’
 119      将输出写入到 FILE 而非 ‘stdout’。
 120
 121 ‘-p TEXT’
 122 ‘--info-page=TEXT’
 123      Texinfo 手册名称。
 124
 125 ‘-N’
 126 ‘--no-info’
 127      Suppress inclusion of a ‘SEE ALSO’ paragraph directing the reader
 128      to the Texinfo documentation.
 129
 130 ‘-l’
 131 ‘--libtool’
 132      Drop ‘lt-’ prefix from instances of the program name in the
 133      synopsis (‘libtool’ creates wrapper scripts in the build directory
 134      which invoke ‘foo’ as ‘.libs/lt-foo’).
 135
 136 ‘--help’
 137 ‘--version’
 138      显示帮助或版本信息。
 139
 140    By default ‘help2man’ passes the standard ‘--help’ and ‘--version’
 141 options to the executable although alternatives may be specified using:
 142
 143 ‘-h OPTION’
 144 ‘--help-option=OPTION’
 145      帮助选项字串。
 146
 147 ‘-v OPTION’
 148 ‘-h OPTION’
 149      版本选项字串。
 150
 151 ‘--version-string=STRING’
 152      版本字串。
 153
 154 ‘--no-discard-stderr’
 155      Include stderr when parsing option output.
 156
 157 \1f
 158 File: help2man-zh_CN.info.tmp,  Node: --help 建议,  Next: 包含文字,  Prev: 调用 help2man,  Up: Top
 159
 160 3 ‘--help’ 建议
 161 ***************
 162
 163 Here are some recommendations for what to include in your ‘--help’
 164 output.  Including these gives ‘help2man’ the best chance at generating
 165 a respectable man page, as well as benefitting users directly.
 166
 167    See *note (standards)Command-Line Interfaces:: and *note
 168 (standards)Man Pages::, for the official GNU standards relating to
 169 ‘--help’ and man pages.
 170
 171    • A synopsis of how to invoke the program.  If different usages of
 172      the program have different invocations, then list them all.  For
 173      example (edited for brevity):
 174
 175           Usage: cp [OPTION]... SOURCE DEST
 176             or:  cp [OPTION]... SOURCE... DIRECTORY
 177           ...
 178
 179      Use ‘argv[0]’ for the program name in these synopses, just as it
 180      is, with no directory stripping.  This is in contrast to the
 181      canonical (constant) name of the program which is used in
 182      ‘--version’.
 183
 184    • A very brief explanation of what the program does, including
 185      default and/or typical behaviour.  For example, here is ‘cp’’s:
 186
 187           将 SOURCE 拷贝到 DEST，或将多个 SOURCE 拷贝到 DIRECTORY。
 188
 189    • A list of options, indented to column 2.  If the program supports
 190      one-character options, put those first, then the equivalent long
 191      option (if any).  If the option takes an argument, include that
 192      too, giving it a meaningful name.  Align the descriptions in a
 193      convenient column, if desired.  Note that to be correctly
 194      recognised by ‘help2man’ the description must be separated from the
 195      options by at least two spaces and descriptions continued on
 196      subsequent lines must start at the same column.
 197
 198      Here again is an (edited) excerpt from ‘cp’, showing a short option
 199      with an equivalent long option, a long option only, and a short
 200      option only:
 201
 202             -a, --archive                相当于 -dpR
 203                 --backup[=CONTROL]       对每个文件备份 ...
 204             -b                           就像 --backup 不过 ...
 205
 206      For programs that take many options, it may be desirable to split
 207      the option list into sections such as ‘Global’, ‘Output control’,
 208      or whatever makes sense in the particular case.  It is usually best
 209      to alphabetise (by short option name first, then long) within each
 210      section, or the entire list if there are no sections.
 211
 212    • Any useful additional information about program behaviour, such as
 213      influential environment variables, further explanation of options,
 214      etc.  For example, ‘cp’ discusses ‘VERSION_CONTROL’ and sparse
 215      files.
 216
 217    • A few examples of typical usage, at your discretion.  One good
 218      example is usually worth a thousand words of description, so this
 219      is highly recommended.
 220
 221    • In closing, a line stating how to email bug reports.  Typically,
 222      MAILING-ADDRESS will be ‘bug-PROGRAM@gnu.org’; please use this form
 223      for GNU programs whenever possible.  It’s also good to mention the
 224      home page of the program, other mailing lists, etc.
 225
 226    The ‘argp’ and ‘popt’ programming interfaces let you specify option
 227 descriptions for ‘--help’ in the same structure as the rest of the
 228 option definition; you may wish to consider using these routines for
 229 option parsing instead of ‘getopt’.
 230
 231    By default ‘help2man’ has some heuristics for identifying manual page
 232 sections: a line consisting of ‘Options:’ for example will cause the
 233 following text to appear in the ‘OPTIONS’ section, and a line beginning
 234 with ‘Copyright’ will appear in the ‘COPYRIGHT’ section.  Outside of
 235 these heuristics, a line consisting of ‘*Words*’ will start a new
 236 section, and ‘Words:’ a new sub-section.
 237
 238 \1f
 239 File: help2man-zh_CN.info.tmp,  Node: 包含文字,  Next: Makefile 用法,  Prev: --help 建议,  Up: Top
 240
 241 4 在输出中包括附加文本
 242 **********************
 243
 244 额外的静态文字可用 ‘--include’ 和 ‘--opt-include’（*note 调用
 245 help2man::）加入生成的手册页中。尽管这些文件可以任意命名，我们还是推荐使
 246 用将 ‘.h2m’ 拓展名用于 ‘help2man’ 包含文件以保证一致性。
 247
 248    The format for files included with these option is simple:
 249
 250      [章节]
 251      文本
 252
 253      /正则表达式/
 254      文本
 255
 256    逐字 *roff 文字块将在给定的 ‘[章节]’（大小写不敏感）开始处，或在匹配
 257 ‘/正则表达式/’ 的段后加入。
 258
 259    Patterns use the Perl regular expression syntax and may be followed
 260 by the ‘i’, ‘s’ or ‘m’ modifiers (*note perlre(1): (*manpages*)perlre.)
 261
 262    第一节前的行，或由 ‘-’ 开始的模式，将被认为是选项。其他的都将被安静地
 263 忽略，可被用作注释、RCS 关键字等。
 264
 265    章节输出（包含的）顺序为：
 266
 267      NAME
 268      SYNOPSIS
 269      DESCRIPTION
 270      OPTIONS
 271      _other_
 272      ENVIRONMENT
 273      FILES
 274      EXAMPLES
 275      AUTHOR
 276      REPORTING BUGS
 277      COPYRIGHT
 278      SEE ALSO
 279
 280    Any ‘[name]’ or ‘[synopsis]’ sections appearing in the include file
 281 will replace what would have automatically been produced (although you
 282 can still override the former with ‘--name’ if required).
 283
 284    其他章节会自动附加到以上自动生成章节之上，或按照它们在包含文件中出现
 285 的顺序包含于 _其他_（以上）章节上。
 286
 287    Placement of the text within the section may be explicitly requested
 288 by using the syntax ‘[<section]’, ‘[=section]’ or ‘[>section]’ to place
 289 the additional text before, in place of, or after the default output
 290 respectively.
 291
 292 \1f
 293 File: help2man-zh_CN.info.tmp,  Node: Makefile 用法,  Next: 本地化手册页,  Prev: 包含文字,  Up: Top
 294
 295 5 同 ‘make’ 一起使用 ‘help2man’。
 296 *********************************
 297
 298 A suggested use of ‘help2man’ in Makefiles is to have the manual page
 299 depend not on the binary, but on the source file(s) in which the
 300 ‘--help’ and ‘--version’ output are defined.
 301
 302    This usage allows a manual page to be generated by the maintainer and
 303 included in the distribution without requiring the end-user to have
 304 ‘help2man’ installed.
 305
 306    An example rule for the program ‘prog’ could be:
 307
 308      prog.1: $(srcdir)/main.c
 309              -$(HELP2MAN) --output=$@ --name='an example program' ./prog
 310
 311    The value of ‘HELP2MAN’ may be set in ‘configure.in’ using either of:
 312
 313      AM_MISSING_PROG(HELP2MAN, help2man)
 314
 315    ‘automake’，或类似如下例子：
 316
 317      AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
 318
 319    仅为 ‘autoconf’ 专用。
 320
 321 \1f
 322 File: help2man-zh_CN.info.tmp,  Node: 本地化手册页,  Next: 示例,  Prev: Makefile 用法,  Up: Top
 323
 324 6 生成原生语言手册页
 325 ********************
 326
 327 Manual pages may be produced for any locale supported by both the
 328 program and ‘help2man’ with the ‘--locale’ (‘-L’) option.
 329
 330      help2man -L fr_FR@euro -o cp.fr.1 cp
 331
 332    参见 <http://translationproject.org/domain/help2man.html> 以获取
 333 ‘help2man’ 目前支持的语言列表，以及 *note 报告:: 以学习如何提交其它翻译
 334 。
 335
 336 6.1 Changing the Location of Message Catalogs
 337 =============================================
 338
 339 When creating localised manual pages from a program’s build directory it
 340 is probable that the translations installed in the standard location
 341 will not be (if installed at all) correct for the version of the program
 342 being built.
 343
 344    A preloadable library is provided with ‘help2man’ which will
 345 intercept ‘bindtextdomain’ calls configuring the location of message
 346 catalogs for the domain given by ‘$TEXTDOMAIN’ and override the location
 347 to the path given by ‘$LOCALEDIR’.
 348
 349    举个例子:
 350
 351      mkdir -p tmp/fr/LC_MESSAGES
 352      cp po/fr.gmo tmp/fr/LC_MESSAGES/PROG.mo
 353      LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
 354        LOCALEDIR=tmp \
 355        TEXTDOMAIN=PROG \
 356        help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
 357      rm -rf tmp
 358
 359    will cause PROG to load the message catalog from ‘tmp’ rather than
 360 ‘/usr/share/locale’.
 361
 362    注：
 363    • The generalisation of ‘fr_FR@euro’ to ‘fr’ in the example above is
 364      done by ‘gettext’, if a more specific match were available it would
 365      also have been re-mapped.
 366
 367    • 此预加载库只配合 ‘eglibc’ 2.11.2 和 ‘gettext’ 0.18.1.1 在一个
 368      GNU/Linux 系统上测试过；请告诉我们它是否对你有用（*note 报告::）。
 369
 370 \1f
 371 File: help2man-zh_CN.info.tmp,  Node: 示例,  Next: 报告,  Prev: 本地化手册页,  Up: Top
 372
 373 7 ‘help2man’ 示例输出。
 374 ***********************
 375
 376 Given a hypothetical program ‘foo’ which produces the following output:
 377
 378      $ foo --version
 379      GNU foo 1.1
 380
 381      版权所有 (C) 2011 自由软件基金会。
 382      本软件为自由软件；请参阅源代码以获取许可条款。此软件不对包括商业使用以及其他
 383      特殊用途提供任何担保。
 384
 385      Written by A. Programmer.
 386      $ foo --help
 387      GNU `foo' does nothing interesting except serve as an example for
 388      `help2man'.
 389
 390      用法: foo [选项] ...
 391
 392      Options:
 393        -a, --option      an option
 394        -b, --another-option[=VALUE]
 395                          another option
 396
 397            --help           显示此帮助信息并退出
 398            --version     输出版本信息并退出
 399
 400      示例:
 401        foo               什么都不做
 402        foo --option      效果一致，传入参数 `--option'
 403
 404      请将问题报告给 <bug-gnu-utils@gnu.org>。
 405
 406    ‘help2man’ will produce ‘nroff’ input for a manual page which will be
 407 formatted something like this:
 408
 409      FOO(1)                         用户命令                        FOO(1)
 410
 411      NAME
 412             foo - manual page for foo 1.1
 413
 414      SYNOPSIS
 415             foo [OPTION]...
 416
 417      DESCRIPTION
 418             GNU  `foo'  does nothing interesting except serve as an example for
 419             `help2man'.
 420
 421      OPTIONS
 422             -a, --option
 423                    an option
 424
 425             -b, --another-option[=VALUE]
 426                    another option
 427
 428         --help 显示此帮助信息并推出
 429
 430            --version
 431                    输出版本信息并退出
 432
 433      EXAMPLES
 434             foo    do nothing
 435
 436             foo --option
 437                    the same thing, giving `--option'
 438
 439      AUTHOR
 440             Written by A. Programmer.
 441
 442      REPORTING BUGS
 443             Report bugs to <bug-gnu-utils@gnu.org>.
 444
 445      COPYRIGHT
 446             版权所有 (C) 2011 自由软件基金会。
 447            本软件为自由软件；请参阅源代码以获取许可条款。
 448             此软件不对提供任何担保，甚至不保证适销性或对某一特定用途的适用性的保证。
 449      SEE ALSO
 450             The full documentation for foo is maintained as a  Texinfo  manual.
 451             If  the  info and foo programs are properly installed at your site,
 452             the command
 453
 454                    info foo
 455
 456             应可给您显示完整的手册页。
 457
 458      foo 1.1                          2011 五月                           FOO(1)
 459
 460 \1f
 461 File: help2man-zh_CN.info.tmp,  Node: 报告,  Next: 可用性,  Prev: 示例,  Up: Top
 462
 463 8 报告程序缺陷或建议
 464 ********************
 465
 466 如果你在此程序或本手册中发现了问题，或是有什么意见或建议，都请一并报告到
 467 <bug-help2man@gnu.org>。
 468
 469    翻译员们请注意: 软件翻译通过 Translation Project
 470 (http://translationproject.org/) 管理，请访问
 471 <http://translationproject.org/html/translators.html> 以获取更多信息。
 472
 473 \1f
 474 File: help2man-zh_CN.info.tmp,  Node: 可用性,  Prev: 报告,  Up: Top
 475
 476 9 获取 ‘help2man’。
 477 *******************
 478
 479 此发行的最新版本可从 GNU 在线镜像获取:
 480
 481      <http://ftpmirror.gnu.org/help2man/>
 482
 483    如自动重定向失败，镜像列表位于:
 484
 485      <http://www.gnu.org/order/ftp.html>
 486
 487    必要时可以使用 GNU 主 FTP 服务器:
 488      <http://ftp.gnu.org/gnu/help2man/>
 489
 490 \1f
 491 Tag Table:
 492 Node: Top\7f1143
 493 Node: 概览\7f1937
 494 Node: 调用 help2man\7f2610
 495 Node: --help 建议\7f5287
 496 Node: 包含文字\7f9161
 497 Node: Makefile 用法\7f11016
 498 Node: 本地化手册页\7f12006
 499 Node: 示例\7f13875
 500 Node: 报告\7f16504
 501 Node: 可用性\7f16980
 502 \1f
 503 End Tag Table
 504
 505 \1f
 506 Local Variables:
 507 coding: utf-8
 508 End: