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