help2man.texi

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