Pod::Man(3pm)

1Pod::Man(3pm)          Perl Programmers Reference Guide          Pod::Man(3pm)
2
3
4

NAME

6       Pod::Man - Convert POD data to formatted *roff input
7

SYNOPSIS

9           use Pod::Man;
10           my $parser = Pod::Man->new (release => $VERSION, section => 8);
11
12           # Read POD from STDIN and write to STDOUT.
13           $parser->parse_file (\*STDIN);
14
15           # Read POD from file.pod and write to file.1.
16           $parser->parse_from_file ('file.pod', 'file.1');
17

DESCRIPTION

19       Pod::Man is a module to convert documentation in the POD format (the
20       preferred language for documenting Perl) into *roff input using the man
21       macro set.  The resulting *roff code is suitable for display on a
22       terminal using nroff(1), normally via man(1), or printing using
23       troff(1).  It is conventionally invoked using the driver script
24       pod2man, but it can also be used directly.
25
26       As a derived class from Pod::Simple, Pod::Man supports the same methods
27       and interfaces.  See Pod::Simple for all the details.
28
29       new() can take options, in the form of key/value pairs that control the
30       behavior of the parser.  See below for details.
31
32       If no options are given, Pod::Man uses the name of the input file with
33       any trailing ".pod", ".pm", or ".pl" stripped as the man page title, to
34       section 1 unless the file ended in ".pm" in which case it defaults to
35       section 3, to a centered title of "User Contributed Perl
36       Documentation", to a centered footer of the Perl version it is run
37       with, and to a left-hand footer of the modification date of its input
38       (or the current date if given "STDIN" for input).
39
40       Pod::Man assumes that your *roff formatters have a fixed-width font
41       named "CW".  If yours is called something else (like "CR"), use the
42       "fixed" option to specify it.  This generally only matters for troff
43       output for printing.  Similarly, you can set the fonts used for bold,
44       italic, and bold italic fixed-width output.
45
46       Besides the obvious pod conversions, Pod::Man also takes care of
47       formatting func(), func(3), and simple variable references like $foo or
48       @bar so you don't have to use code escapes for them; complex
49       expressions like $fred{'stuff'} will still need to be escaped, though.
50       It also translates dashes that aren't used as hyphens into en dashes,
51       makes long dashes--like this--into proper em dashes, fixes "paired
52       quotes," makes C++ look right, puts a little space between double
53       underscores, makes ALLCAPS a teeny bit smaller in troff, and escapes
54       stuff that *roff treats as special so that you don't have to.
55
56       The recognized options to new() are as follows.  All options take a
57       single argument.
58
59       center
60           Sets the centered page header to use instead of "User Contributed
61           Perl Documentation".
62
63       date
64           Sets the left-hand footer.  By default, the modification date of
65           the input file will be used, or the current date if stat() can't
66           find that file (the case if the input is from "STDIN"), and the
67           date will be formatted as "YYYY-MM-DD".
68
69       fixed
70           The fixed-width font to use for verbatim text and code.  Defaults
71           to "CW".  Some systems may want "CR" instead.  Only matters for
72           troff output.
73
74       fixedbold
75           Bold version of the fixed-width font.  Defaults to "CB".  Only
76           matters for troff output.
77
78       fixeditalic
79           Italic version of the fixed-width font (actually, something of a
80           misnomer, since most fixed-width fonts only have an oblique
81           version, not an italic version).  Defaults to "CI".  Only matters
82           for troff output.
83
84       fixedbolditalic
85           Bold italic (probably actually oblique) version of the fixed-width
86           font.  Pod::Man doesn't assume you have this, and defaults to "CB".
87           Some systems (such as Solaris) have this font available as "CX".
88           Only matters for troff output.
89
90       name
91           Set the name of the manual page.  Without this option, the manual
92           name is set to the uppercased base name of the file being converted
93           unless the manual section is 3, in which case the path is parsed to
94           see if it is a Perl module path.  If it is, a path like
95           ".../lib/Pod/Man.pm" is converted into a name like "Pod::Man".
96           This option, if given, overrides any automatic determination of the
97           name.
98
99       quotes
100           Sets the quote marks used to surround C<> text.  If the value is a
101           single character, it is used as both the left and right quote; if
102           it is two characters, the first character is used as the left quote
103           and the second as the right quoted; and if it is four characters,
104           the first two are used as the left quote and the second two as the
105           right quote.
106
107           This may also be set to the special value "none", in which case no
108           quote marks are added around C<> text (but the font is still
109           changed for troff output).
110
111       release
112           Set the centered footer.  By default, this is the version of Perl
113           you run Pod::Man under.  Note that some system an macro sets assume
114           that the centered footer will be a modification date and will
115           prepend something like "Last modified: "; if this is the case, you
116           may want to set "release" to the last modified date and "date" to
117           the version number.
118
119       section
120           Set the section for the ".TH" macro.  The standard section
121           numbering convention is to use 1 for user commands, 2 for system
122           calls, 3 for functions, 4 for devices, 5 for file formats, 6 for
123           games, 7 for miscellaneous information, and 8 for administrator
124           commands.  There is a lot of variation here, however; some systems
125           (like Solaris) use 4 for file formats, 5 for miscellaneous
126           information, and 7 for devices.  Still others use 1m instead of 8,
127           or some mix of both.  About the only section numbers that are
128           reliably consistent are 1, 2, and 3.
129
130           By default, section 1 will be used unless the file ends in ".pm" in
131           which case section 3 will be selected.
132
133       stderr
134           Send error messages about invalid POD to standard error instead of
135           appending a POD ERRORS section to the generated *roff output.
136
137       utf8
138           By default, Pod::Man produces the most conservative possible *roff
139           output to try to ensure that it will work with as many different
140           *roff implementations as possible.  Many *roff implementations
141           cannot handle non-ASCII characters, so this means all non-ASCII
142           characters are converted either to a *roff escape sequence that
143           tries to create a properly accented character (at least for troff
144           output) or to "X".
145
146           If this option is set, Pod::Man will instead output UTF-8.  If your
147           *roff implementation can handle it, this is the best output format
148           to use and avoids corruption of documents containing non-ASCII
149           characters.  However, be warned that *roff source with literal
150           UTF-8 characters is not supported by many implementations and may
151           even result in segfaults and other bad behavior.
152
153           Be aware that, when using this option, the input encoding of your
154           POD source must be properly declared unless it is US-ASCII or
155           Latin-1.  POD input without an "=encoding" command will be assumed
156           to be in Latin-1, and if it's actually in UTF-8, the output will be
157           double-encoded.  See perlpod(1) for more information on the
158           "=encoding" command.
159
160       The standard Pod::Simple method parse_file() takes one argument naming
161       the POD file to read from.  By default, the output is sent to "STDOUT",
162       but this can be changed with the output_fd() method.
163
164       The standard Pod::Simple method parse_from_file() takes up to two
165       arguments, the first being the input file to read POD from and the
166       second being the file to write the formatted output to.
167
168       You can also call parse_lines() to parse an array of lines or
169       parse_string_document() to parse a document already in memory.  To put
170       the output into a string instead of a file handle, call the
171       output_string() method.  See Pod::Simple for the specific details.
172

DIAGNOSTICS

174       roff font should be 1 or 2 chars, not "%s"
175           (F) You specified a *roff font (using "fixed", "fixedbold", etc.)
176           that wasn't either one or two characters.  Pod::Man doesn't support
177           *roff fonts longer than two characters, although some *roff
178           extensions do (the canonical versions of nroff and troff don't
179           either).
180
181       Invalid quote specification "%s"
182           (F) The quote specification given (the quotes option to the
183           constructor) was invalid.  A quote specification must be one, two,
184           or four characters long.
185

BUGS

187       Encoding handling assumes that PerlIO is available and does not work
188       properly if it isn't.  The "utf8" option is therefore not supported
189       unless Perl is built with PerlIO support.
190
191       There is currently no way to turn off the guesswork that tries to
192       format unmarked text appropriately, and sometimes it isn't wanted
193       (particularly when using POD to document something other than Perl).
194       Most of the work toward fixing this has now been done, however, and all
195       that's still needed is a user interface.
196
197       The NAME section should be recognized specially and index entries
198       emitted for everything in that section.  This would have to be deferred
199       until the next section, since extraneous things in NAME tends to
200       confuse various man page processors.  Currently, no index entries are
201       emitted for anything in NAME.
202
203       Pod::Man doesn't handle font names longer than two characters.  Neither
204       do most troff implementations, but GNU troff does as an extension.  It
205       would be nice to support as an option for those who want to use it.
206
207       The preamble added to each output file is rather verbose, and most of
208       it is only necessary in the presence of non-ASCII characters.  It would
209       ideally be nice if all of those definitions were only output if needed,
210       perhaps on the fly as the characters are used.
211
212       Pod::Man is excessively slow.
213

CAVEATS

215       If Pod::Man is given the "utf8" option, the encoding of its output file
216       handle will be forced to UTF-8 if possible, overriding any existing
217       encoding.  This will be done even if the file handle is not created by
218       Pod::Man and was passed in from outside.  This maintains consistency
219       regardless of PERL_UNICODE and other settings.
220
221       The handling of hyphens and em dashes is somewhat fragile, and one may
222       get the wrong one under some circumstances.  This should only matter
223       for troff output.
224
225       When and whether to use small caps is somewhat tricky, and Pod::Man
226       doesn't necessarily get it right.
227
228       Converting neutral double quotes to properly matched double quotes
229       doesn't work unless there are no formatting codes between the quote
230       marks.  This only matters for troff output.
231

AUTHOR

233       Russ Allbery <rra@stanford.edu>, based very heavily on the original
234       pod2man by Tom Christiansen <tchrist@mox.perl.com>.  The modifications
235       to work with Pod::Simple instead of Pod::Parser were originally
236       contributed by Sean Burke (but I've since hacked them beyond
237       recognition and all bugs are mine).
238

COPYRIGHT AND LICENSE

240       Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
241       2009 Russ Allbery <rra@stanford.edu>.
242
243       This program is free software; you may redistribute it and/or modify it
244       under the same terms as Perl itself.
245