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 "POD2MAN 1"
132 .TH POD2MAN 1 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
134 pod2man \- Convert POD data to formatted *roff input
136 .IX Header "SYNOPSIS"
137 pod2man [\fB\-\-center\fR=\fIstring\fR] [\fB\-\-date\fR=\fIstring\fR]
138 [\fB\-\-fixed\fR=\fIfont\fR] [\fB\-\-fixedbold\fR=\fIfont\fR] [\fB\-\-fixeditalic\fR=\fIfont\fR]
139 [\fB\-\-fixedbolditalic\fR=\fIfont\fR] [\fB\-\-name\fR=\fIname\fR] [\fB\-\-official\fR]
140 [\fB\-\-quotes\fR=\fIquotes\fR] [\fB\-\-release\fR[=\fIversion\fR]]
141 [\fB\-\-section\fR=\fImanext\fR] [\fB\-\-stderr\fR] [\fB\-\-utf8\fR] [\fB\-\-verbose\fR]
142 [\fIinput\fR [\fIoutput\fR] ...]
144 pod2man \fB\-\-help\fR
146 .IX Header "DESCRIPTION"
147 \&\fBpod2man\fR is a front-end for Pod::Man, using it to generate *roff input
148 from \s-1POD\s0 source. The resulting *roff code is suitable for display on a
149 terminal using \fInroff\fR\|(1), normally via \fIman\fR\|(1), or printing using \fItroff\fR\|(1).
151 \&\fIinput\fR is the file to read for \s-1POD\s0 source (the \s-1POD\s0 can be embedded in
152 code). If \fIinput\fR isn't given, it defaults to \f(CW\*(C`STDIN\*(C'\fR. \fIoutput\fR, if
153 given, is the file to which to write the formatted output. If \fIoutput\fR
154 isn't given, the formatted output is written to \f(CW\*(C`STDOUT\*(C'\fR. Several \s-1POD\s0
155 files can be processed in the same \fBpod2man\fR invocation (saving module
156 load and compile times) by providing multiple pairs of \fIinput\fR and
157 \&\fIoutput\fR files on the command line.
159 \&\fB\-\-section\fR, \fB\-\-release\fR, \fB\-\-center\fR, \fB\-\-date\fR, and \fB\-\-official\fR can
160 be used to set the headers and footers to use; if not given, Pod::Man will
161 assume various defaults. See below or Pod::Man for details.
163 \&\fBpod2man\fR assumes that your *roff formatters have a fixed-width font
164 named \f(CW\*(C`CW\*(C'\fR. If yours is called something else (like \f(CW\*(C`CR\*(C'\fR), use
165 \&\fB\-\-fixed\fR to specify it. This generally only matters for troff output
166 for printing. Similarly, you can set the fonts used for bold, italic, and
167 bold italic fixed-width output.
169 Besides the obvious pod conversions, Pod::Man, and therefore pod2man also
170 takes care of formatting \fIfunc()\fR, func(n), and simple variable references
171 like \f(CW$foo\fR or \f(CW@bar\fR so you don't have to use code escapes for them; complex
172 expressions like \f(CW$fred{'stuff'}\fR will still need to be escaped, though.
173 It also translates dashes that aren't used as hyphens into en dashes, makes
174 long dashes\*(--like this\*(--into proper em dashes, fixes \*(L"paired quotes,\*(R" and
175 takes care of several other troff-specific tweaks. See Pod::Man for
176 complete information.
179 .IP "\fB\-c\fR \fIstring\fR, \fB\-\-center\fR=\fIstring\fR" 4
180 .IX Item "-c string, --center=string"
181 Sets the centered page header to \fIstring\fR. The default is \*(L"User
182 Contributed Perl Documentation\*(R", but also see \fB\-\-official\fR below.
183 .IP "\fB\-d\fR \fIstring\fR, \fB\-\-date\fR=\fIstring\fR" 4
184 .IX Item "-d string, --date=string"
185 Set the left-hand footer string to this value. By default, the modification
186 date of the input file will be used, or the current date if input comes from
187 \&\f(CW\*(C`STDIN\*(C'\fR.
188 .IP "\fB\-\-fixed\fR=\fIfont\fR" 4
189 .IX Item "--fixed=font"
190 The fixed-width font to use for verbatim text and code. Defaults to
191 \&\f(CW\*(C`CW\*(C'\fR. Some systems may want \f(CW\*(C`CR\*(C'\fR instead. Only matters for \fItroff\fR\|(1)
193 .IP "\fB\-\-fixedbold\fR=\fIfont\fR" 4
194 .IX Item "--fixedbold=font"
195 Bold version of the fixed-width font. Defaults to \f(CW\*(C`CB\*(C'\fR. Only matters
196 for \fItroff\fR\|(1) output.
197 .IP "\fB\-\-fixeditalic\fR=\fIfont\fR" 4
198 .IX Item "--fixeditalic=font"
199 Italic version of the fixed-width font (actually, something of a misnomer,
200 since most fixed-width fonts only have an oblique version, not an italic
201 version). Defaults to \f(CW\*(C`CI\*(C'\fR. Only matters for \fItroff\fR\|(1) output.
202 .IP "\fB\-\-fixedbolditalic\fR=\fIfont\fR" 4
203 .IX Item "--fixedbolditalic=font"
204 Bold italic (probably actually oblique) version of the fixed-width font.
205 Pod::Man doesn't assume you have this, and defaults to \f(CW\*(C`CB\*(C'\fR. Some
206 systems (such as Solaris) have this font available as \f(CW\*(C`CX\*(C'\fR. Only matters
207 for \fItroff\fR\|(1) output.
208 .IP "\fB\-h\fR, \fB\-\-help\fR" 4
209 .IX Item "-h, --help"
210 Print out usage information.
211 .IP "\fB\-l\fR, \fB\-\-lax\fR" 4
213 No longer used. \fBpod2man\fR used to check its input for validity as a
214 manual page, but this should now be done by \fIpodchecker\fR\|(1) instead.
215 Accepted for backward compatibility; this option no longer does anything.
216 .IP "\fB\-n\fR \fIname\fR, \fB\-\-name\fR=\fIname\fR" 4
217 .IX Item "-n name, --name=name"
218 Set the name of the manual page to \fIname\fR. Without this option, the manual
219 name is set to the uppercased base name of the file being converted unless
220 the manual section is 3, in which case the path is parsed to see if it is a
221 Perl module path. If it is, a path like \f(CW\*(C`.../lib/Pod/Man.pm\*(C'\fR is converted
222 into a name like \f(CW\*(C`Pod::Man\*(C'\fR. This option, if given, overrides any
223 automatic determination of the name.
225 Note that this option is probably not useful when converting multiple \s-1POD\s0
226 files at once. The convention for Unix man pages for commands is for the
227 man page title to be in all-uppercase even if the command isn't.
228 .IP "\fB\-o\fR, \fB\-\-official\fR" 4
229 .IX Item "-o, --official"
230 Set the default header to indicate that this page is part of the standard
231 Perl release, if \fB\-\-center\fR is not also given.
232 .IP "\fB\-q\fR \fIquotes\fR, \fB\-\-quotes\fR=\fIquotes\fR" 4
233 .IX Item "-q quotes, --quotes=quotes"
234 Sets the quote marks used to surround C<> text to \fIquotes\fR. If
235 \&\fIquotes\fR is a single character, it is used as both the left and right
236 quote; if \fIquotes\fR is two characters, the first character is used as the
237 left quote and the second as the right quoted; and if \fIquotes\fR is four
238 characters, the first two are used as the left quote and the second two as
241 \&\fIquotes\fR may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no
242 quote marks are added around C<> text (but the font is still changed for
244 .IP "\fB\-r\fR, \fB\-\-release\fR" 4
245 .IX Item "-r, --release"
246 Set the centered footer. By default, this is the version of Perl you run
247 \&\fBpod2man\fR under. Note that some system an macro sets assume that the
248 centered footer will be a modification date and will prepend something like
249 \&\*(L"Last modified: \*(R"; if this is the case, you may want to set \fB\-\-release\fR to
250 the last modified date and \fB\-\-date\fR to the version number.
251 .IP "\fB\-s\fR, \fB\-\-section\fR" 4
252 .IX Item "-s, --section"
253 Set the section for the \f(CW\*(C`.TH\*(C'\fR macro. The standard section numbering
254 convention is to use 1 for user commands, 2 for system calls, 3 for
255 functions, 4 for devices, 5 for file formats, 6 for games, 7 for
256 miscellaneous information, and 8 for administrator commands. There is a lot
257 of variation here, however; some systems (like Solaris) use 4 for file
258 formats, 5 for miscellaneous information, and 7 for devices. Still others
259 use 1m instead of 8, or some mix of both. About the only section numbers
260 that are reliably consistent are 1, 2, and 3.
262 By default, section 1 will be used unless the file ends in \f(CW\*(C`.pm\*(C'\fR, in
263 which case section 3 will be selected.
264 .IP "\fB\-\-stderr\fR" 4
266 By default, \fBpod2man\fR puts any errors detected in the \s-1POD\s0 input in a \s-1POD\s0
267 \&\s-1ERRORS\s0 section in the output manual page. If \fB\-\-stderr\fR is given, errors
268 are sent to standard error instead and the \s-1POD\s0 \s-1ERRORS\s0 section is
270 .IP "\fB\-u\fR, \fB\-\-utf8\fR" 4
271 .IX Item "-u, --utf8"
272 By default, \fBpod2man\fR produces the most conservative possible *roff
273 output to try to ensure that it will work with as many different *roff
274 implementations as possible. Many *roff implementations cannot handle
275 non-ASCII characters, so this means all non-ASCII characters are converted
276 either to a *roff escape sequence that tries to create a properly accented
277 character (at least for troff output) or to \f(CW\*(C`X\*(C'\fR.
279 This option says to instead output literal \s-1UTF\-8\s0 characters. If your
280 *roff implementation can handle it, this is the best output format to use
281 and avoids corruption of documents containing non-ASCII characters.
282 However, be warned that *roff source with literal \s-1UTF\-8\s0 characters is not
283 supported by many implementations and may even result in segfaults and
286 Be aware that, when using this option, the input encoding of your \s-1POD\s0
287 source must be properly declared unless it is US-ASCII or Latin\-1. \s-1POD\s0
288 input without an \f(CW\*(C`=encoding\*(C'\fR command will be assumed to be in Latin\-1,
289 and if it's actually in \s-1UTF\-8\s0, the output will be double\-encoded. See
290 \&\fIperlpod\fR\|(1) for more information on the \f(CW\*(C`=encoding\*(C'\fR command.
291 .IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
292 .IX Item "-v, --verbose"
293 Print out the name of each output file as it is being generated.
295 .IX Header "DIAGNOSTICS"
296 If \fBpod2man\fR fails with errors, see Pod::Man and Pod::Simple for
297 information about what those errors might mean.
299 .IX Header "EXAMPLES"
301 \& pod2man program > program.1
302 \& pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
303 \& pod2man \-\-section=7 note.pod > note.7
306 If you would like to print out a lot of man page continuously, you probably
307 want to set the C and D registers to set contiguous page numbering and
308 even/odd paging, at least on some versions of \fIman\fR\|(7).
311 \& troff \-man \-rC1 \-rD1 perl.1 perldata.1 perlsyn.1 ...
314 To get index entries on \f(CW\*(C`STDERR\*(C'\fR, turn on the F register, as in:
317 \& troff \-man \-rF1 perl.1
320 The indexing merely outputs messages via \f(CW\*(C`.tm\*(C'\fR for each major page,
321 section, subsection, item, and any \f(CW\*(C`X<>\*(C'\fR directives. See
322 Pod::Man for more details.
325 Lots of this documentation is duplicated from Pod::Man.
328 For those not sure of the proper layout of a man page, here are some notes
329 on writing a proper man page.
331 The name of the program being documented is conventionally written in bold
332 (using B<>) wherever it occurs, as are all program options.
333 Arguments should be written in italics (I<>). Functions are
334 traditionally written in italics; if you write a function as \fIfunction()\fR,
335 Pod::Man will take care of this for you. Literal code or commands should
336 be in C<>. References to other man pages should be in the form
337 \&\f(CW\*(C`manpage(section)\*(C'\fR, and Pod::Man will automatically format those
338 appropriately. As an exception, it's traditional not to use this form when
339 referring to module documentation; use \f(CW\*(C`L<Module::Name>\*(C'\fR instead.
341 References to other programs or functions are normally in the form of man
342 page references so that cross-referencing tools can provide the user with
343 links and the like. It's possible to overdo this, though, so be careful not
344 to clutter your documentation with too much markup.
346 The major headers should be set out using a \f(CW\*(C`=head1\*(C'\fR directive, and are
347 historically written in the rather startling \s-1ALL\s0 \s-1UPPER\s0 \s-1CASE\s0 format, although
348 this is not mandatory. Minor headers may be included using \f(CW\*(C`=head2\*(C'\fR, and
349 are typically in mixed case.
351 The standard sections of a manual page are:
354 Mandatory section; should be a comma-separated list of programs or functions
355 documented by this \s-1POD\s0 page, such as:
358 \& foo, bar \- programs to do something
361 Manual page indexers are often extremely picky about the format of this
362 section, so don't put anything in it except this line. A single dash, and
363 only a single dash, should separate the list of programs or functions from
364 the description. Functions should not be qualified with \f(CW\*(C`()\*(C'\fR or the like.
365 The description should ideally fit on a single line, even if a man program
366 replaces the dash with a few tabs.
367 .IP "\s-1SYNOPSIS\s0" 4
369 A short usage summary for programs and functions. This section is mandatory
371 .IP "\s-1DESCRIPTION\s0" 4
372 .IX Item "DESCRIPTION"
373 Extended description and discussion of the program or functions, or the body
374 of the documentation for man pages that document something else. If
375 particularly long, it's a good idea to break this up into subsections
376 \&\f(CW\*(C`=head2\*(C'\fR directives like:
379 \& =head2 Normal Usage
383 \& =head2 Advanced Features
387 \& =head2 Writing Configuration Files
390 or whatever is appropriate for your documentation.
391 .IP "\s-1OPTIONS\s0" 4
393 Detailed description of each of the command-line options taken by the
394 program. This should be separate from the description for the use of things
395 like Pod::Usage. This is normally presented as a list, with
396 each option as a separate \f(CW\*(C`=item\*(C'\fR. The specific option string should be
397 enclosed in B<>. Any values that the option takes should be
398 enclosed in I<>. For example, the section for the option
399 \&\fB\-\-section\fR=\fImanext\fR would be introduced with:
402 \& =item B<\-\-section>=I<manext>
405 Synonymous options (like both the short and long forms) are separated by a
406 comma and a space on the same \f(CW\*(C`=item\*(C'\fR line, or optionally listed as their
407 own item with a reference to the canonical name. For example, since
408 \&\fB\-\-section\fR can also be written as \fB\-s\fR, the above would be:
411 \& =item B<\-s> I<manext>, B<\-\-section>=I<manext>
414 (Writing the short option first is arguably easier to read, since the long
415 option is long enough to draw the eye to it anyway and the short option can
416 otherwise get lost in visual noise.)
417 .IP "\s-1RETURN\s0 \s-1VALUE\s0" 4
418 .IX Item "RETURN VALUE"
419 What the program or function returns, if successful. This section can be
420 omitted for programs whose precise exit codes aren't important, provided
421 they return 0 on success as is standard. It should always be present for
423 .IP "\s-1ERRORS\s0" 4
425 Exceptions, error return codes, exit statuses, and errno settings.
426 Typically used for function documentation; program documentation uses
427 \&\s-1DIAGNOSTICS\s0 instead. The general rule of thumb is that errors printed to
428 \&\f(CW\*(C`STDOUT\*(C'\fR or \f(CW\*(C`STDERR\*(C'\fR and intended for the end user are documented in
429 \&\s-1DIAGNOSTICS\s0 while errors passed internal to the calling program and
430 intended for other programmers are documented in \s-1ERRORS\s0. When documenting
431 a function that sets errno, a full list of the possible errno values
432 should be given here.
433 .IP "\s-1DIAGNOSTICS\s0" 4
434 .IX Item "DIAGNOSTICS"
435 All possible messages the program can print out\*(--and what they mean. You
436 may wish to follow the same documentation style as the Perl documentation;
437 see \fIperldiag\fR\|(1) for more details (and look at the \s-1POD\s0 source as well).
439 If applicable, please include details on what the user should do to correct
440 the error; documenting an error as indicating \*(L"the input buffer is too
441 small\*(R" without telling the user how to increase the size of the input buffer
442 (or at least telling them that it isn't possible) aren't very useful.
443 .IP "\s-1EXAMPLES\s0" 4
445 Give some example uses of the program or function. Don't skimp; users often
446 find this the most useful part of the documentation. The examples are
447 generally given as verbatim paragraphs.
449 Don't just present an example without explaining what it does. Adding a
450 short paragraph saying what the example will do can increase the value of
451 the example immensely.
452 .IP "\s-1ENVIRONMENT\s0" 4
453 .IX Item "ENVIRONMENT"
454 Environment variables that the program cares about, normally presented as a
455 list using \f(CW\*(C`=over\*(C'\fR, \f(CW\*(C`=item\*(C'\fR, and \f(CW\*(C`=back\*(C'\fR. For example:
466 \& Used to determine the user's home directory. F<.foorc> in this
467 \& directory is read for configuration details, if it exists.
474 Since environment variables are normally in all uppercase, no additional
475 special formatting is generally needed; they're glaring enough as it is.
478 All files used by the program or function, normally presented as a list, and
479 what it uses them for. File names should be enclosed in F<>. It's
480 particularly important to document files that will be potentially modified.
481 .IP "\s-1CAVEATS\s0" 4
483 Things to take special care with, sometimes called \s-1WARNINGS\s0.
486 Things that are broken or just don't work quite right.
487 .IP "\s-1RESTRICTIONS\s0" 4
488 .IX Item "RESTRICTIONS"
489 Bugs you don't plan to fix. :\-)
492 Miscellaneous commentary.
493 .IP "\s-1AUTHOR\s0" 4
495 Who wrote it (use \s-1AUTHORS\s0 for multiple people). Including your current
496 e\-mail address (or some e\-mail address to which bug reports should be sent)
497 so that users have a way of contacting you is a good idea. Remember that
498 program documentation tends to roam the wild for far longer than you expect
499 and pick an e\-mail address that's likely to last if possible.
500 .IP "\s-1HISTORY\s0" 4
502 Programs derived from other sources sometimes have this, or you might keep
503 a modification log here. If the log gets overly long or detailed,
504 consider maintaining it in a separate file, though.
505 .IP "\s-1COPYRIGHT\s0 \s-1AND\s0 \s-1LICENSE\s0" 4
506 .IX Item "COPYRIGHT AND LICENSE"
510 \& Copyright YEAR(s) by YOUR NAME(s)
513 (No, (C) is not needed. No, \*(L"all rights reserved\*(R" is not needed.)
515 For licensing the easiest way is to use the same licensing as Perl itself:
518 \& This library is free software; you may redistribute it and/or modify
519 \& it under the same terms as Perl itself.
522 This makes it easy for people to use your module with Perl. Note that
523 this licensing is neither an endorsement or a requirement, you are of
524 course free to choose any licensing.
525 .IP "\s-1SEE\s0 \s-1ALSO\s0" 4
527 Other man pages to check out, like \fIman\fR\|(1), \fIman\fR\|(7), \fImakewhatis\fR\|(8), or
528 \&\fIcatman\fR\|(8). Normally a simple list of man pages separated by commas, or a
529 paragraph giving the name of a reference work. Man page references, if they
530 use the standard \f(CW\*(C`name(section)\*(C'\fR form, don't have to be enclosed in
531 L<> (although it's recommended), but other things in this section
532 probably should be when appropriate.
534 If the package has a mailing list, include a \s-1URL\s0 or subscription
537 If the package has a web site, include a \s-1URL\s0 here.
539 In addition, some systems use \s-1CONFORMING\s0 \s-1TO\s0 to note conformance to relevant
540 standards and MT-LEVEL to note safeness for use in threaded programs or
541 signal handlers. These headings are primarily useful when documenting parts
542 of a C library. Documentation of object-oriented libraries or modules may
543 use \s-1CONSTRUCTORS\s0 and \s-1METHODS\s0 sections for detailed documentation of the
544 parts of the library and save the \s-1DESCRIPTION\s0 section for an overview; other
545 large modules may use \s-1FUNCTIONS\s0 for similar reasons. Some people use
546 \&\s-1OVERVIEW\s0 to summarize the description if it's quite long.
548 Section ordering varies, although \s-1NAME\s0 should \fIalways\fR be the first section
549 (you'll break some man page systems otherwise), and \s-1NAME\s0, \s-1SYNOPSIS\s0,
550 \&\s-1DESCRIPTION\s0, and \s-1OPTIONS\s0 generally always occur first and in that order if
551 present. In general, \s-1SEE\s0 \s-1ALSO\s0, \s-1AUTHOR\s0, and similar material should be left
552 for last. Some systems also move \s-1WARNINGS\s0 and \s-1NOTES\s0 to last. The order
553 given above should be reasonable for most purposes.
555 Finally, as a general note, try not to use an excessive amount of markup.
556 As documented here and in Pod::Man, you can safely leave Perl variables,
557 function names, man page references, and the like unadorned by markup and
558 the \s-1POD\s0 translators will figure it out for you. This makes it much easier
559 to later edit the documentation. Note that many existing translators
560 (including this one currently) will do the wrong thing with e\-mail addresses
561 when wrapped in L<>, so don't do that.
563 For additional information that may be more accurate for your specific
564 system, see either \fIman\fR\|(5) or \fIman\fR\|(7) depending on your system manual
565 section numbering conventions.
567 .IX Header "SEE ALSO"
568 Pod::Man, Pod::Simple, \fIman\fR\|(1), \fInroff\fR\|(1), \fIperlpod\fR\|(1),
569 \&\fIpodchecker\fR\|(1), \fItroff\fR\|(1), \fIman\fR\|(7)
571 The man page documenting the an macro set may be \fIman\fR\|(5) instead of
572 \&\fIman\fR\|(7) on your system.
574 The current version of this script is always available from its web site at
575 <http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
576 Perl core distribution as of 5.6.0.
579 Russ Allbery <rra@stanford.edu>, based \fIvery\fR heavily on the original
580 \&\fBpod2man\fR by Larry Wall and Tom Christiansen. Large portions of this
581 documentation, particularly the sections on the anatomy of a proper man
582 page, are taken from the \fBpod2man\fR documentation by Tom.
583 .SH "COPYRIGHT AND LICENSE"
584 .IX Header "COPYRIGHT AND LICENSE"
585 Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery
588 This program is free software; you may redistribute it and/or modify it
589 under the same terms as Perl itself.
projects / catagits/Gitalist.git / blob