Penguin
Recent Changes
Annotated edit history of pod2man(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 POD2MAN
2 !!!POD2MAN
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 DIAGNOSTICS
8 EXAMPLES
9 BUGS
10 NOTES
11 SEE ALSO
12 AUTHOR
13 ----
14 !!NAME
15
16
17 pod2man - Convert POD data to formatted *roff input
18 !!SYNOPSIS
19
20
21 pod2man [[__--section__=''manext'']
22 [[__--release__=''version'']
23 [[__--center__=''string'']
24 [[__--date__=''string''] [[__--fixed__=''font'']
25 [[__--fixedbold__=''font'']
26 [[__--fixeditalic__=''font'']
27 [[__--fixedbolditalic__=''font''] [[__--official__]
28 [[__--lax__] [[__--quotes__=''quotes''] [[''input''
29 [[''output''] ...]
30
31
32 pod2man __--help__
33 !!DESCRIPTION
34
35
36 __pod2man__ is a front-end for Pod::Man, using it to
37 generate *roff input from POD source. The
38 resulting *roff code is suitable for display on a terminal
39 using nroff(1), normally via man(1), or
40 printing using troff(1).
41
42
43 ''input'' is the file to read for POD
44 source (the POD can be embedded in code). If
45 ''input'' isn't given, it defaults to
46 STDIN . ''output'', if given, is the file
47 to which to write the formatted output. If ''output''
48 isn't given, the formatted output is written to
49 STDOUT . Several POD files can
50 be processed in the same __pod2man__ invocation (saving
51 module load and compile times) by providing multiple pairs
52 of ''input'' and ''output'' files on the command
53 line.
54
55
56 __--section__, __--release__, __--center__,
57 __--date__, and __--official__ can be used to set the
58 headers and footers to use; if not given, Pod::Man will
59 assume various defaults. See below or Pod::Man for
60 details.
61
62
63 __pod2man__ assumes that your *roff formatters have a
64 fixed-width font named CW . If yours is
65 called something else (like CR ), use
66 __--fixed__ to specify it. This generally only matters
67 for troff output for printing. Similarly, you can set the
68 fonts used for bold, italic, and bold italic fixed-width
69 output.
70
71
72 Besides the obvious pod conversions, Pod::Man, and therefore
73 pod2man also takes care of formatting ''func()'',
74 func(n), and simple variable references like $foo
75 or @bar so you don't have to use code escapes for
76 them; complex expressions like $fred{'stuff'} will
77 still need to be escaped, though. It also translates dashes
78 that aren't used as hyphens into en dashes, makes long
79 dashes--like this--into proper em dashes, fixes ``paired
80 quotes,'' and takes care of several other troff-specific
81 tweaks. See Pod::Man for complete information.
82 !!OPTIONS
83
84
85 __-c__ ''string'',
86 __--center__=''string''
87
88
89 Sets the centered page header to ''string''. The default
90 is ``User Contributed Perl Documentation'', but also see
91 __--official__ below.
92
93
94 __-d__ ''string'',
95 __--date__=''string''
96
97
98 Set the left-hand footer string to this value. By default,
99 the modification date of the input file will be used, or the
100 current date if input comes from STDIN
101 .
102
103
104 __--fixed__=''font''
105
106
107 The fixed-width font to use for vertabim text and code.
108 Defaults to CW . Some systems may want
109 CR instead. Only matters for troff(1)
110 output.
111
112
113 __--fixedbold__=''font''
114
115
116 Bold version of the fixed-width font. Defaults to
117 CB . Only matters for troff(1)
118 output.
119
120
121 __--fixeditalic__=''font''
122
123
124 Italic version of the fixed-width font (actually, something
125 of a misnomer, since most fixed-width fonts only have an
126 oblique version, not an italic version). Defaults to
127 CI . Only matters for troff(1)
128 output.
129
130
131 __--fixedbolditalic__=''font''
132
133
134 Bold italic (probably actually oblique) version of the
135 fixed-width font. Pod::Man doesn't assume you have this, and
136 defaults to CB . Some systems (such as
137 Solaris) have this font available as CX .
138 Only matters for troff(1) output.
139
140
141 __-h__, __--help__
142
143
144 Print out usage information.
145
146
147 __-l__, __--lax__
148
149
150 Don't complain when required sections are missing. Not
151 currently used, as POD checking functionality
152 is not yet implemented in Pod::Man.
153
154
155 __-o__, __--official__
156
157
158 Set the default header to indicate that this page is part of
159 the standard Perl release, if __--center__ is not also
160 given.
161
162
163 __-q__ ''quotes'',
164 __--quotes__=''quotes''
165
166
167 Sets the quote marks used to surround C
168 quotes''. If ''quotes'' is a single character, it is
169 used as both the left and right quote; if ''quotes'' is
170 two characters, the first character is used as the left
171 quote and the second as the right quoted; and if
172 ''quotes'' is four characters, the first two are used as
173 the left quote and the second two as the right
174 quote.
175
176
177 ''quotes'' may also be set to the special value
178 none, in which case no quote marks are added around
179 C
180
181
182 __-r__, __--release__
183
184
185 Set the centered footer. By default, this is the version of
186 Perl you run __pod2man__ under. Note that some system an
187 macro sets assume that the centered footer will be a
188 modification date and will prepend something like ``Last
189 modified: ''; if this is the case, you may want to set
190 __--release__ to the last modified date and __--date__
191 to the version number.
192
193
194 __-s__, __--section__
195
196
197 Set the section for the .TH macro. The standard
198 section numbering convention is to use 1 for user commands,
199 2 for system calls, 3 for functions, 4 for devices, 5 for
200 file formats, 6 for games, 7 for miscellaneous information,
201 and 8 for administrator commands. There is a lot of
202 variation here, however; some systems (like Solaris) use 4
203 for file formats, 5 for miscellaneous information, and 7 for
204 devices. Still others use 1m instead of 8, or some mix of
205 both. About the only section numbers that are reliably
206 consistent are 1, 2, and 3.
207
208
209 By default, section 1 will be used unless the file ends in
210 .pm in which case section 3 will be selected.
211 !!DIAGNOSTICS
212
213
214 If __pod2man__ fails with errors, see Pod::Man and
215 Pod::Parser for information about what those errors might
216 mean.
217 !!EXAMPLES
218
219
220 pod2man program
221 If you would like to print out a lot of man page continuously, you probably want to set the C and D registers to set contiguous page numbering and even/odd paging, at least on some versions of man(7).
222
223
224 troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
225 To get index entries on stderr, turn on the F register, as in:
226
227
228 troff -man -rF1 perl.1
229 The indexing merely outputs messages via .tm for each major page, section, subsection, item, and any X directives. See Pod::Man for more details.
230 !!BUGS
231
232
233 Lots of this documentation is duplicated from
234 Pod::Man.
235
236
237 POD checking and the corresponding
238 __--lax__ option don't work yet.
239 !!NOTES
240
241
242 For those not sure of the proper layout of a man page, here
243 are some notes on writing a proper man page.
244
245
246 The name of the program being documented is conventionally
247 written in bold (using B
248 function()'', Pod::Man will
249 take care of this for you. Literal code or commands should
250 be in C
251 ''manpage(section), and Pod::Man will
252 automatically format those appropriately. As an exception,
253 it's traditional not to use this form when referring to
254 module documentation; use L
255 instead.
256
257
258 References to other programs or functions are normally in
259 the form of man page references so that cross-referencing
260 tools can provide the user with links and the like. It's
261 possible to overdo this, though, so be careful not to
262 clutter your documentation with too much
263 markup.
264
265
266 The major headers should be set out using a =head1
267 directive, and are historically written in the rather
268 startling ALL UPPER CASE format, although
269 this is not mandatory. Minor headers may be included using
270 =head2, and are typically in mixed
271 case.
272
273
274 The standard sections of a manual page are:
275
276
277 NAME
278
279
280 Mandatory section; should be a comma-separated list of
281 programs or functions documented by this podpage, such
282 as:
283
284
285 foo, bar - programs to do something
286 Manual page indexers are often extremely picky about the format of this section, so don't put anything in it except this line. A single dash, and only a single dash, should separate the list of programs or functions from the description. Functions should not be qualified with () or the like. The description should ideally fit on a single line, even if a man program replaces the dash with a few tabs.
287
288
289 SYNOPSIS
290
291
292 A short usage summary for programs and functions. This
293 section is mandatory for section 3 pages.
294
295
296 DESCRIPTION
297
298
299 Extended description and discussion of the program or
300 functions, or the body of the documentation for man pages
301 that document something else. If particularly long, it's a
302 good idea to break this up into subsections =head2
303 directives like:
304
305
306 =head2 Normal Usage
307 =head2 Advanced Features
308 =head2 Writing Configuration Files
309 or whatever is appropriate for your documentation.
310
311
312 OPTIONS
313
314
315 Detailed description of each of the command-line options
316 taken by the program. This should be separate from the
317 description for the use of things like Pod::Usage. This is
318 normally presented as a list, with each option as a separate
319 =item. The specific option string should be
320 enclosed in B
321 --section__=''manext'' would be
322 introduced with:
323
324
325 =item B
326 Synonymous options (like both the short and long forms) are separated by a comma and a space on the same =item line, or optionally listed as their own item with a reference to the canonical name. For example, since __--section__ can also be written as __-s__, the above would be:
327
328
329 =item B
330 (Writing the short option first is arguably easier to read, since the long option is long enough to draw the eye to it anyway and the short option can otherwise get lost in visual noise.)
331
332
333 RETURN VALUE
334
335
336 What the program or function returns, if successful. This
337 section can be omitted for programs whose precise exit codes
338 aren't important, provided they return 0 on success as is
339 standard. It should always be present for
340 functions.
341
342
343 ERRORS
344
345
346 Exceptions, error return codes, exit statuses, and errno
347 settings. Typically used for function documentation; program
348 documentation uses DIAGNOSTICS instead. The
349 general rule of thumb is that errors printed to
350 STDOUT or STDERR and intended
351 for the end user are documented in
352 DIAGNOSTICS while errors passed internal to
353 the calling program and intended for other programmers are
354 documented in ERRORS . When documenting a
355 function that sets errno, a full list of the possible errno
356 values should be given here.
357
358
359 DIAGNOSTICS
360
361
362 All possible messages the program can print out--and what
363 they mean. You may wish to follow the same documentation
364 style as the Perl documentation; see perldiag(1) for
365 more details (and look at the POD source as
366 well).
367
368
369 If applicable, please include details on what the user
370 should do to correct the error; documenting an error as
371 indicating ``the input buffer is too small'' without telling
372 the user how to increase the size of the input buffer (or at
373 least telling them that it isn't possible) aren't very
374 useful.
375
376
377 EXAMPLES
378
379
380 Give some example uses of the program or function. Don't
381 skimp; users often find this the most useful part of the
382 documentation. The examples are generally given as verbatim
383 paragraphs.
384
385
386 Don't just present an example without explaining what it
387 does. Adding a short paragraph saying what the example will
388 do can increase the value of the example
389 immensely.
390
391
392 ENVIRONMENT
393
394
395 Environment variables that the program cares about, normally
396 presented as a list using =over, =item,
397 and =back. For example:
398
399
400 =over 6
401 =item HOME
402 Used to determine the user's home directory. F
403 =back
404 Since environment variables are normally in all uppercase, no additional special formatting is generally needed; they're glaring enough as it is.
405
406
407 FILES
408
409
410 All files used by the program or function, normally
411 presented as a list, and what it uses them for. File names
412 should be enclosed in F
413
414
415 CAVEATS
416
417
418 Things to take special care with, sometimes called
419 WARNINGS .
420
421
422 BUGS
423
424
425 Things that are broken or just don't work quite
426 right.
427
428
429 RESTRICTIONS
430
431
432 Bugs you don't plan to fix. :-)
433
434
435 NOTES
436
437
438 Miscellaneous commentary.
439
440
441 SEE ALSO
442
443
444 Other man pages to check out, like man(1),
445 man(7), makewhatis(8), or catman(8).
446 Normally a simple list of man pages separated by commas, or
447 a paragraph giving the name of a reference work. Man page
448 references, if they use the standard name(section)
449 form, don't have to be enclosed in L
450 L syntax to
451 keep __pod2man__ and __pod2text__ from being too
452 verbose; see perlpod(1).
453
454
455 If the package has a web site, include a URL
456 here.
457
458
459 AUTHOR
460
461
462 Who wrote it (use AUTHORS for multiple
463 people). Including your current e-mail address (or some
464 e-mail address to which bug reports should be sent) so that
465 users have a way of contacting you is a good idea. Remember
466 that program documentation tends to roam the wild for far
467 longer than you expect and pick an e-mail address that's
468 likely to last if possible.
469
470
471 HISTORY
472
473
474 Programs derived from other sources sometimes have this, or
475 you might keep a modification log here.
476
477
478 In addition, some systems use CONFORMING TO
479 to note conformance to relevant standards and MT-LEVEL to
480 note safeness for use in threaded programs or signal
481 handlers. These headings are primarily useful when
482 documenting parts of a C library. Documentation of
483 object-oriented libraries or modules may use
484 CONSTRUCTORS and METHODS
485 sections for detailed documentation of the parts of the
486 library and save the DESCRIPTION section for
487 an overview; other large modules may use
488 FUNCTIONS for similar reasons. Some people
489 use OVERVIEW to summarize the description if
490 it's quite long. Sometimes there's an additional
491 COPYRIGHT section at the bottom, for
492 licensing terms. AVAILABILITY is sometimes
493 added, giving the canonical download site for the software
494 or a URL for updates.
495
496
497 Section ordering varies, although NAME should
498 ''always'' be the first section (you'll break some man
499 page systems otherwise), and NAME ,
500 SYNOPSIS , DESCRIPTION , and
501 OPTIONS generally always occur first and in
502 that order if present. In general, SEE ALSO ,
503 AUTHOR , and similar material should be left
504 for last. Some systems also move WARNINGS and
505 NOTES to last. The order given above should
506 be reasonable for most purposes.
507
508
509 Finally, as a general note, try not to use an excessive
510 amount of markup. As documented here and in Pod::Man, you
511 can safely leave Perl variables, function names, man page
512 references, and the like unadorned by markup and the
513 POD translators will figure it out for you.
514 This makes it much easier to later edit the documentation.
515 Note that many existing translators (including this one
516 currently) will do the wrong thing with e-mail addresses or
517 URLs when wrapped in L
518
519
520 For additional information that may be more accurate for
521 your specific system, see either man(5) or
522 man(7) depending on your system manual section
523 numbering conventions.
524 !!SEE ALSO
525
526
527 Pod::Man, Pod::Parser, man(1), nroff(1),
528 troff(1), man(7)
529
530
531 The man page documenting the an macro set may be
532 man(5) instead of man(7) on your
533 system.
534 !!AUTHOR
535
536
537 Russ Allbery very''
538 heavily on the original __pod2man__ by Larry Wall and Tom
539 Christiansen. Large portions of this documentation,
540 particularly the sections on the anatomy of a proper man
541 page, are taken from the __pod2man__ documentation by
542 Tom.
543 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.