1 \input texinfo @c -*-texinfo-*-
2 @setfilename help2man.info
3 @settitle @command{help2man} Reference Manual
6 @documentencoding UTF-8
8 @dircategory Software development
10 * help2man: (help2man). Automatic manual page generation.
14 This file documents the GNU @command{help2man} command which produces
15 simple manual pages from the @samp{--help} and @samp{--version} output
18 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010, 2011, 2012,
19 2013, 2014 Free Software Foundation, Inc.
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.
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).
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.
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
45 @subtitle A utility for generating simple manual pages
46 @author Brendan O'Dea @email{bod@@debian.org}
49 @vskip 0pt plus 1filll
50 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
51 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
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.
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.
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
70 @top @command{help2man}
72 @command{help2man} produces simple manual pages from the @samp{--help}
73 and @samp{--version} output of other commands.
76 * Overview:: Overview of @command{help2man}.
77 * Invoking help2man:: How to run @command{help2man}.
78 * --help recommendations:: Recommended formatting for --help output.
79 * Including text:: Including additional text in the output.
80 * Makefile usage:: Using @command{help2man} with @command{make}.
81 * Localised man pages:: Producing native language manual pages.
82 * Example:: Example @command{help2man} output.
83 * Reports:: Reporting bugs or suggestions.
84 * Availability:: Obtaining @command{help2man}.
89 @chapter Overview of @command{help2man}
91 @command{help2man} is a tool for automatically generating simple
92 manual pages from program output.
94 Although manual pages are optional for GNU programs other projects,
95 such as Debian require them (@pxref{Man Pages, , , standards, GNU
98 This program is intended to provide an easy way for software authors
99 to include a manual page in their distribution without having to
100 maintain that document.
102 Given a program which produces reasonably standard @samp{--help} and
103 @samp{--version} outputs, @command{help2man} can re-arrange that
104 output into something which resembles a manual page.
106 @node Invoking help2man
107 @chapter How to Run @command{help2man}
109 The format for running the @command{help2man} program is:
112 @command{help2man} [@var{option}]@dots{} @var{executable}
115 @command{help2man} supports the following options:
118 @item -n @var{string}
119 @itemx --name=@var{string}
120 Use @var{string} as the description for the @samp{NAME} paragraph of
123 By default (for want of anything better) this paragraph contains
124 @samp{manual page for @var{program} @var{version}}.
126 This option overrides an include file @samp{[name]} section
127 (@pxref{Including text}).
129 @item -s @var{section}
130 @itemx --section @var{section}
131 Use @var{section} as the section for the man page. The default
134 @item -m @var{manual}
135 @itemx --manual=@var{manual}
136 Set the name of the manual section to @var{section}, used as a centred
137 heading for the manual page. By default @samp{User Commands} is used
138 for pages in section 1, @samp{Games} for section 6 and @samp{System
139 Administration Utilities} for sections 8 and 1M.
141 @item -S @var{source}
142 @itemx --source=@var{source}
143 The program source is used as a page footer, and often contains the name
144 of the organisation or a suite of which the program is part. By default
145 the value is the package name and version.
147 @item -L @var{locale}
148 @itemx --locale=@var{locale}
149 Select output locale (default @samp{C}). Both the program and
150 @command{help2man} must support the given @var{locale}
151 (@pxref{Localised man pages}).
154 @itemx --include=@var{file}
155 Include material from @var{file} (@pxref{Including text}).
158 @itemx --opt-include=@var{file}
159 A variant of @samp{--include} for use in Makefile pattern rules which
160 does not require @var{file} to exist.
163 @itemx --output=@var{file}
164 Send output to @var{file} rather than @code{stdout}.
167 @itemx --info-page=@var{text}
168 Name of Texinfo manual.
172 Suppress inclusion of a @samp{SEE ALSO} paragraph directing the reader
173 to the Texinfo documentation.
177 Drop @file{lt-} prefix from instances of the program name in the
178 synopsis (@command{libtool} creates wrapper scripts in the build
179 directory which invoke @command{foo} as @command{.libs/lt-foo}).
183 Show help or version information.
186 By default @command{help2man} passes the standard @samp{--help} and
187 @samp{--version} options to the executable although alternatives may
191 @item -h @var{option}
192 @itemx --help-option=@var{option}
195 @item -v @var{option}
196 @itemx --version-option=@var{option}
197 Version option string.
199 @item --version-string=@var{string}
202 @item --no-discard-stderr
203 Include stderr when parsing option output.
206 @node --help recommendations
207 @chapter @option{--help} Recommendations
209 Here are some recommendations for what to include in your
210 @option{--help} output. Including these gives @command{help2man} the
211 best chance at generating a respectable man page, as well as
212 benefitting users directly.
214 See @ref{Command-Line Interfaces, , , standards, GNU Coding Standards}
215 and @ref{Man Pages, , , standards, GNU Coding Standards}, for the
216 official GNU standards relating to @option{--help} and man pages.
220 A synopsis of how to invoke the program. If different usages of the
221 program have different invocations, then list them all. For example
222 (edited for brevity):
225 Usage: cp [OPTION]... SOURCE DEST
226 or: cp [OPTION]... SOURCE... DIRECTORY
230 Use @code{argv[0]} for the program name in these synopses, just as it
231 is, with no directory stripping. This is in contrast to the canonical
232 (constant) name of the program which is used in @option{--version}.
235 A very brief explanation of what the program does, including default
236 and/or typical behaviour. For example, here is @command{cp}'s:
239 Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
243 A list of options, indented to column 2. If the program supports
244 one-character options, put those first, then the equivalent long option
245 (if any). If the option takes an argument, include that too, giving it
246 a meaningful name. Align the descriptions in a convenient column, if
247 desired. Note that to be correctly recognised by @command{help2man}
248 the description must be separated from the options by at least two
249 spaces and descriptions continued on subsequent lines must start at
252 Here again is an (edited) excerpt from @command{cp}, showing a short
253 option with an equivalent long option, a long option only, and a short
257 -a, --archive same as -dpR
258 --backup[=CONTROL] make a backup of each ...
259 -b like --backup but ...
262 For programs that take many options, it may be desirable to split the
263 option list into sections such as @samp{Global}, @samp{Output control}, or
264 whatever makes sense in the particular case. It is usually best to
265 alphabetise (by short option name first, then long) within each section,
266 or the entire list if there are no sections.
269 Any useful additional information about program behaviour, such as
270 influential environment variables, further explanation of options, etc.
271 For example, @command{cp} discusses @env{VERSION_CONTROL} and sparse
275 A few examples of typical usage, at your discretion. One good example
276 is usually worth a thousand words of description, so this is
280 @cindex address for bug reports
282 In closing, a line stating how to email bug reports. Typically,
283 @var{mailing-address} will be @samp{bug-@var{program}@@gnu.org}; please
284 use this form for GNU programs whenever possible. It's also good to
285 mention the home page of the program, other mailing lists, etc.
289 The @code{argp} and @code{popt} programming interfaces let you specify
290 option descriptions for @option{--help} in the same structure as the
291 rest of the option definition; you may wish to consider using these
292 routines for option parsing instead of @code{getopt}.
294 By default @command{help2man} has some heuristics for identifying
295 manual page sections: a line consisting of @samp{Options:} for example
296 will cause the following text to appear in the @code{OPTIONS} section,
297 and a line beginning with @samp{Copyright} will appear in the
298 @code{COPYRIGHT} section. Outside of these heuristics, a line
299 consisting of @samp{*Words*} will start a new section, and
300 @samp{Words:} a new sub-section.
303 @chapter Including Additional Text in the Output
305 Additional static text may be included in the generated manual page by
306 using the @samp{--include} and @samp{--opt-include} options
307 (@pxref{Invoking help2man}). While these files can be named anything,
308 for consistency we suggest to use the extension @code{.h2m} for
309 @command{help2man} include files.
311 The format for files included with these option is simple:
321 Blocks of verbatim *roff text are inserted into the output either at
322 the start of the given @samp{[section]} (case insensitive), or after a
323 paragraph matching @samp{/pattern/}.
325 Patterns use the Perl regular expression syntax and may be followed by
326 the @samp{i}, @samp{s} or @samp{m} modifiers (@pxref{perlre, ,
327 perlre(1), *manpages*, The @code{perlre(1)} manual page})
329 Lines before the first section or pattern which begin with @samp{-}
330 are processed as options. Anything else is silently ignored and may
331 be used for comments, RCS keywords and the like.
333 The section output order (for those included) is:
350 Any @samp{[name]} or @samp{[synopsis]} sections appearing in the
351 include file will replace what would have automatically been produced
352 (although you can still override the former with @samp{--name} if
355 Other sections are prepended to the automatically produced output for
356 the standard sections given above, or included at @emph{other} (above)
357 in the order they were encountered in the include file.
359 Placement of the text within the section may be explicitly requested
360 by using the syntax @samp{[<section]}, @samp{[=section]} or
361 @samp{[>section]} to place the additional text before, in place of, or
362 after the default output respectively.
365 @chapter Using @command{help2man} With @command{make}
367 A suggested use of @command{help2man} in Makefiles is to have the
368 manual page depend not on the binary, but on the source file(s) in
369 which the @samp{--help} and @samp{--version} output are defined.
371 This usage allows a manual page to be generated by the maintainer and
372 included in the distribution without requiring the end-user to have
373 @command{help2man} installed.
375 An example rule for the program @code{prog} could be:
379 prog.1: $(srcdir)/main.c
380 -$(HELP2MAN) --output=$@@ --name='an example program' ./prog
384 The value of @code{HELP2MAN} may be set in @code{configure.in} using
388 AM_MISSING_PROG(HELP2MAN, help2man, $missing_dir)
391 for @command{automake}, or something like:
394 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
397 for @command{autoconf} alone.
399 @node Localised man pages
400 @chapter Producing Native Language Manual Pages
402 Manual pages may be produced for any locale supported by both the
403 program and @command{help2man} with the @samp{--locale} (@samp{-L})
407 help2man -L fr_FR@@euro -o cp.fr.1 cp
410 See @url{http://translationproject.org/domain/help2man.html} for the
411 languages currently supported by @command{help2man}, and
412 @pxref{Reports} for how to submit other translations.
414 @section Changing the Location of Message Catalogs
416 When creating localised manual pages from a program's build directory it
417 is probable that the translations installed in the standard location
418 will not be (if installed at all) correct for the version of the
421 A preloadable library is provided with @command{help2man} which will
422 intercept @code{bindtextdomain} calls configuring the location of message
423 catalogs for the domain given by @env{$TEXTDOMAIN} and override the
424 location to the path given by @env{$LOCALEDIR}.
429 mkdir -p tmp/fr/LC_MESSAGES
430 cp po/fr.gmo tmp/fr/LC_MESSAGES/@var{prog}.mo
431 LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
433 TEXTDOMAIN=@var{prog} \
434 help2man -L fr_FR@@euro -i @var{prog}.fr.h2m -o @var{prog}.fr.1 @var{prog}
438 will cause @var{prog} to load the message catalog from @samp{tmp}
439 rather than @samp{/usr/share/locale}.
444 The generalisation of @samp{fr_FR@@euro} to @samp{fr} in the example
445 above is done by @code{gettext}, if a more specific match were available
446 it would also have been re-mapped.
449 This preload has only been tested against @command{eglibc} 2.11.2 and
450 @command{gettext} 0.18.1.1 on a GNU/Linux system; let me know if it
451 does (or doesn't) work for you (@pxref{Reports}).
455 @chapter Example @command{help2man} Output
457 Given a hypothetical program @command{foo} which produces the following output:
459 @c Default values strong/em to be used in Examples, these are
460 @c overridden for info, which doesn't have real bold/italic.
461 @macro exstrong{text}
468 @c No-op version for info:
471 @macro exstrong{text}
481 @exstrong{$ foo --version}
484 Copyright (C) 2011 Free Software Foundation, Inc.
485 This is free software; see the source for copying conditions. There is NO
486 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
488 Written by A. Programmer.
489 @exstrong{$ foo --help}
490 GNU `foo' does nothing interesting except serve as an example for
493 Usage: foo [OPTION]...
496 -a, --option an option
497 -b, --another-option[=VALUE]
500 --help display this help and exit
501 --version output version information and exit
505 foo --option the same thing, giving `--option'
507 Report bugs to <bug-gnu-utils@@gnu.org>.
510 @command{help2man} will produce @command{nroff} input for a manual
511 page which will be formatted something like this:
514 FOO(1) User Commands FOO(1)
518 foo - manual page for foo 1.1
523 @exstrong{DESCRIPTION}
524 GNU `foo' does nothing interesting except serve as an example for
528 @exstrong{-a}, @exstrong{--option}
531 @exstrong{-b}, @exstrong{--another-option}[=@exemph{VALUE}]
534 @exstrong{--help} display this help and exit
537 output version information and exit
542 foo @exstrong{--option}
543 the same thing, giving `--option'
546 Written by A. Programmer.
548 @exstrong{REPORTING BUGS}
549 Report bugs to <bug-gnu-utils@@gnu.org>.
552 Copyright @copyright{} 2011 Free Software Foundation, Inc.
553 This is free software; see the source for copying conditions.
554 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
558 The full documentation for @exstrong{foo} is maintained as a Texinfo manual.
559 If the @exstrong{info} and @exstrong{foo} programs are properly installed at your site,
564 should give you access to the complete manual.
567 foo 1.1 May 2011 FOO(1)
571 @chapter Reporting Bugs or Suggestions
573 If you find problems or have suggestions about this program or
574 manual, please report them to @email{bug-help2man@@gnu.org}.
576 Note to translators: Translations are handled though the
577 @uref{http://translationproject.org/, Translation Project} see
578 @url{http://translationproject.org/html/translators.html} for details.
581 @chapter Obtaining @command{help2man}
583 The latest version of this distribution is available online from GNU
587 @url{http://ftpmirror.gnu.org/help2man/}
590 If automatic redirection fails, the list of mirrors is at:
593 @url{http://www.gnu.org/order/ftp.html}
596 Or if need be you can use the main GNU ftp server:
598 @url{http://ftp.gnu.org/gnu/help2man/}