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
  17 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, 2011
  49 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 `Global', `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 @node Including text
 293 @chapter Including Additional Text in the Output
 294
 295 Additional static text may be included in the generated manual page by
 296 using the @samp{--include} and @samp{--opt-include} options
 297 (@pxref{Invoking help2man}).  While these files can be named anything,
 298 for consistency we suggest to use the extension @code{.h2m} for
 299 help2man include files.
 300
 301 The format for files included with these option is simple:
 302
 303 @example
 304 [section]
 305 text
 306
 307 /pattern/
 308 text
 309 @end example
 310
 311 Blocks of verbatim *roff text are inserted into the output either at
 312 the start of the given @samp{[section]} (case insensitive), or after a
 313 paragraph matching @samp{/pattern/}.
 314
 315 Patterns use the Perl regular expression syntax and may be followed by
 316 the @samp{i}, @samp{s} or @samp{m} modifiers (@pxref{perlre, ,
 317 perlre(1), *manpages*, The @code{perlre(1)} manual page})
 318
 319 Lines before the first section or pattern which begin with @samp{-}
 320 are processed as options.  Anything else is silently ignored and may
 321 be used for comments, RCS keywords and the like.
 322
 323 The section output order (for those included) is:
 324
 325 @example
 326 NAME
 327 SYNOPSIS
 328 DESCRIPTION
 329 OPTIONS
 330 ENVIRONMENT
 331 FILES
 332 EXAMPLES
 333 @emph{other}
 334 AUTHOR
 335 REPORTING BUGS
 336 COPYRIGHT
 337 SEE ALSO
 338 @end example
 339
 340 Any @samp{[name]} or @samp{[synopsis]} sections appearing in the
 341 include file will replace what would have automatically been produced
 342 (although you can still override the former with @samp{--name} if
 343 required).
 344
 345 Other sections are prepended to the automatically produced output for
 346 the standard sections given above, or included at @emph{other} (above)
 347 in the order they were encountered in the include file.
 348
 349 @node Makefile usage
 350 @chapter Using @command{help2man} With @command{make}
 351
 352 A suggested use of @command{help2man} in Makefiles is to have the
 353 manual page depend not on the binary, but on the source file(s) in
 354 which the @samp{--help} and @samp{--version} output are defined.
 355
 356 This usage allows a manual page to be generated by the maintainer and
 357 included in the distribution without requiring the end-user to have
 358 @command{help2man} installed.
 359
 360 An example rule for the program @code{prog} could be:
 361
 362 @example
 363 @group
 364 prog.1: $(srcdir)/main.c
 365         -$(HELP2MAN) --output=$@@ --name='an example program' ./prog
 366 @end group
 367 @end example
 368
 369 The value of @code{HELP2MAN} may be set in @code{configure.in} using
 370 either of:
 371
 372 @example
 373 AM_MISSING_PROG(HELP2MAN, help2man, $missing_dir)
 374 @end example
 375
 376 for @command{automake}, or something like:
 377
 378 @example
 379 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
 380 @end example
 381
 382 for @command{autoconf} alone.
 383
 384 @node Localised man pages
 385 @chapter Producing Native Language Manual Pages
 386
 387 Manual pages may be produced for any locale supported by both the
 388 program and @command{help2man} with the @samp{--locale} (@samp{-L})
 389 option.
 390
 391 @example
 392 help2man -L fr_FR@@euro -o cp.fr.1 cp
 393 @end example
 394
 395 See @url{http://translationproject.org/domain/help2man.html} for the
 396 languages currently supported by @command{help2man}, and
 397 @pxref{Reports} for how to submit other translations.
 398
 399 @section Changing the Location of Message Catalogs
 400
 401 When creating localised manual pages from a program's build directory it
 402 is probable that the translations installed in the standard location
 403 will not be (if installed at all) correct for the version of the
 404 program being built.
 405
 406 A preloadable library is provided with @command{help2man} which will
 407 intercept @code{bindtextdomain} calls configuring the location of message
 408 catalogs for the domain given by @env{$TEXTDOMAIN} and override the
 409 location to the path given by @env{$LOCALEDIR}.
 410
 411 So for example:
 412
 413 @example
 414 mkdir -p tmp/fr/LC_MESSAGES
 415 cp po/fr.gmo tmp/fr/LC_MESSAGES/@var{prog}.mo
 416 LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
 417   LOCALEDIR=tmp \
 418   TEXTDOMAIN=@var{prog} \
 419   help2man -L fr_FR@@euro -i @var{prog}.fr.h2m -o @var{prog}.fr.1 @var{prog}
 420 rm -rf tmp
 421 @end example
 422
 423 will cause @var{prog} to load the message catalog from @samp{tmp}
 424 rather than @samp{/usr/share/locale}.
 425
 426 Notes:
 427 @itemize @bullet
 428 @item
 429 The generalisation of @samp{fr_FR@@euro} to @samp{fr} in the example
 430 above is done by @code{gettext}, if a more specific match were available
 431 it would also have been re-mapped.
 432
 433 @item
 434 This preload has only been tested against @command{eglibc} 2.11.2 and
 435 @command{gettext} 0.18.1.1 on a GNU/Linux system; let me know if it
 436 does (or doesn't) work for you (@pxref{Reports}).
 437 @end itemize
 438
 439 @node Example
 440 @chapter Example @command{help2man} Output
 441
 442 Given a hypothetical program @command{foo} which produces the following output:
 443
 444 @c Default values strong/em to be used in Examples, these are
 445 @c overridden for info, which doesn't have real bold/italic.
 446 @macro exstrong{text}
 447 @strong{\text\}
 448 @end macro
 449 @macro exemph{text}
 450 @emph{\text\}
 451 @end macro
 452
 453 @c No-op version for info:
 454 @ifinfo
 455 @unmacro exstrong
 456 @macro exstrong{text}
 457 \text\
 458 @end macro
 459 @unmacro exemph
 460 @macro exemph{text}
 461 \text\
 462 @end macro
 463 @end ifinfo
 464
 465 @example
 466 @exstrong{$ foo --version}
 467 GNU foo 1.1
 468
 469 Copyright (C) 2011 Free Software Foundation, Inc.
 470 This is free software; see the source for copying conditions.  There is NO
 471 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 472
 473 Written by A. Programmer.
 474 @exstrong{$ foo --help}
 475 GNU `foo' does nothing interesting except serve as an example for
 476 `help2man'.
 477
 478 Usage: foo [OPTION]...
 479
 480 Options:
 481   -a, --option      an option
 482   -b, --another-option[=VALUE]
 483                     another option
 484
 485       --help        display this help and exit
 486       --version     output version information and exit
 487
 488 Examples:
 489   foo               do nothing
 490   foo --option      the same thing, giving `--option'
 491
 492 Report bugs to <bug-gnu-utils@@gnu.org>.
 493 @end example
 494
 495 @command{help2man} will produce @command{nroff} input for a manual
 496 page which will be formatted something like this:
 497
 498 @example
 499 FOO(1)                         User Commands                        FOO(1)
 500
 501
 502 @exstrong{NAME}
 503        foo - manual page for foo 1.1
 504
 505 @exstrong{SYNOPSIS}
 506        foo [OPTION]...
 507
 508 @exstrong{DESCRIPTION}
 509        GNU  `foo'  does nothing interesting except serve as an example for
 510        `help2man'.
 511
 512 @exstrong{OPTIONS}
 513        @exstrong{-a}, @exstrong{--option}
 514               an option
 515
 516        @exstrong{-b}, @exstrong{--another-option}[=@exemph{VALUE}]
 517               another option
 518
 519        @exstrong{--help} display this help and exit
 520
 521        @exstrong{--version}
 522               output version information and exit
 523
 524 @exstrong{EXAMPLES}
 525        foo    do nothing
 526
 527        foo @exstrong{--option}
 528               the same thing, giving `--option'
 529
 530 @exstrong{AUTHOR}
 531        Written by A. Programmer.
 532
 533 @exstrong{REPORTING BUGS}
 534        Report bugs to <bug-gnu-utils@@gnu.org>.
 535
 536 @exstrong{COPYRIGHT}
 537        Copyright @copyright{} 2011 Free Software Foundation, Inc.
 538        This is free software;  see  the  source  for  copying  conditions.
 539        There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
 540        PARTICULAR PURPOSE.
 541
 542 @exstrong{SEE ALSO}
 543        The full documentation for @exstrong{foo} is maintained as a  Texinfo  manual.
 544        If  the  @exstrong{info} and @exstrong{foo} programs are properly installed at your site,
 545        the command
 546
 547               @exstrong{info foo}
 548
 549        should give you access to the complete manual.
 550
 551
 552 foo 1.1                          May 2011                           FOO(1)
 553 @end example
 554
 555 @node Reports
 556 @chapter Reporting Bugs or Suggestions
 557
 558 If you find problems or have suggestions about this program or
 559 manual, please report them to @email{bug-help2man@@gnu.org}.
 560
 561 Note to translators: Translations are handled though the
 562 @uref{http://translationproject.org/, Translation Project} see
 563 @url{http://translationproject.org/html/translators.html} for details.
 564
 565 @node Availability
 566 @chapter Obtaining @command{help2man}
 567
 568 The latest version of this distribution is available online from GNU
 569 mirrors:
 570
 571 @example
 572 @url{http://ftpmirror.gnu.org/help2man/}
 573 @end example
 574
 575 If automatic redirection fails, the list of mirrors is at:
 576
 577 @example
 578 @url{http://www.gnu.org/order/ftp.html}
 579 @end example
 580
 581 Or if need be you can use the main GNU ftp server:
 582 @example
 583 @url{http://ftp.gnu.org/gnu/help2man/}
 584 @end example
 585
 586 @contents
 587 @bye