help2man.texi

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