1 This is help2man.info, produced by makeinfo version 4.13 from
4 INFO-DIR-SECTION Software development
6 * help2man: (help2man). Automatic manual page generation.
9 This file documents the GNU `help2man' command which produces simple
10 manual pages from the `--help' and `--version' output of other commands.
12 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
13 2011 Free Software Foundation, Inc.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided that
21 the entire resulting derived work is distributed under the terms of a
22 permission notice identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that this permission notice may be stated in a
27 translation approved by the Foundation.
30 File: help2man.info, Node: Top, Next: Overview, Up: (dir)
35 `help2man' produces simple manual pages from the `--help' and
36 `--version' output of other commands.
40 * Overview:: Overview of `help2man'.
41 * Invoking help2man:: How to run `help2man'.
42 * --help recommendations:: Recommended formatting for --help output.
43 * Including text:: Including additional text in the output.
44 * Makefile usage:: Using `help2man' with `make'.
45 * Localised man pages:: Producing native language manual pages.
46 * Example:: Example `help2man' output.
47 * Reports:: Reporting bugs or suggestions.
48 * Availability:: Obtaining `help2man'.
51 File: help2man.info, Node: Overview, Next: Invoking help2man, Prev: Top, Up: Top
53 1 Overview of `help2man'
54 ************************
56 `help2man' is a tool for automatically generating simple manual pages
59 Although manual pages are optional for GNU programs other projects,
60 such as Debian require them (*note Man Pages: (standards)Man Pages.)
62 This program is intended to provide an easy way for software authors
63 to include a manual page in their distribution without having to
64 maintain that document.
66 Given a program which produces reasonably standard `--help' and
67 `--version' outputs, `help2man' can re-arrange that output into
68 something which resembles a manual page.
71 File: help2man.info, Node: Invoking help2man, Next: --help recommendations, Prev: Overview, Up: Top
73 2 How to Run `help2man'
74 ***********************
76 The format for running the `help2man' program is:
78 `help2man' [OPTION]... EXECUTABLE
80 `help2man' supports the following options:
84 Use STRING as the description for the `NAME' paragraph of the
87 By default (for want of anything better) this paragraph contains
88 `manual page for PROGRAM VERSION'.
90 This option overrides an include file `[name]' section (*note
95 Use SECTION as the section for the man page. The default section
100 Set the name of the manual section to SECTION, used as a centred
101 heading for the manual page. By default `User Commands' is used
102 for pages in section 1, `Games' for section 6 and `System
103 Administration Utilities' for sections 8 and 1M.
107 The program source is used as a page footer, and often contains
108 the name of the organisation or a suite of which the program is
109 part. By default the value is the package name and version.
113 Select output locale (default `C'). Both the program and
114 `help2man' must support the given LOCALE (*note Localised man
119 Include material from FILE (*note Including text::).
123 A variant of `--include' for use in Makefile pattern rules which
124 does not require FILE to exist.
128 Send output to FILE rather than `stdout'.
132 Name of Texinfo manual.
136 Suppress inclusion of a `SEE ALSO' paragraph directing the reader
137 to the Texinfo documentation.
141 Drop `lt-' prefix from instances of the program name in the
142 synopsis (`libtool' creates wrapper scripts in the build directory
143 which invoke `foo' as `.libs/lt-foo').
147 Show help or version information.
149 By default `help2man' passes the standard `--help' and `--version'
150 options to the executable although alternatives may be specified using:
153 `--help-option=OPTION'
157 `--version-option=OPTION'
158 Version option string.
160 `--version-string=STRING'
163 `--no-discard-stderr'
164 Include stderr when parsing option output.
167 File: help2man.info, Node: --help recommendations, Next: Including text, Prev: Invoking help2man, Up: Top
169 3 `--help' Recommendations
170 **************************
172 Here are some recommendations for what to include in your `--help'
173 output. Including these gives `help2man' the best chance at generating
174 a respectable man page, as well as benefitting users directly.
176 *Note Command-Line Interfaces: (standards)Command-Line Interfaces,
177 and *note Man Pages: (standards)Man Pages, for the official GNU
178 standards relating to `--help' and man pages.
180 * A synopsis of how to invoke the program. If different usages of
181 the program have different invocations, then list them all. For
182 example (edited for brevity):
184 Usage: cp [OPTION]... SOURCE DEST
185 or: cp [OPTION]... SOURCE... DIRECTORY
188 Use `argv[0]' for the program name in these synopses, just as it
189 is, with no directory stripping. This is in contrast to the
190 canonical (constant) name of the program which is used in
193 * A very brief explanation of what the program does, including
194 default and/or typical behaviour. For example, here is `cp''s:
196 Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
198 * A list of options, indented to column 2. If the program supports
199 one-character options, put those first, then the equivalent long
200 option (if any). If the option takes an argument, include that
201 too, giving it a meaningful name. Align the descriptions in a
202 convenient column, if desired. Note that to be correctly
203 recognised by `help2man' the description must be separated from
204 the options by at least two spaces and descriptions continued on
205 subsequent lines must start at the same column.
207 Here again is an (edited) excerpt from `cp', showing a short
208 option with an equivalent long option, a long option only, and a
211 -a, --archive same as -dpR
212 --backup[=CONTROL] make a backup of each ...
213 -b like --backup but ...
215 For programs that take many options, it may be desirable to split
216 the option list into sections such as `Global', `Output control',
217 or whatever makes sense in the particular case. It is usually
218 best to alphabetise (by short option name first, then long) within
219 each section, or the entire list if there are no sections.
221 * Any useful additional information about program behaviour, such as
222 influential environment variables, further explanation of options,
223 etc. For example, `cp' discusses `VERSION_CONTROL' and sparse
226 * A few examples of typical usage, at your discretion. One good
227 example is usually worth a thousand words of description, so this
228 is highly recommended.
230 * In closing, a line stating how to email bug reports. Typically,
231 MAILING-ADDRESS will be `bug-PROGRAM@gnu.org'; please use this
232 form for GNU programs whenever possible. It's also good to
233 mention the home page of the program, other mailing lists, etc.
236 The `argp' and `popt' programming interfaces let you specify option
237 descriptions for `--help' in the same structure as the rest of the
238 option definition; you may wish to consider using these routines for
239 option parsing instead of `getopt'.
242 File: help2man.info, Node: Including text, Next: Makefile usage, Prev: --help recommendations, Up: Top
244 4 Including Additional Text in the Output
245 *****************************************
247 Additional static text may be included in the generated manual page by
248 using the `--include' and `--opt-include' options (*note Invoking
249 help2man::). While these files can be named anything, for consistency
250 we suggest to use the extension `.h2m' for help2man include files.
252 The format for files included with these option is simple:
260 Blocks of verbatim *roff text are inserted into the output either at
261 the start of the given `[section]' (case insensitive), or after a
262 paragraph matching `/pattern/'.
264 Patterns use the Perl regular expression syntax and may be followed
265 by the `i', `s' or `m' modifiers (*note perlre(1): (*manpages*)perlre.)
267 Lines before the first section or pattern which begin with `-' are
268 processed as options. Anything else is silently ignored and may be
269 used for comments, RCS keywords and the like.
271 The section output order (for those included) is:
286 Any `[name]' or `[synopsis]' sections appearing in the include file
287 will replace what would have automatically been produced (although you
288 can still override the former with `--name' if required).
290 Other sections are prepended to the automatically produced output for
291 the standard sections given above, or included at _other_ (above) in
292 the order they were encountered in the include file.
295 File: help2man.info, Node: Makefile usage, Next: Localised man pages, Prev: Including text, Up: Top
297 5 Using `help2man' With `make'
298 ******************************
300 A suggested use of `help2man' in Makefiles is to have the manual page
301 depend not on the binary, but on the source file(s) in which the
302 `--help' and `--version' output are defined.
304 This usage allows a manual page to be generated by the maintainer and
305 included in the distribution without requiring the end-user to have
306 `help2man' installed.
308 An example rule for the program `prog' could be:
310 prog.1: $(srcdir)/main.c
311 -$(HELP2MAN) --output=$@ --name='an example program' ./prog
313 The value of `HELP2MAN' may be set in `configure.in' using either of:
315 AM_MISSING_PROG(HELP2MAN, help2man, $missing_dir)
317 for `automake', or something like:
319 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
321 for `autoconf' alone.
324 File: help2man.info, Node: Localised man pages, Next: Example, Prev: Makefile usage, Up: Top
326 6 Producing Native Language Manual Pages
327 ****************************************
329 Manual pages may be produced for any locale supported by both the
330 program and `help2man' with the `--locale' (`-L') option.
332 help2man -L fr_FR@euro -o cp.fr.1 cp
334 See `http://translationproject.org/domain/help2man.html' for the
335 languages currently supported by `help2man', and *note Reports:: for
336 how to submit other translations.
338 6.1 Changing the Location of Message Catalogs
339 =============================================
341 When creating localised manual pages from a program's build directory it
342 is probable that the translations installed in the standard location
343 will not be (if installed at all) correct for the version of the
346 A preloadable library is provided with `help2man' which will
347 intercept `bindtextdomain' calls configuring the location of message
348 catalogs for the domain given by `$TEXTDOMAIN' and override the
349 location to the path given by `$LOCALEDIR'.
353 mkdir -p tmp/fr/LC_MESSAGES
354 cp po/fr.gmo tmp/fr/LC_MESSAGES/PROG.mo
355 LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
358 help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
361 will cause PROG to load the message catalog from `tmp' rather than
365 * The generalisation of `fr_FR@euro' to `fr' in the example above is
366 done by `gettext', if a more specific match were available it
367 would also have been re-mapped.
369 * This preload has only been tested against `eglibc' 2.11.2 and
370 `gettext' 0.18.1.1 on a GNU/Linux system; let me know if it does
371 (or doesn't) work for you (*note Reports::).
374 File: help2man.info, Node: Example, Next: Reports, Prev: Localised man pages, Up: Top
376 7 Example `help2man' Output
377 ***************************
379 Given a hypothetical program `foo' which produces the following output:
384 Copyright (C) 2011 Free Software Foundation, Inc.
385 This is free software; see the source for copying conditions. There is NO
386 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
388 Written by A. Programmer.
390 GNU `foo' does nothing interesting except serve as an example for
393 Usage: foo [OPTION]...
396 -a, --option an option
397 -b, --another-option[=VALUE]
400 --help display this help and exit
401 --version output version information and exit
405 foo --option the same thing, giving `--option'
407 Report bugs to <bug-gnu-utils@gnu.org>.
409 `help2man' will produce `nroff' input for a manual page which will
410 be formatted something like this:
412 FOO(1) User Commands FOO(1)
416 foo - manual page for foo 1.1
422 GNU `foo' does nothing interesting except serve as an example for
429 -b, --another-option[=VALUE]
432 --help display this help and exit
435 output version information and exit
441 the same thing, giving `--option'
444 Written by A. Programmer.
447 Report bugs to <bug-gnu-utils@gnu.org>.
450 Copyright (C) 2011 Free Software Foundation, Inc.
451 This is free software; see the source for copying conditions.
452 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
456 The full documentation for foo is maintained as a Texinfo manual.
457 If the info and foo programs are properly installed at your site,
462 should give you access to the complete manual.
465 foo 1.1 May 2011 FOO(1)
468 File: help2man.info, Node: Reports, Next: Availability, Prev: Example, Up: Top
470 8 Reporting Bugs or Suggestions
471 *******************************
473 If you find problems or have suggestions about this program or manual,
474 please report them to <bug-help2man@gnu.org>.
476 Note to translators: Translations are handled though the Translation
477 Project (http://translationproject.org/) see
478 `http://translationproject.org/html/translators.html' for details.
481 File: help2man.info, Node: Availability, Prev: Reports, Up: Top
483 9 Obtaining `help2man'
484 **********************
486 The latest version of this distribution is available online from GNU
489 `http://ftpmirror.gnu.org/help2man/'
491 If automatic redirection fails, the list of mirrors is at:
493 `http://www.gnu.org/order/ftp.html'
495 Or if need be you can use the main GNU ftp server:
496 `http://ftp.gnu.org/gnu/help2man/'
502 Node: Overview
\7f1900
503 Node: Invoking help2man
\7f2607
504 Node: --help recommendations
\7f5165
505 Node: Including text
\7f8564
506 Node: Makefile usage
\7f10272
507 Node: Localised man pages
\7f11203
508 Node: Example
\7f13039
509 Node: Reports
\7f15644
510 Node: Availability
\7f16098