help2man.info

   1 This is help2man.info, produced by makeinfo version 4.13 from
   2 help2man.texi.
   3
   4 INFO-DIR-SECTION Software development
   5 START-INFO-DIR-ENTRY
   6 * help2man: (help2man).      Automatic manual page generation.
   7 END-INFO-DIR-ENTRY
   8
   9    This file documents the GNU `help2man' command which produces simple
  10 manual pages from the `--help' and `--version' output of other commands.
  11
  12    Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
  13 2011 Free Software Foundation, Inc.
  14
  15    Permission is granted to make and distribute verbatim copies of this
  16 manual provided the copyright notice and this permission notice are
  17 preserved on all copies.
  18
  19    Permission is granted to copy and distribute modified versions of
  20 this manual under the conditions for verbatim copying, provided that
  21 the entire resulting derived work is distributed under the terms of a
  22 permission notice identical to this one.
  23
  24    Permission is granted to copy and distribute translations of this
  25 manual into another language, under the above conditions for modified
  26 versions, except that this permission notice may be stated in a
  27 translation approved by the Foundation.
  28
  29 \1f
  30 File: help2man.info,  Node: Top,  Next: Overview,  Up: (dir)
  31
  32 `help2man'
  33 **********
  34
  35 `help2man' produces simple manual pages from the `--help' and
  36 `--version' output of other commands.
  37
  38 * Menu:
  39
  40 * Overview::                    Overview of `help2man'.
  41 * Invoking help2man::           How to run `help2man'.
  42 * --help recommendations::      Recommended formatting for --help output.
  43 * Including text::              Including additional text in the output.
  44 * Makefile usage::              Using `help2man' with `make'.
  45 * Localised man pages::         Producing native language manual pages.
  46 * Example::                     Example `help2man' output.
  47 * Reports::                     Reporting bugs or suggestions.
  48 * Availability::                Obtaining `help2man'.
  49
  50 \1f
  51 File: help2man.info,  Node: Overview,  Next: Invoking help2man,  Prev: Top,  Up: Top
  52
  53 1 Overview of `help2man'
  54 ************************
  55
  56 `help2man' is a tool for automatically generating simple manual pages
  57 from program output.
  58
  59    Although manual pages are optional for GNU programs other projects,
  60 such as Debian require them (*note Man Pages: (standards)Man Pages.)
  61
  62    This program is intended to provide an easy way for software authors
  63 to include a manual page in their distribution without having to
  64 maintain that document.
  65
  66    Given a program which produces reasonably standard `--help' and
  67 `--version' outputs, `help2man' can re-arrange that output into
  68 something which resembles a manual page.
  69
  70 \1f
  71 File: help2man.info,  Node: Invoking help2man,  Next: --help recommendations,  Prev: Overview,  Up: Top
  72
  73 2 How to Run `help2man'
  74 ***********************
  75
  76 The format for running the `help2man' program is:
  77
  78      `help2man' [OPTION]... EXECUTABLE
  79
  80    `help2man' supports the following options:
  81
  82 `-n STRING'
  83 `--name=STRING'
  84      Use STRING as the description for the `NAME' paragraph of the
  85      manual page.
  86
  87      By default (for want of anything better) this paragraph contains
  88      `manual page for PROGRAM VERSION'.
  89
  90      This option overrides an include file `[name]' section (*note
  91      Including text::).
  92
  93 `-s SECTION'
  94 `--section SECTION'
  95      Use SECTION as the section for the man page.  The default section
  96      is 1.
  97
  98 `-m MANUAL'
  99 `--manual=MANUAL'
 100      Set the name of the manual section to SECTION, used as a centred
 101      heading for the manual page.  By default `User Commands' is used
 102      for pages in section 1, `Games' for section 6 and `System
 103      Administration Utilities' for sections 8 and 1M.
 104
 105 `-S SOURCE'
 106 `--source=SOURCE'
 107      The program source is used as a page footer, and often contains
 108      the name of the organisation or a suite of which the program is
 109      part.  By default the value is the package name and version.
 110
 111 `-L LOCALE'
 112 `--locale=LOCALE'
 113      Select output locale (default `C').  Both the program and
 114      `help2man' must support the given LOCALE (*note Localised man
 115      pages::).
 116
 117 `-i FILE'
 118 `--include=FILE'
 119      Include material from FILE (*note Including text::).
 120
 121 `-I FILE'
 122 `--opt-include=FILE'
 123      A variant of `--include' for use in Makefile pattern rules which
 124      does not require FILE to exist.
 125
 126 `-o FILE'
 127 `--output=FILE'
 128      Send output to FILE rather than `stdout'.
 129
 130 `-p TEXT'
 131 `--info-page=TEXT'
 132      Name of Texinfo manual.
 133
 134 `-N'
 135 `--no-info'
 136      Suppress inclusion of a `SEE ALSO' paragraph directing the reader
 137      to the Texinfo documentation.
 138
 139 `-l'
 140 `--libtool'
 141      Drop `lt-' prefix from instances of the program name in the
 142      synopsis (`libtool' creates wrapper scripts in the build directory
 143      which invoke `foo' as `.libs/lt-foo').
 144
 145 `--help'
 146 `--version'
 147      Show help or version information.
 148
 149    By default `help2man' passes the standard `--help' and `--version'
 150 options to the executable although alternatives may be specified using:
 151
 152 `-h OPTION'
 153 `--help-option=OPTION'
 154      Help option string.
 155
 156 `-v OPTION'
 157 `--version-option=OPTION'
 158      Version option string.
 159
 160 `--version-string=STRING'
 161      Version string.
 162
 163 `--no-discard-stderr'
 164      Include stderr when parsing option output.
 165
 166 \1f
 167 File: help2man.info,  Node: --help recommendations,  Next: Including text,  Prev: Invoking help2man,  Up: Top
 168
 169 3 `--help' Recommendations
 170 **************************
 171
 172 Here are some recommendations for what to include in your `--help'
 173 output.  Including these gives `help2man' the best chance at generating
 174 a respectable man page, as well as benefitting users directly.
 175
 176    *Note Command-Line Interfaces: (standards)Command-Line Interfaces,
 177 and *note Man Pages: (standards)Man Pages, for the official GNU
 178 standards relating to `--help' and man pages.
 179
 180    * A synopsis of how to invoke the program.  If different usages of
 181      the program have different invocations, then list them all.  For
 182      example (edited for brevity):
 183
 184           Usage: cp [OPTION]... SOURCE DEST
 185             or:  cp [OPTION]... SOURCE... DIRECTORY
 186           ...
 187
 188      Use `argv[0]' for the program name in these synopses, just as it
 189      is, with no directory stripping.  This is in contrast to the
 190      canonical (constant) name of the program which is used in
 191      `--version'.
 192
 193    * A very brief explanation of what the program does, including
 194      default and/or typical behaviour.  For example, here is `cp''s:
 195
 196           Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
 197
 198    * A list of options, indented to column 2.  If the program supports
 199      one-character options, put those first, then the equivalent long
 200      option (if any).  If the option takes an argument, include that
 201      too, giving it a meaningful name.  Align the descriptions in a
 202      convenient column, if desired.  Note that to be correctly
 203      recognised by `help2man' the description must be separated from
 204      the options by at least two spaces and descriptions continued on
 205      subsequent lines must start at the same column.
 206
 207      Here again is an (edited) excerpt from `cp', showing a short
 208      option with an equivalent long option, a long option only, and a
 209      short option only:
 210
 211             -a, --archive                same as -dpR
 212                 --backup[=CONTROL]       make a backup of each ...
 213             -b                           like --backup but ...
 214
 215      For programs that take many options, it may be desirable to split
 216      the option list into sections such as `Global', `Output control',
 217      or whatever makes sense in the particular case.  It is usually
 218      best to alphabetise (by short option name first, then long) within
 219      each section, or the entire list if there are no sections.
 220
 221    * Any useful additional information about program behaviour, such as
 222      influential environment variables, further explanation of options,
 223      etc.  For example, `cp' discusses `VERSION_CONTROL' and sparse
 224      files.
 225
 226    * A few examples of typical usage, at your discretion.  One good
 227      example is usually worth a thousand words of description, so this
 228      is highly recommended.
 229
 230    * In closing, a line stating how to email bug reports.  Typically,
 231      MAILING-ADDRESS will be `bug-PROGRAM@gnu.org'; please use this
 232      form for GNU programs whenever possible.  It's also good to
 233      mention the home page of the program, other mailing lists, etc.
 234
 235
 236    The `argp' and `popt' programming interfaces let you specify option
 237 descriptions for `--help' in the same structure as the rest of the
 238 option definition; you may wish to consider using these routines for
 239 option parsing instead of `getopt'.
 240
 241 \1f
 242 File: help2man.info,  Node: Including text,  Next: Makefile usage,  Prev: --help recommendations,  Up: Top
 243
 244 4 Including Additional Text in the Output
 245 *****************************************
 246
 247 Additional static text may be included in the generated manual page by
 248 using the `--include' and `--opt-include' options (*note Invoking
 249 help2man::).  While these files can be named anything, for consistency
 250 we suggest to use the extension `.h2m' for help2man include files.
 251
 252    The format for files included with these option is simple:
 253
 254      [section]
 255      text
 256
 257      /pattern/
 258      text
 259
 260    Blocks of verbatim *roff text are inserted into the output either at
 261 the start of the given `[section]' (case insensitive), or after a
 262 paragraph matching `/pattern/'.
 263
 264    Patterns use the Perl regular expression syntax and may be followed
 265 by the `i', `s' or `m' modifiers (*note perlre(1): (*manpages*)perlre.)
 266
 267    Lines before the first section or pattern which begin with `-' are
 268 processed as options.  Anything else is silently ignored and may be
 269 used for comments, RCS keywords and the like.
 270
 271    The section output order (for those included) is:
 272
 273      NAME
 274      SYNOPSIS
 275      DESCRIPTION
 276      OPTIONS
 277      ENVIRONMENT
 278      FILES
 279      EXAMPLES
 280      _other_
 281      AUTHOR
 282      REPORTING BUGS
 283      COPYRIGHT
 284      SEE ALSO
 285
 286    Any `[name]' or `[synopsis]' sections appearing in the include file
 287 will replace what would have automatically been produced (although you
 288 can still override the former with `--name' if required).
 289
 290    Other sections are prepended to the automatically produced output for
 291 the standard sections given above, or included at _other_ (above) in
 292 the order they were encountered in the include file.
 293
 294 \1f
 295 File: help2man.info,  Node: Makefile usage,  Next: Localised man pages,  Prev: Including text,  Up: Top
 296
 297 5 Using `help2man' With `make'
 298 ******************************
 299
 300 A suggested use of `help2man' in Makefiles is to have the manual page
 301 depend not on the binary, but on the source file(s) in which the
 302 `--help' and `--version' output are defined.
 303
 304    This usage allows a manual page to be generated by the maintainer and
 305 included in the distribution without requiring the end-user to have
 306 `help2man' installed.
 307
 308    An example rule for the program `prog' could be:
 309
 310      prog.1: $(srcdir)/main.c
 311              -$(HELP2MAN) --output=$@ --name='an example program' ./prog
 312
 313    The value of `HELP2MAN' may be set in `configure.in' using either of:
 314
 315      AM_MISSING_PROG(HELP2MAN, help2man, $missing_dir)
 316
 317    for `automake', or something like:
 318
 319      AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
 320
 321    for `autoconf' alone.
 322
 323 \1f
 324 File: help2man.info,  Node: Localised man pages,  Next: Example,  Prev: Makefile usage,  Up: Top
 325
 326 6 Producing Native Language Manual Pages
 327 ****************************************
 328
 329 Manual pages may be produced for any locale supported by both the
 330 program and `help2man' with the `--locale' (`-L') option.
 331
 332      help2man -L fr_FR@euro -o cp.fr.1 cp
 333
 334    See `http://translationproject.org/domain/help2man.html' for the
 335 languages currently supported by `help2man', and *note Reports:: for
 336 how to submit other translations.
 337
 338 6.1 Changing the Location of Message Catalogs
 339 =============================================
 340
 341 When creating localised manual pages from a program's build directory it
 342 is probable that the translations installed in the standard location
 343 will not be (if installed at all) correct for the version of the
 344 program being built.
 345
 346    A preloadable library is provided with `help2man' which will
 347 intercept `bindtextdomain' calls configuring the location of message
 348 catalogs for the domain given by `$TEXTDOMAIN' and override the
 349 location to the path given by `$LOCALEDIR'.
 350
 351    So for example:
 352
 353      mkdir -p tmp/fr/LC_MESSAGES
 354      cp po/fr.gmo tmp/fr/LC_MESSAGES/PROG.mo
 355      LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
 356        LOCALEDIR=tmp \
 357        TEXTDOMAIN=PROG \
 358        help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
 359      rm -rf tmp
 360
 361    will cause PROG to load the message catalog from `tmp' rather than
 362 `/usr/share/locale'.
 363
 364    Notes:
 365    * The generalisation of `fr_FR@euro' to `fr' in the example above is
 366      done by `gettext', if a more specific match were available it
 367      would also have been re-mapped.
 368
 369    * This preload has only been tested against `eglibc' 2.11.2 and
 370      `gettext' 0.18.1.1 on a GNU/Linux system; let me know if it does
 371      (or doesn't) work for you (*note Reports::).
 372
 373 \1f
 374 File: help2man.info,  Node: Example,  Next: Reports,  Prev: Localised man pages,  Up: Top
 375
 376 7 Example `help2man' Output
 377 ***************************
 378
 379 Given a hypothetical program `foo' which produces the following output:
 380
 381      $ foo --version
 382      GNU foo 1.1
 383
 384      Copyright (C) 2011 Free Software Foundation, Inc.
 385      This is free software; see the source for copying conditions.  There is NO
 386      warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 387
 388      Written by A. Programmer.
 389      $ foo --help
 390      GNU `foo' does nothing interesting except serve as an example for
 391      `help2man'.
 392
 393      Usage: foo [OPTION]...
 394
 395      Options:
 396        -a, --option      an option
 397        -b, --another-option[=VALUE]
 398                          another option
 399
 400            --help        display this help and exit
 401            --version     output version information and exit
 402
 403      Examples:
 404        foo               do nothing
 405        foo --option      the same thing, giving `--option'
 406
 407      Report bugs to <bug-gnu-utils@gnu.org>.
 408
 409    `help2man' will produce `nroff' input for a manual page which will
 410 be formatted something like this:
 411
 412      FOO(1)                         User Commands                        FOO(1)
 413
 414
 415      NAME
 416             foo - manual page for foo 1.1
 417
 418      SYNOPSIS
 419             foo [OPTION]...
 420
 421      DESCRIPTION
 422             GNU  `foo'  does nothing interesting except serve as an example for
 423             `help2man'.
 424
 425      OPTIONS
 426             -a, --option
 427                    an option
 428
 429             -b, --another-option[=VALUE]
 430                    another option
 431
 432             --help display this help and exit
 433
 434             --version
 435                    output version information and exit
 436
 437      EXAMPLES
 438             foo    do nothing
 439
 440             foo --option
 441                    the same thing, giving `--option'
 442
 443      AUTHOR
 444             Written by A. Programmer.
 445
 446      REPORTING BUGS
 447             Report bugs to <bug-gnu-utils@gnu.org>.
 448
 449      COPYRIGHT
 450             Copyright (C) 2011 Free Software Foundation, Inc.
 451             This is free software;  see  the  source  for  copying  conditions.
 452             There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
 453             PARTICULAR PURPOSE.
 454
 455      SEE ALSO
 456             The full documentation for foo is maintained as a  Texinfo  manual.
 457             If  the  info and foo programs are properly installed at your site,
 458             the command
 459
 460                    info foo
 461
 462             should give you access to the complete manual.
 463
 464
 465      foo 1.1                          May 2011                           FOO(1)
 466
 467 \1f
 468 File: help2man.info,  Node: Reports,  Next: Availability,  Prev: Example,  Up: Top
 469
 470 8 Reporting Bugs or Suggestions
 471 *******************************
 472
 473 If you find problems or have suggestions about this program or manual,
 474 please report them to <bug-help2man@gnu.org>.
 475
 476    Note to translators: Translations are handled though the Translation
 477 Project (http://translationproject.org/) see
 478 `http://translationproject.org/html/translators.html' for details.
 479
 480 \1f
 481 File: help2man.info,  Node: Availability,  Prev: Reports,  Up: Top
 482
 483 9 Obtaining `help2man'
 484 **********************
 485
 486 The latest version of this distribution is available online from GNU
 487 mirrors:
 488
 489      `http://ftpmirror.gnu.org/help2man/'
 490
 491    If automatic redirection fails, the list of mirrors is at:
 492
 493      `http://www.gnu.org/order/ftp.html'
 494
 495    Or if need be you can use the main GNU ftp server:
 496      `http://ftp.gnu.org/gnu/help2man/'
 497
 498
 499 \1f
 500 Tag Table:
 501 Node: Top\7f1134
 502 Node: Overview\7f1900
 503 Node: Invoking help2man\7f2607
 504 Node: --help recommendations\7f5165
 505 Node: Including text\7f8564
 506 Node: Makefile usage\7f10272
 507 Node: Localised man pages\7f11203
 508 Node: Example\7f13039
 509 Node: Reports\7f15644
 510 Node: Availability\7f16098
 511 \1f
 512 End Tag Table