1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Pod::Man 3"
132 .TH Pod::Man 3 "2009-01-18" "perl v5.8.7" "User Contributed Perl Documentation"
134 Pod::Man \- Convert POD data to formatted *roff input
136 .IX Header "SYNOPSIS"
139 \& my $parser = Pod::Man\->new (release => $VERSION, section => 8);
143 \& # Read POD from STDIN and write to STDOUT.
144 \& $parser\->parse_file (\e*STDIN);
148 \& # Read POD from file.pod and write to file.1.
149 \& $parser\->parse_from_file ('file.pod', 'file.1');
152 .IX Header "DESCRIPTION"
153 Pod::Man is a module to convert documentation in the \s-1POD\s0 format (the
154 preferred language for documenting Perl) into *roff input using the man
155 macro set. The resulting *roff code is suitable for display on a terminal
156 using \fInroff\fR\|(1), normally via \fIman\fR\|(1), or printing using \fItroff\fR\|(1).
157 It is conventionally invoked using the driver script \fBpod2man\fR, but it can
158 also be used directly.
160 As a derived class from Pod::Simple, Pod::Man supports the same methods and
161 interfaces. See Pod::Simple for all the details.
163 \&\fInew()\fR can take options, in the form of key/value pairs that control the
164 behavior of the parser. See below for details.
166 If no options are given, Pod::Man uses the name of the input file with any
167 trailing \f(CW\*(C`.pod\*(C'\fR, \f(CW\*(C`.pm\*(C'\fR, or \f(CW\*(C`.pl\*(C'\fR stripped as the man page title, to
168 section 1 unless the file ended in \f(CW\*(C`.pm\*(C'\fR in which case it defaults to
169 section 3, to a centered title of \*(L"User Contributed Perl Documentation\*(R", to
170 a centered footer of the Perl version it is run with, and to a left-hand
171 footer of the modification date of its input (or the current date if given
172 \&\f(CW\*(C`STDIN\*(C'\fR for input).
174 Pod::Man assumes that your *roff formatters have a fixed-width font named
175 \&\f(CW\*(C`CW\*(C'\fR. If yours is called something else (like \f(CW\*(C`CR\*(C'\fR), use the \f(CW\*(C`fixed\*(C'\fR
176 option to specify it. This generally only matters for troff output for
177 printing. Similarly, you can set the fonts used for bold, italic, and
178 bold italic fixed-width output.
180 Besides the obvious pod conversions, Pod::Man also takes care of
181 formatting \fIfunc()\fR, \fIfunc\fR\|(3), and simple variable references like \f(CW$foo\fR or
182 \&\f(CW@bar\fR so you don't have to use code escapes for them; complex expressions
183 like \f(CW$fred{'stuff'}\fR will still need to be escaped, though. It also
184 translates dashes that aren't used as hyphens into en dashes, makes long
185 dashes\*(--like this\*(--into proper em dashes, fixes \*(L"paired quotes,\*(R" makes \*(C+
186 look right, puts a little space between double underscores, makes \s-1ALLCAPS\s0
187 a teeny bit smaller in \fBtroff\fR, and escapes stuff that *roff treats as
188 special so that you don't have to.
190 The recognized options to \fInew()\fR are as follows. All options take a single
194 Sets the centered page header to use instead of \*(L"User Contributed Perl
198 Sets the left-hand footer. By default, the modification date of the input
199 file will be used, or the current date if \fIstat()\fR can't find that file (the
200 case if the input is from \f(CW\*(C`STDIN\*(C'\fR), and the date will be formatted as
201 \&\f(CW\*(C`YYYY\-MM\-DD\*(C'\fR.
204 The fixed-width font to use for verbatim text and code. Defaults to
205 \&\f(CW\*(C`CW\*(C'\fR. Some systems may want \f(CW\*(C`CR\*(C'\fR instead. Only matters for \fBtroff\fR
209 Bold version of the fixed-width font. Defaults to \f(CW\*(C`CB\*(C'\fR. Only matters
210 for \fBtroff\fR output.
212 .IX Item "fixeditalic"
213 Italic version of the fixed-width font (actually, something of a misnomer,
214 since most fixed-width fonts only have an oblique version, not an italic
215 version). Defaults to \f(CW\*(C`CI\*(C'\fR. Only matters for \fBtroff\fR output.
216 .IP "fixedbolditalic" 4
217 .IX Item "fixedbolditalic"
218 Bold italic (probably actually oblique) version of the fixed-width font.
219 Pod::Man doesn't assume you have this, and defaults to \f(CW\*(C`CB\*(C'\fR. Some
220 systems (such as Solaris) have this font available as \f(CW\*(C`CX\*(C'\fR. Only matters
221 for \fBtroff\fR output.
224 Set the name of the manual page. Without this option, the manual name is
225 set to the uppercased base name of the file being converted unless the
226 manual section is 3, in which case the path is parsed to see if it is a Perl
227 module path. If it is, a path like \f(CW\*(C`.../lib/Pod/Man.pm\*(C'\fR is converted into
228 a name like \f(CW\*(C`Pod::Man\*(C'\fR. This option, if given, overrides any automatic
229 determination of the name.
232 Sets the quote marks used to surround C<> text. If the value is a
233 single character, it is used as both the left and right quote; if it is two
234 characters, the first character is used as the left quote and the second as
235 the right quoted; and if it is four characters, the first two are used as
236 the left quote and the second two as the right quote.
238 This may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote
239 marks are added around C<> text (but the font is still changed for troff
243 Set the centered footer. By default, this is the version of Perl you run
244 Pod::Man under. Note that some system an macro sets assume that the
245 centered footer will be a modification date and will prepend something like
246 \&\*(L"Last modified: \*(R"; if this is the case, you may want to set \f(CW\*(C`release\*(C'\fR to
247 the last modified date and \f(CW\*(C`date\*(C'\fR to the version number.
250 Set the section for the \f(CW\*(C`.TH\*(C'\fR macro. The standard section numbering
251 convention is to use 1 for user commands, 2 for system calls, 3 for
252 functions, 4 for devices, 5 for file formats, 6 for games, 7 for
253 miscellaneous information, and 8 for administrator commands. There is a lot
254 of variation here, however; some systems (like Solaris) use 4 for file
255 formats, 5 for miscellaneous information, and 7 for devices. Still others
256 use 1m instead of 8, or some mix of both. About the only section numbers
257 that are reliably consistent are 1, 2, and 3.
259 By default, section 1 will be used unless the file ends in \f(CW\*(C`.pm\*(C'\fR in which
260 case section 3 will be selected.
263 Send error messages about invalid \s-1POD\s0 to standard error instead of
264 appending a \s-1POD\s0 \s-1ERRORS\s0 section to the generated *roff output.
267 By default, Pod::Man produces the most conservative possible *roff output
268 to try to ensure that it will work with as many different *roff
269 implementations as possible. Many *roff implementations cannot handle
270 non-ASCII characters, so this means all non-ASCII characters are converted
271 either to a *roff escape sequence that tries to create a properly accented
272 character (at least for troff output) or to \f(CW\*(C`X\*(C'\fR.
274 If this option is set, Pod::Man will instead output \s-1UTF\-8\s0. If your *roff
275 implementation can handle it, this is the best output format to use and
276 avoids corruption of documents containing non-ASCII characters. However,
277 be warned that *roff source with literal \s-1UTF\-8\s0 characters is not supported
278 by many implementations and may even result in segfaults and other bad
281 Be aware that, when using this option, the input encoding of your \s-1POD\s0
282 source must be properly declared unless it is US-ASCII or Latin\-1. \s-1POD\s0
283 input without an \f(CW\*(C`=encoding\*(C'\fR command will be assumed to be in Latin\-1,
284 and if it's actually in \s-1UTF\-8\s0, the output will be double\-encoded. See
285 \&\fIperlpod\fR\|(1) for more information on the \f(CW\*(C`=encoding\*(C'\fR command.
287 The standard Pod::Simple method \fIparse_file()\fR takes one argument naming the
288 \&\s-1POD\s0 file to read from. By default, the output is sent to \f(CW\*(C`STDOUT\*(C'\fR, but
289 this can be changed with the \fIoutput_fd()\fR method.
291 The standard Pod::Simple method \fIparse_from_file()\fR takes up to two
292 arguments, the first being the input file to read \s-1POD\s0 from and the second
293 being the file to write the formatted output to.
295 You can also call \fIparse_lines()\fR to parse an array of lines or
296 \&\fIparse_string_document()\fR to parse a document already in memory. To put the
297 output into a string instead of a file handle, call the \fIoutput_string()\fR
298 method. See Pod::Simple for the specific details.
300 .IX Header "DIAGNOSTICS"
301 .ie n .IP "roff font should be 1 or 2 chars, not ""%s""" 4
302 .el .IP "roff font should be 1 or 2 chars, not ``%s''" 4
303 .IX Item "roff font should be 1 or 2 chars, not %s"
304 (F) You specified a *roff font (using \f(CW\*(C`fixed\*(C'\fR, \f(CW\*(C`fixedbold\*(C'\fR, etc.) that
305 wasn't either one or two characters. Pod::Man doesn't support *roff fonts
306 longer than two characters, although some *roff extensions do (the canonical
307 versions of \fBnroff\fR and \fBtroff\fR don't either).
308 .ie n .IP "Invalid quote specification ""%s""" 4
309 .el .IP "Invalid quote specification ``%s''" 4
310 .IX Item "Invalid quote specification %s"
311 (F) The quote specification given (the quotes option to the constructor) was
312 invalid. A quote specification must be one, two, or four characters long.
315 Encoding handling assumes that PerlIO is available and does not work
316 properly if it isn't. The \f(CW\*(C`utf8\*(C'\fR option is therefore not supported
317 unless Perl is built with PerlIO support.
319 There is currently no way to turn off the guesswork that tries to format
320 unmarked text appropriately, and sometimes it isn't wanted (particularly
321 when using \s-1POD\s0 to document something other than Perl). Most of the work
322 toward fixing this has now been done, however, and all that's still needed
325 The \s-1NAME\s0 section should be recognized specially and index entries emitted
326 for everything in that section. This would have to be deferred until the
327 next section, since extraneous things in \s-1NAME\s0 tends to confuse various man
328 page processors. Currently, no index entries are emitted for anything in
331 Pod::Man doesn't handle font names longer than two characters. Neither do
332 most \fBtroff\fR implementations, but \s-1GNU\s0 troff does as an extension. It would
333 be nice to support as an option for those who want to use it.
335 The preamble added to each output file is rather verbose, and most of it
336 is only necessary in the presence of non-ASCII characters. It would
337 ideally be nice if all of those definitions were only output if needed,
338 perhaps on the fly as the characters are used.
340 Pod::Man is excessively slow.
343 If Pod::Man is given the \f(CW\*(C`utf8\*(C'\fR option, the encoding of its output file
344 handle will be forced to \s-1UTF\-8\s0 if possible, overriding any existing
345 encoding. This will be done even if the file handle is not created by
346 Pod::Man and was passed in from outside. This maintains consistency
347 regardless of \s-1PERL_UNICODE\s0 and other settings.
349 The handling of hyphens and em dashes is somewhat fragile, and one may get
350 the wrong one under some circumstances. This should only matter for
351 \&\fBtroff\fR output.
353 When and whether to use small caps is somewhat tricky, and Pod::Man doesn't
354 necessarily get it right.
356 Converting neutral double quotes to properly matched double quotes doesn't
357 work unless there are no formatting codes between the quote marks. This
358 only matters for troff output.
361 Russ Allbery <rra@stanford.edu>, based \fIvery\fR heavily on the original
362 \&\fBpod2man\fR by Tom Christiansen <tchrist@mox.perl.com>. The modifications to
363 work with Pod::Simple instead of Pod::Parser were originally contributed by
364 Sean Burke (but I've since hacked them beyond recognition and all bugs are
366 .SH "COPYRIGHT AND LICENSE"
367 .IX Header "COPYRIGHT AND LICENSE"
368 Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
369 Russ Allbery <rra@stanford.edu>.
371 This program is free software; you may redistribute it and/or modify it
372 under the same terms as Perl itself.
374 .IX Header "SEE ALSO"
375 Pod::Simple, \fIperlpod\fR\|(1), \fIpod2man\fR\|(1), \fInroff\fR\|(1), \fItroff\fR\|(1),
376 \&\fIman\fR\|(1), \fIman\fR\|(7)
378 Ossanna, Joseph F., and Brian W. Kernighan. \*(L"Troff User's Manual,\*(R"
379 Computing Science Technical Report No. 54, \s-1AT&T\s0 Bell Laboratories. This is
380 the best documentation of standard \fBnroff\fR and \fBtroff\fR. At the time of
381 this writing, it's available at
382 <http://www.cs.bell\-labs.com/cm/cs/cstr.html>.
384 The man page documenting the man macro set may be \fIman\fR\|(5) instead of
385 \&\fIman\fR\|(7) on your system. Also, please see \fIpod2man\fR\|(1) for extensive
386 documentation on writing manual pages if you've not done it before and
387 aren't familiar with the conventions.
389 The current version of this module is always available from its web site at
390 <http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
391 Perl core distribution as of 5.6.0.
projects / catagits/Gitalist.git / blob