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, 2015, 2020, 2021 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, 2015, 2020, 2021 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
72 @top @command{help2man}
74 @command{help2man} produces simple manual pages from the @samp{--help}
75 and @samp{--version} output of other commands.
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}.
91 @chapter Overview of @command{help2man}
93 @command{help2man} is a tool for automatically generating simple
94 manual pages from program output.
96 Although manual pages are optional for GNU programs other projects,
97 such as Debian require them (@pxref{Man Pages, , , standards, GNU
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.
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.
108 @node Invoking help2man
109 @chapter How to Run @command{help2man}
111 The format for running the @command{help2man} program is:
114 @command{help2man} [@var{option}]@dots{} @var{executable}
117 @command{help2man} supports the following options:
120 @item -n @var{string}
121 @itemx --name=@var{string}
122 Use @var{string} as the description for the @samp{NAME} paragraph of
125 By default (for want of anything better) this paragraph contains
126 @samp{manual page for @var{program} @var{version}}.
128 This option overrides an include file @samp{[name]} section
129 (@pxref{Including text}).
131 @item -s @var{section}
132 @itemx --section @var{section}
133 Use @var{section} as the section for the man page. The default
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.
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.
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}).
156 @itemx --include=@var{file}
157 Include material from @var{file} (@pxref{Including text}).
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.
165 @itemx --output=@var{file}
166 Send output to @var{file} rather than @code{stdout}.
169 @itemx --info-page=@var{text}
170 Name of Texinfo manual.
174 Suppress inclusion of a @samp{SEE ALSO} paragraph directing the reader
175 to the Texinfo documentation.
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}).
185 Show help or version information.
188 By default @command{help2man} passes the standard @samp{--help} and
189 @samp{--version} options to the executable although alternatives may
193 @item -h @var{option}
194 @itemx --help-option=@var{option}
197 @item -v @var{option}
198 @itemx --version-option=@var{option}
199 Version option string.
201 @item --version-string=@var{string}
204 @item --no-discard-stderr
205 Include stderr when parsing option output.
208 @node --help recommendations
209 @chapter @option{--help} Recommendations
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.
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.
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):
227 Usage: cp [OPTION]... SOURCE DEST
228 or: cp [OPTION]... SOURCE... DIRECTORY
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}.
237 A very brief explanation of what the program does, including default
238 and/or typical behaviour. For example, here is @command{cp}'s:
241 Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
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
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
259 -a, --archive same as -dpR
260 --backup[=CONTROL] make a backup of each ...
261 -b like --backup but ...
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.
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
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
282 @cindex address for 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.
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}.
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.
305 @chapter Including Additional Text in the Output
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.
313 The format for files included with these option is simple:
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/}.
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})
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.
335 The section output order (for those included) is:
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
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.
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.
367 @chapter Using @command{help2man} With @command{make}
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.
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.
377 An example rule for the program @code{prog} could be:
381 prog.1: $(srcdir)/main.c
382 -$(HELP2MAN) --output=$@@ --name='an example program' ./prog
386 The value of @code{HELP2MAN} may be set in @code{configure.in} using
390 AM_MISSING_PROG(HELP2MAN, help2man)
393 for @command{automake}, or something like:
396 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
399 for @command{autoconf} alone.
401 @node Localised man pages
402 @chapter Producing Native Language Manual Pages
404 Manual pages may be produced for any locale supported by both the
405 program and @command{help2man} with the @samp{--locale} (@samp{-L})
409 help2man -L fr_FR@@euro -o cp.fr.1 cp
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.
416 @section Changing the Location of Message Catalogs
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
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}.
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" \
435 TEXTDOMAIN=@var{prog} \
436 help2man -L fr_FR@@euro -i @var{prog}.fr.h2m -o @var{prog}.fr.1 @var{prog}
440 will cause @var{prog} to load the message catalog from @samp{tmp}
441 rather than @samp{/usr/share/locale}.
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.
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}).
457 @chapter Example @command{help2man} Output
459 Given a hypothetical program @command{foo} which produces the following output:
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}
470 @c No-op version for info:
473 @macro exstrong{text}
483 @exstrong{$ foo --version}
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.
490 Written by A. Programmer.
491 @exstrong{$ foo --help}
492 GNU `foo' does nothing interesting except serve as an example for
495 Usage: foo [OPTION]...
498 -a, --option an option
499 -b, --another-option[=VALUE]
502 --help display this help and exit
503 --version output version information and exit
507 foo --option the same thing, giving `--option'
509 Report bugs to <bug-gnu-utils@@gnu.org>.
512 @command{help2man} will produce @command{nroff} input for a manual
513 page which will be formatted something like this:
516 FOO(1) User Commands FOO(1)
520 foo - manual page for foo 1.1
525 @exstrong{DESCRIPTION}
526 GNU `foo' does nothing interesting except serve as an example for
530 @exstrong{-a}, @exstrong{--option}
533 @exstrong{-b}, @exstrong{--another-option}[=@exemph{VALUE}]
536 @exstrong{--help} display this help and exit
539 output version information and exit
544 foo @exstrong{--option}
545 the same thing, giving `--option'
548 Written by A. Programmer.
550 @exstrong{REPORTING BUGS}
551 Report bugs to <bug-gnu-utils@@gnu.org>.
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
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,
566 should give you access to the complete manual.
569 foo 1.1 May 2011 FOO(1)
573 @chapter Reporting Bugs or Suggestions
575 If you find problems or have suggestions about this program or
576 manual, please report them to @email{bug-help2man@@gnu.org}.
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.
583 @chapter Obtaining @command{help2man}
585 The latest version of this distribution is available online from GNU
589 @url{http://ftpmirror.gnu.org/help2man/}
592 If automatic redirection fails, the list of mirrors is at:
595 @url{http://www.gnu.org/order/ftp.html}
598 Or if need be you can use the main GNU ftp server:
600 @url{http://ftp.gnu.org/gnu/help2man/}