help2man.info

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