help2man.info

   1 This is help2man.info, produced by makeinfo version 5.2 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, 2014 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    See *note (standards)Command-Line Interfaces:: and *note
 176 (standards)Man Pages::, for the official GNU standards relating to
 177 ‘--help’ and man 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    By default ‘help2man’ has some heuristics for identifying manual page
 240 sections: a line consisting of ‘Options:’ for example will cause the
 241 following text to appear in the ‘OPTIONS’ section, and a line beginning
 242 with ‘Copyright’ will appear in the ‘COPYRIGHT’ section.  Outside of
 243 these heuristics, a line consisting of ‘*Words*’ will start a new
 244 section, and ‘Words:’ a new sub-section.
 245
 246 \1f
 247 File: help2man.info,  Node: Including text,  Next: Makefile usage,  Prev: --help recommendations,  Up: Top
 248
 249 4 Including Additional Text in the Output
 250 *****************************************
 251
 252 Additional static text may be included in the generated manual page by
 253 using the ‘--include’ and ‘--opt-include’ options (*note Invoking
 254 help2man::).  While these files can be named anything, for consistency
 255 we suggest to use the extension ‘.h2m’ for ‘help2man’ include files.
 256
 257    The format for files included with these option is simple:
 258
 259      [section]
 260      text
 261
 262      /pattern/
 263      text
 264
 265    Blocks of verbatim *roff text are inserted into the output either at
 266 the start of the given ‘[section]’ (case insensitive), or after a
 267 paragraph matching ‘/pattern/’.
 268
 269    Patterns use the Perl regular expression syntax and may be followed
 270 by the ‘i’, ‘s’ or ‘m’ modifiers (*note perlre(1): (*manpages*)perlre.)
 271
 272    Lines before the first section or pattern which begin with ‘-’ are
 273 processed as options.  Anything else is silently ignored and may be used
 274 for comments, RCS keywords and the like.
 275
 276    The section output order (for those included) is:
 277
 278      NAME
 279      SYNOPSIS
 280      DESCRIPTION
 281      OPTIONS
 282      _other_
 283      ENVIRONMENT
 284      FILES
 285      EXAMPLES
 286      AUTHOR
 287      REPORTING BUGS
 288      COPYRIGHT
 289      SEE ALSO
 290
 291    Any ‘[name]’ or ‘[synopsis]’ sections appearing in the include file
 292 will replace what would have automatically been produced (although you
 293 can still override the former with ‘--name’ if required).
 294
 295    Other sections are prepended to the automatically produced output for
 296 the standard sections given above, or included at _other_ (above) in the
 297 order they were encountered in the include file.
 298
 299    Placement of the text within the section may be explicitly requested
 300 by using the syntax ‘[<section]’, ‘[=section]’ or ‘[>section]’ to place
 301 the additional text before, in place of, or after the default output
 302 respectively.
 303
 304 \1f
 305 File: help2man.info,  Node: Makefile usage,  Next: Localised man pages,  Prev: Including text,  Up: Top
 306
 307 5 Using ‘help2man’ With ‘make’
 308 ******************************
 309
 310 A suggested use of ‘help2man’ in Makefiles is to have the manual page
 311 depend not on the binary, but on the source file(s) in which the
 312 ‘--help’ and ‘--version’ output are defined.
 313
 314    This usage allows a manual page to be generated by the maintainer and
 315 included in the distribution without requiring the end-user to have
 316 ‘help2man’ installed.
 317
 318    An example rule for the program ‘prog’ could be:
 319
 320      prog.1: $(srcdir)/main.c
 321              -$(HELP2MAN) --output=$@ --name='an example program' ./prog
 322
 323    The value of ‘HELP2MAN’ may be set in ‘configure.in’ using either of:
 324
 325      AM_MISSING_PROG(HELP2MAN, help2man)
 326
 327    for ‘automake’, or something like:
 328
 329      AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
 330
 331    for ‘autoconf’ alone.
 332
 333 \1f
 334 File: help2man.info,  Node: Localised man pages,  Next: Example,  Prev: Makefile usage,  Up: Top
 335
 336 6 Producing Native Language Manual Pages
 337 ****************************************
 338
 339 Manual pages may be produced for any locale supported by both the
 340 program and ‘help2man’ with the ‘--locale’ (‘-L’) option.
 341
 342      help2man -L fr_FR@euro -o cp.fr.1 cp
 343
 344    See <http://translationproject.org/domain/help2man.html> for the
 345 languages currently supported by ‘help2man’, and *note Reports:: for how
 346 to submit other translations.
 347
 348 6.1 Changing the Location of Message Catalogs
 349 =============================================
 350
 351 When creating localised manual pages from a program’s build directory it
 352 is probable that the translations installed in the standard location
 353 will not be (if installed at all) correct for the version of the program
 354 being built.
 355
 356    A preloadable library is provided with ‘help2man’ which will
 357 intercept ‘bindtextdomain’ calls configuring the location of message
 358 catalogs for the domain given by ‘$TEXTDOMAIN’ and override the location
 359 to the path given by ‘$LOCALEDIR’.
 360
 361    So for example:
 362
 363      mkdir -p tmp/fr/LC_MESSAGES
 364      cp po/fr.gmo tmp/fr/LC_MESSAGES/PROG.mo
 365      LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
 366        LOCALEDIR=tmp \
 367        TEXTDOMAIN=PROG \
 368        help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
 369      rm -rf tmp
 370
 371    will cause PROG to load the message catalog from ‘tmp’ rather than
 372 ‘/usr/share/locale’.
 373
 374    Notes:
 375    • The generalisation of ‘fr_FR@euro’ to ‘fr’ in the example above is
 376      done by ‘gettext’, if a more specific match were available it would
 377      also have been re-mapped.
 378
 379    • This preload has only been tested against ‘eglibc’ 2.11.2 and
 380      ‘gettext’ 0.18.1.1 on a GNU/Linux system; let me know if it does
 381      (or doesn’t) work for you (*note Reports::).
 382
 383 \1f
 384 File: help2man.info,  Node: Example,  Next: Reports,  Prev: Localised man pages,  Up: Top
 385
 386 7 Example ‘help2man’ Output
 387 ***************************
 388
 389 Given a hypothetical program ‘foo’ which produces the following output:
 390
 391      $ foo --version
 392      GNU foo 1.1
 393
 394      Copyright (C) 2011 Free Software Foundation, Inc.
 395      This is free software; see the source for copying conditions.  There is NO
 396      warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 397
 398      Written by A. Programmer.
 399      $ foo --help
 400      GNU `foo' does nothing interesting except serve as an example for
 401      `help2man'.
 402
 403      Usage: foo [OPTION]...
 404
 405      Options:
 406        -a, --option      an option
 407        -b, --another-option[=VALUE]
 408                          another option
 409
 410            --help        display this help and exit
 411            --version     output version information and exit
 412
 413      Examples:
 414        foo               do nothing
 415        foo --option      the same thing, giving `--option'
 416
 417      Report bugs to <bug-gnu-utils@gnu.org>.
 418
 419    ‘help2man’ will produce ‘nroff’ input for a manual page which will be
 420 formatted something like this:
 421
 422      FOO(1)                         User Commands                        FOO(1)
 423
 424
 425      NAME
 426             foo - manual page for foo 1.1
 427
 428      SYNOPSIS
 429             foo [OPTION]...
 430
 431      DESCRIPTION
 432             GNU  `foo'  does nothing interesting except serve as an example for
 433             `help2man'.
 434
 435      OPTIONS
 436             -a, --option
 437                    an option
 438
 439             -b, --another-option[=VALUE]
 440                    another option
 441
 442             --help display this help and exit
 443
 444             --version
 445                    output version information and exit
 446
 447      EXAMPLES
 448             foo    do nothing
 449
 450             foo --option
 451                    the same thing, giving `--option'
 452
 453      AUTHOR
 454             Written by A. Programmer.
 455
 456      REPORTING BUGS
 457             Report bugs to <bug-gnu-utils@gnu.org>.
 458
 459      COPYRIGHT
 460             Copyright © 2011 Free Software Foundation, Inc.
 461             This is free software;  see  the  source  for  copying  conditions.
 462             There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
 463             PARTICULAR PURPOSE.
 464
 465      SEE ALSO
 466             The full documentation for foo is maintained as a  Texinfo  manual.
 467             If  the  info and foo programs are properly installed at your site,
 468             the command
 469
 470                    info foo
 471
 472             should give you access to the complete manual.
 473
 474
 475      foo 1.1                          May 2011                           FOO(1)
 476
 477 \1f
 478 File: help2man.info,  Node: Reports,  Next: Availability,  Prev: Example,  Up: Top
 479
 480 8 Reporting Bugs or Suggestions
 481 *******************************
 482
 483 If you find problems or have suggestions about this program or manual,
 484 please report them to <bug-help2man@gnu.org>.
 485
 486    Note to translators: Translations are handled though the Translation
 487 Project (http://translationproject.org/) see
 488 <http://translationproject.org/html/translators.html> for details.
 489
 490 \1f
 491 File: help2man.info,  Node: Availability,  Prev: Reports,  Up: Top
 492
 493 9 Obtaining ‘help2man’
 494 **********************
 495
 496 The latest version of this distribution is available online from GNU
 497 mirrors:
 498
 499      <http://ftpmirror.gnu.org/help2man/>
 500
 501    If automatic redirection fails, the list of mirrors is at:
 502
 503      <http://www.gnu.org/order/ftp.html>
 504
 505    Or if need be you can use the main GNU ftp server:
 506      <http://ftp.gnu.org/gnu/help2man/>
 507
 508
 509 \1f
 510 Tag Table:
 511 Node: Top\7f1159
 512 Node: Overview\7f1966
 513 Node: Invoking help2man\7f2683
 514 Node: --help recommendations\7f5442
 515 Node: Including text\7f9318
 516 Node: Makefile usage\7f11320
 517 Node: Localised man pages\7f12281
 518 Node: Example\7f14185
 519 Node: Reports\7f16805
 520 Node: Availability\7f17259
 521 \1f
 522 End Tag Table
 523
 524 \1f
 525 Local Variables:
 526 coding: utf-8
 527 End: