1 \input texinfo @c -*-texinfo-*-
2 @setfilename help2man.info
3 @settitle @command{help2man} Reference Manual
6 @dircategory Software development
8 * help2man: (help2man). Automatic manual page generation.
12 This file documents the GNU @command{help2man} command which produces
13 simple manual pages from the @samp{--help} and @samp{--version} output
16 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010, 2011, 2012,
17 2013, 2014 Free Software Foundation, Inc.
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.
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).
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.
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
43 @subtitle A utility for generating simple manual pages
44 @author Brendan O'Dea @email{bod@@debian.org}
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.
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.
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.
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
68 @top @command{help2man}
70 @command{help2man} produces simple manual pages from the @samp{--help}
71 and @samp{--version} output of other commands.
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}.
87 @chapter Overview of @command{help2man}
89 @command{help2man} is a tool for automatically generating simple
90 manual pages from program output.
92 Although manual pages are optional for GNU programs other projects,
93 such as Debian require them (@pxref{Man Pages, , , standards, GNU
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.
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.
104 @node Invoking help2man
105 @chapter How to Run @command{help2man}
107 The format for running the @command{help2man} program is:
110 @command{help2man} [@var{option}]@dots{} @var{executable}
113 @command{help2man} supports the following options:
116 @item -n @var{string}
117 @itemx --name=@var{string}
118 Use @var{string} as the description for the @samp{NAME} paragraph of
121 By default (for want of anything better) this paragraph contains
122 @samp{manual page for @var{program} @var{version}}.
124 This option overrides an include file @samp{[name]} section
125 (@pxref{Including text}).
127 @item -s @var{section}
128 @itemx --section @var{section}
129 Use @var{section} as the section for the man page. The default
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.
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.
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}).
152 @itemx --include=@var{file}
153 Include material from @var{file} (@pxref{Including text}).
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.
161 @itemx --output=@var{file}
162 Send output to @var{file} rather than @code{stdout}.
165 @itemx --info-page=@var{text}
166 Name of Texinfo manual.
170 Suppress inclusion of a @samp{SEE ALSO} paragraph directing the reader
171 to the Texinfo documentation.
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}).
181 Show help or version information.
184 By default @command{help2man} passes the standard @samp{--help} and
185 @samp{--version} options to the executable although alternatives may
189 @item -h @var{option}
190 @itemx --help-option=@var{option}
193 @item -v @var{option}
194 @itemx --version-option=@var{option}
195 Version option string.
197 @item --version-string=@var{string}
200 @item --no-discard-stderr
201 Include stderr when parsing option output.
204 @node --help recommendations
205 @chapter @option{--help} Recommendations
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.
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.
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):
223 Usage: cp [OPTION]... SOURCE DEST
224 or: cp [OPTION]... SOURCE... DIRECTORY
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}.
233 A very brief explanation of what the program does, including default
234 and/or typical behaviour. For example, here is @command{cp}'s:
237 Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
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
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
255 -a, --archive same as -dpR
256 --backup[=CONTROL] make a backup of each ...
257 -b like --backup but ...
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.
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
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
278 @cindex address for 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.
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}.
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.
301 @chapter Including Additional Text in the Output
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.
309 The format for files included with these option is simple:
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/}.
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})
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.
331 The section output order (for those included) is:
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
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.
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.
363 @chapter Using @command{help2man} With @command{make}
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.
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.
373 An example rule for the program @code{prog} could be:
377 prog.1: $(srcdir)/main.c
378 -$(HELP2MAN) --output=$@@ --name='an example program' ./prog
382 The value of @code{HELP2MAN} may be set in @code{configure.in} using
386 AM_MISSING_PROG(HELP2MAN, help2man, $missing_dir)
389 for @command{automake}, or something like:
392 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
395 for @command{autoconf} alone.
397 @node Localised man pages
398 @chapter Producing Native Language Manual Pages
400 Manual pages may be produced for any locale supported by both the
401 program and @command{help2man} with the @samp{--locale} (@samp{-L})
405 help2man -L fr_FR@@euro -o cp.fr.1 cp
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.
412 @section Changing the Location of Message Catalogs
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
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}.
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" \
431 TEXTDOMAIN=@var{prog} \
432 help2man -L fr_FR@@euro -i @var{prog}.fr.h2m -o @var{prog}.fr.1 @var{prog}
436 will cause @var{prog} to load the message catalog from @samp{tmp}
437 rather than @samp{/usr/share/locale}.
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.
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}).
453 @chapter Example @command{help2man} Output
455 Given a hypothetical program @command{foo} which produces the following output:
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}
466 @c No-op version for info:
469 @macro exstrong{text}
479 @exstrong{$ foo --version}
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.
486 Written by A. Programmer.
487 @exstrong{$ foo --help}
488 GNU `foo' does nothing interesting except serve as an example for
491 Usage: foo [OPTION]...
494 -a, --option an option
495 -b, --another-option[=VALUE]
498 --help display this help and exit
499 --version output version information and exit
503 foo --option the same thing, giving `--option'
505 Report bugs to <bug-gnu-utils@@gnu.org>.
508 @command{help2man} will produce @command{nroff} input for a manual
509 page which will be formatted something like this:
512 FOO(1) User Commands FOO(1)
516 foo - manual page for foo 1.1
521 @exstrong{DESCRIPTION}
522 GNU `foo' does nothing interesting except serve as an example for
526 @exstrong{-a}, @exstrong{--option}
529 @exstrong{-b}, @exstrong{--another-option}[=@exemph{VALUE}]
532 @exstrong{--help} display this help and exit
535 output version information and exit
540 foo @exstrong{--option}
541 the same thing, giving `--option'
544 Written by A. Programmer.
546 @exstrong{REPORTING BUGS}
547 Report bugs to <bug-gnu-utils@@gnu.org>.
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
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,
562 should give you access to the complete manual.
565 foo 1.1 May 2011 FOO(1)
569 @chapter Reporting Bugs or Suggestions
571 If you find problems or have suggestions about this program or
572 manual, please report them to @email{bug-help2man@@gnu.org}.
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.
579 @chapter Obtaining @command{help2man}
581 The latest version of this distribution is available online from GNU
585 @url{http://ftpmirror.gnu.org/help2man/}
588 If automatic redirection fails, the list of mirrors is at:
591 @url{http://www.gnu.org/order/ftp.html}
594 Or if need be you can use the main GNU ftp server:
596 @url{http://ftp.gnu.org/gnu/help2man/}