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