3 eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
4 if 0; # not running under some shell
5 eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
6 if $running_under_some_shell;
8 # pod2man -- Convert POD data to formatted *roff input.
10 # Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery <rra@stanford.edu>
12 # This program is free software; you may redistribute it and/or modify it
13 # under the same terms as Perl itself.
17 use Getopt::Long qw(GetOptions);
19 use Pod::Usage qw(pod2usage);
23 # Silence -w warnings.
24 use vars qw($running_under_some_shell);
26 # Insert -- into @ARGV before any single dash argument to hide it from
27 # Getopt::Long; we want to interpret it as meaning stdin.
29 @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
31 # Parse our options, trying to retain backward compatibility with pod2man but
32 # allowing short forms as well. --lax is currently ignored.
34 $options{errors} = 'pod';
35 Getopt::Long::config ('bundling_override');
36 GetOptions (\%options, 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s',
37 'fixeditalic=s', 'fixedbolditalic=s', 'help|h', 'lax|l',
38 'name|n=s', 'official|o', 'quotes|q=s', 'release|r:s',
39 'section|s=s', 'stderr', 'verbose|v', 'utf8|u') or exit 1;
40 pod2usage (0) if $options{help};
42 # Official sets --center, but don't override things explicitly set.
43 if ($options{official} && !defined $options{center}) {
44 $options{center} = 'Perl Programmers Reference Guide';
47 # Verbose is only our flag, not a Pod::Man flag.
48 my $verbose = $options{verbose};
49 delete $options{verbose};
51 # This isn't a valid Pod::Man option and is only accepted for backward
55 # Initialize and run the formatter, pulling a pair of input and output off at
57 my $parser = Pod::Man->new (%options);
60 @files = splice (@ARGV, 0, 2);
61 print " $files[1]\n" if $verbose;
62 $parser->parse_from_file (@files);
69 pod2man - Convert POD data to formatted *roff input
72 en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris
73 URL troff troff-specific formatters uppercased Christiansen
77 pod2man [B<--center>=I<string>] [B<--date>=I<string>]
78 [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
79 [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--official>]
80 [B<--quotes>=I<quotes>] [B<--release>[=I<version>]]
81 [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>]
82 [I<input> [I<output>] ...]
88 B<pod2man> is a front-end for Pod::Man, using it to generate *roff input
89 from POD source. The resulting *roff code is suitable for display on a
90 terminal using nroff(1), normally via man(1), or printing using troff(1).
92 I<input> is the file to read for POD source (the POD can be embedded in
93 code). If I<input> isn't given, it defaults to C<STDIN>. I<output>, if
94 given, is the file to which to write the formatted output. If I<output>
95 isn't given, the formatted output is written to C<STDOUT>. Several POD
96 files can be processed in the same B<pod2man> invocation (saving module
97 load and compile times) by providing multiple pairs of I<input> and
98 I<output> files on the command line.
100 B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can
101 be used to set the headers and footers to use; if not given, Pod::Man will
102 assume various defaults. See below or L<Pod::Man> for details.
104 B<pod2man> assumes that your *roff formatters have a fixed-width font
105 named C<CW>. If yours is called something else (like C<CR>), use
106 B<--fixed> to specify it. This generally only matters for troff output
107 for printing. Similarly, you can set the fonts used for bold, italic, and
108 bold italic fixed-width output.
110 Besides the obvious pod conversions, Pod::Man, and therefore pod2man also
111 takes care of formatting func(), func(n), and simple variable references
112 like $foo or @bar so you don't have to use code escapes for them; complex
113 expressions like C<$fred{'stuff'}> will still need to be escaped, though.
114 It also translates dashes that aren't used as hyphens into en dashes, makes
115 long dashes--like this--into proper em dashes, fixes "paired quotes," and
116 takes care of several other troff-specific tweaks. See L<Pod::Man> for
117 complete information.
123 =item B<-c> I<string>, B<--center>=I<string>
125 Sets the centered page header to I<string>. The default is "User
126 Contributed Perl Documentation", but also see B<--official> below.
128 =item B<-d> I<string>, B<--date>=I<string>
130 Set the left-hand footer string to this value. By default, the modification
131 date of the input file will be used, or the current date if input comes from
134 =item B<--fixed>=I<font>
136 The fixed-width font to use for verbatim text and code. Defaults to
137 C<CW>. Some systems may want C<CR> instead. Only matters for troff(1)
140 =item B<--fixedbold>=I<font>
142 Bold version of the fixed-width font. Defaults to C<CB>. Only matters
145 =item B<--fixeditalic>=I<font>
147 Italic version of the fixed-width font (actually, something of a misnomer,
148 since most fixed-width fonts only have an oblique version, not an italic
149 version). Defaults to C<CI>. Only matters for troff(1) output.
151 =item B<--fixedbolditalic>=I<font>
153 Bold italic (probably actually oblique) version of the fixed-width font.
154 Pod::Man doesn't assume you have this, and defaults to C<CB>. Some
155 systems (such as Solaris) have this font available as C<CX>. Only matters
158 =item B<-h>, B<--help>
160 Print out usage information.
162 =item B<-l>, B<--lax>
164 No longer used. B<pod2man> used to check its input for validity as a
165 manual page, but this should now be done by L<podchecker(1)> instead.
166 Accepted for backward compatibility; this option no longer does anything.
168 =item B<-n> I<name>, B<--name>=I<name>
170 Set the name of the manual page to I<name>. Without this option, the manual
171 name is set to the uppercased base name of the file being converted unless
172 the manual section is 3, in which case the path is parsed to see if it is a
173 Perl module path. If it is, a path like C<.../lib/Pod/Man.pm> is converted
174 into a name like C<Pod::Man>. This option, if given, overrides any
175 automatic determination of the name.
177 Note that this option is probably not useful when converting multiple POD
178 files at once. The convention for Unix man pages for commands is for the
179 man page title to be in all-uppercase even if the command isn't.
181 =item B<-o>, B<--official>
183 Set the default header to indicate that this page is part of the standard
184 Perl release, if B<--center> is not also given.
186 =item B<-q> I<quotes>, B<--quotes>=I<quotes>
188 Sets the quote marks used to surround CE<lt>> text to I<quotes>. If
189 I<quotes> is a single character, it is used as both the left and right
190 quote; if I<quotes> is two characters, the first character is used as the
191 left quote and the second as the right quoted; and if I<quotes> is four
192 characters, the first two are used as the left quote and the second two as
195 I<quotes> may also be set to the special value C<none>, in which case no
196 quote marks are added around CE<lt>> text (but the font is still changed for
199 =item B<-r>, B<--release>
201 Set the centered footer. By default, this is the version of Perl you run
202 B<pod2man> under. Note that some system an macro sets assume that the
203 centered footer will be a modification date and will prepend something like
204 "Last modified: "; if this is the case, you may want to set B<--release> to
205 the last modified date and B<--date> to the version number.
207 =item B<-s>, B<--section>
209 Set the section for the C<.TH> macro. The standard section numbering
210 convention is to use 1 for user commands, 2 for system calls, 3 for
211 functions, 4 for devices, 5 for file formats, 6 for games, 7 for
212 miscellaneous information, and 8 for administrator commands. There is a lot
213 of variation here, however; some systems (like Solaris) use 4 for file
214 formats, 5 for miscellaneous information, and 7 for devices. Still others
215 use 1m instead of 8, or some mix of both. About the only section numbers
216 that are reliably consistent are 1, 2, and 3.
218 By default, section 1 will be used unless the file ends in C<.pm>, in
219 which case section 3 will be selected.
223 By default, B<pod2man> puts any errors detected in the POD input in a POD
224 ERRORS section in the output manual page. If B<--stderr> is given, errors
225 are sent to standard error instead and the POD ERRORS section is
228 =item B<-u>, B<--utf8>
230 By default, B<pod2man> produces the most conservative possible *roff
231 output to try to ensure that it will work with as many different *roff
232 implementations as possible. Many *roff implementations cannot handle
233 non-ASCII characters, so this means all non-ASCII characters are converted
234 either to a *roff escape sequence that tries to create a properly accented
235 character (at least for troff output) or to C<X>.
237 This option says to instead output literal UTF-8 characters. If your
238 *roff implementation can handle it, this is the best output format to use
239 and avoids corruption of documents containing non-ASCII characters.
240 However, be warned that *roff source with literal UTF-8 characters is not
241 supported by many implementations and may even result in segfaults and
244 Be aware that, when using this option, the input encoding of your POD
245 source must be properly declared unless it is US-ASCII or Latin-1. POD
246 input without an C<=encoding> command will be assumed to be in Latin-1,
247 and if it's actually in UTF-8, the output will be double-encoded. See
248 L<perlpod(1)> for more information on the C<=encoding> command.
250 =item B<-v>, B<--verbose>
252 Print out the name of each output file as it is being generated.
258 If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for
259 information about what those errors might mean.
263 pod2man program > program.1
264 pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
265 pod2man --section=7 note.pod > note.7
267 If you would like to print out a lot of man page continuously, you probably
268 want to set the C and D registers to set contiguous page numbering and
269 even/odd paging, at least on some versions of man(7).
271 troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
273 To get index entries on C<STDERR>, turn on the F register, as in:
275 troff -man -rF1 perl.1
277 The indexing merely outputs messages via C<.tm> for each major page,
278 section, subsection, item, and any C<XE<lt>E<gt>> directives. See
279 L<Pod::Man> for more details.
283 Lots of this documentation is duplicated from L<Pod::Man>.
287 For those not sure of the proper layout of a man page, here are some notes
288 on writing a proper man page.
290 The name of the program being documented is conventionally written in bold
291 (using BE<lt>E<gt>) wherever it occurs, as are all program options.
292 Arguments should be written in italics (IE<lt>E<gt>). Functions are
293 traditionally written in italics; if you write a function as function(),
294 Pod::Man will take care of this for you. Literal code or commands should
295 be in CE<lt>E<gt>. References to other man pages should be in the form
296 C<manpage(section)>, and Pod::Man will automatically format those
297 appropriately. As an exception, it's traditional not to use this form when
298 referring to module documentation; use C<LE<lt>Module::NameE<gt>> instead.
300 References to other programs or functions are normally in the form of man
301 page references so that cross-referencing tools can provide the user with
302 links and the like. It's possible to overdo this, though, so be careful not
303 to clutter your documentation with too much markup.
305 The major headers should be set out using a C<=head1> directive, and are
306 historically written in the rather startling ALL UPPER CASE format, although
307 this is not mandatory. Minor headers may be included using C<=head2>, and
308 are typically in mixed case.
310 The standard sections of a manual page are:
316 Mandatory section; should be a comma-separated list of programs or functions
317 documented by this POD page, such as:
319 foo, bar - programs to do something
321 Manual page indexers are often extremely picky about the format of this
322 section, so don't put anything in it except this line. A single dash, and
323 only a single dash, should separate the list of programs or functions from
324 the description. Functions should not be qualified with C<()> or the like.
325 The description should ideally fit on a single line, even if a man program
326 replaces the dash with a few tabs.
330 A short usage summary for programs and functions. This section is mandatory
335 Extended description and discussion of the program or functions, or the body
336 of the documentation for man pages that document something else. If
337 particularly long, it's a good idea to break this up into subsections
338 C<=head2> directives like:
342 =head2 Advanced Features
344 =head2 Writing Configuration Files
346 or whatever is appropriate for your documentation.
350 Detailed description of each of the command-line options taken by the
351 program. This should be separate from the description for the use of things
352 like L<Pod::Usage|Pod::Usage>. This is normally presented as a list, with
353 each option as a separate C<=item>. The specific option string should be
354 enclosed in BE<lt>E<gt>. Any values that the option takes should be
355 enclosed in IE<lt>E<gt>. For example, the section for the option
356 B<--section>=I<manext> would be introduced with:
358 =item B<--section>=I<manext>
360 Synonymous options (like both the short and long forms) are separated by a
361 comma and a space on the same C<=item> line, or optionally listed as their
362 own item with a reference to the canonical name. For example, since
363 B<--section> can also be written as B<-s>, the above would be:
365 =item B<-s> I<manext>, B<--section>=I<manext>
367 (Writing the short option first is arguably easier to read, since the long
368 option is long enough to draw the eye to it anyway and the short option can
369 otherwise get lost in visual noise.)
373 What the program or function returns, if successful. This section can be
374 omitted for programs whose precise exit codes aren't important, provided
375 they return 0 on success as is standard. It should always be present for
380 Exceptions, error return codes, exit statuses, and errno settings.
381 Typically used for function documentation; program documentation uses
382 DIAGNOSTICS instead. The general rule of thumb is that errors printed to
383 C<STDOUT> or C<STDERR> and intended for the end user are documented in
384 DIAGNOSTICS while errors passed internal to the calling program and
385 intended for other programmers are documented in ERRORS. When documenting
386 a function that sets errno, a full list of the possible errno values
387 should be given here.
391 All possible messages the program can print out--and what they mean. You
392 may wish to follow the same documentation style as the Perl documentation;
393 see perldiag(1) for more details (and look at the POD source as well).
395 If applicable, please include details on what the user should do to correct
396 the error; documenting an error as indicating "the input buffer is too
397 small" without telling the user how to increase the size of the input buffer
398 (or at least telling them that it isn't possible) aren't very useful.
402 Give some example uses of the program or function. Don't skimp; users often
403 find this the most useful part of the documentation. The examples are
404 generally given as verbatim paragraphs.
406 Don't just present an example without explaining what it does. Adding a
407 short paragraph saying what the example will do can increase the value of
408 the example immensely.
412 Environment variables that the program cares about, normally presented as a
413 list using C<=over>, C<=item>, and C<=back>. For example:
419 Used to determine the user's home directory. F<.foorc> in this
420 directory is read for configuration details, if it exists.
424 Since environment variables are normally in all uppercase, no additional
425 special formatting is generally needed; they're glaring enough as it is.
429 All files used by the program or function, normally presented as a list, and
430 what it uses them for. File names should be enclosed in FE<lt>E<gt>. It's
431 particularly important to document files that will be potentially modified.
435 Things to take special care with, sometimes called WARNINGS.
439 Things that are broken or just don't work quite right.
443 Bugs you don't plan to fix. :-)
447 Miscellaneous commentary.
451 Who wrote it (use AUTHORS for multiple people). Including your current
452 e-mail address (or some e-mail address to which bug reports should be sent)
453 so that users have a way of contacting you is a good idea. Remember that
454 program documentation tends to roam the wild for far longer than you expect
455 and pick an e-mail address that's likely to last if possible.
459 Programs derived from other sources sometimes have this, or you might keep
460 a modification log here. If the log gets overly long or detailed,
461 consider maintaining it in a separate file, though.
463 =item COPYRIGHT AND LICENSE
467 Copyright YEAR(s) by YOUR NAME(s)
469 (No, (C) is not needed. No, "all rights reserved" is not needed.)
471 For licensing the easiest way is to use the same licensing as Perl itself:
473 This library is free software; you may redistribute it and/or modify
474 it under the same terms as Perl itself.
476 This makes it easy for people to use your module with Perl. Note that
477 this licensing is neither an endorsement or a requirement, you are of
478 course free to choose any licensing.
482 Other man pages to check out, like man(1), man(7), makewhatis(8), or
483 catman(8). Normally a simple list of man pages separated by commas, or a
484 paragraph giving the name of a reference work. Man page references, if they
485 use the standard C<name(section)> form, don't have to be enclosed in
486 LE<lt>E<gt> (although it's recommended), but other things in this section
487 probably should be when appropriate.
489 If the package has a mailing list, include a URL or subscription
492 If the package has a web site, include a URL here.
496 In addition, some systems use CONFORMING TO to note conformance to relevant
497 standards and MT-LEVEL to note safeness for use in threaded programs or
498 signal handlers. These headings are primarily useful when documenting parts
499 of a C library. Documentation of object-oriented libraries or modules may
500 use CONSTRUCTORS and METHODS sections for detailed documentation of the
501 parts of the library and save the DESCRIPTION section for an overview; other
502 large modules may use FUNCTIONS for similar reasons. Some people use
503 OVERVIEW to summarize the description if it's quite long.
505 Section ordering varies, although NAME should I<always> be the first section
506 (you'll break some man page systems otherwise), and NAME, SYNOPSIS,
507 DESCRIPTION, and OPTIONS generally always occur first and in that order if
508 present. In general, SEE ALSO, AUTHOR, and similar material should be left
509 for last. Some systems also move WARNINGS and NOTES to last. The order
510 given above should be reasonable for most purposes.
512 Finally, as a general note, try not to use an excessive amount of markup.
513 As documented here and in L<Pod::Man>, you can safely leave Perl variables,
514 function names, man page references, and the like unadorned by markup and
515 the POD translators will figure it out for you. This makes it much easier
516 to later edit the documentation. Note that many existing translators
517 (including this one currently) will do the wrong thing with e-mail addresses
518 when wrapped in LE<lt>E<gt>, so don't do that.
520 For additional information that may be more accurate for your specific
521 system, see either L<man(5)> or L<man(7)> depending on your system manual
522 section numbering conventions.
526 L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<perlpod(1)>,
527 L<podchecker(1)>, L<troff(1)>, L<man(7)>
529 The man page documenting the an macro set may be L<man(5)> instead of
530 L<man(7)> on your system.
532 The current version of this script is always available from its web site at
533 L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
534 Perl core distribution as of 5.6.0.
538 Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original
539 B<pod2man> by Larry Wall and Tom Christiansen. Large portions of this
540 documentation, particularly the sections on the anatomy of a proper man
541 page, are taken from the B<pod2man> documentation by Tom.
543 =head1 COPYRIGHT AND LICENSE
545 Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery
548 This program is free software; you may redistribute it and/or modify it
549 under the same terms as Perl itself.