1PERLPOD(1)             Perl Programmers Reference Guide             PERLPOD(1)
2
3
4

NAME

6       perlpod - the Plain Old Documentation format
7

DESCRIPTION

9       Pod is a simple-to-use markup language used for writing documentation
10       for Perl, Perl programs, and Perl modules.
11
12       Translators are available for converting Pod to various formats like
13       plain text, HTML, man pages, and more.
14
15       Pod markup consists of three basic kinds of paragraphs: ordinary,
16       verbatim, and command.
17
18   Ordinary Paragraph
19       Most paragraphs in your documentation will be ordinary blocks of text,
20       like this one.  You can simply type in your text without any markup
21       whatsoever, and with just a blank line before and after.  When it gets
22       formatted, it will undergo minimal formatting, like being rewrapped,
23       probably put into a proportionally spaced font, and maybe even
24       justified.
25
26       You can use formatting codes in ordinary paragraphs, for bold, italic,
27       "code-style", hyperlinks, and more.  Such codes are explained in the
28       "Formatting Codes" section, below.
29
30   Verbatim Paragraph
31       Verbatim paragraphs are usually used for presenting a codeblock or
32       other text which does not require any special parsing or formatting,
33       and which shouldn't be wrapped.
34
35       A verbatim paragraph is distinguished by having its first character be
36       a space or a tab.  (And commonly, all its lines begin with spaces
37       and/or tabs.)  It should be reproduced exactly, with tabs assumed to be
38       on 8-column boundaries.  There are no special formatting codes, so you
39       can't italicize or anything like that.  A \ means \, and nothing else.
40
41   Command Paragraph
42       A command paragraph is used for special treatment of whole chunks of
43       text, usually as headings or parts of lists.
44
45       All command paragraphs (which are typically only one line long) start
46       with "=", followed by an identifier, followed by arbitrary text that
47       the command can use however it pleases.  Currently recognized commands
48       are
49
50           =pod
51           =head1 Heading Text
52           =head2 Heading Text
53           =head3 Heading Text
54           =head4 Heading Text
55           =over indentlevel
56           =item stuff
57           =back
58           =begin format
59           =end format
60           =for format text...
61           =encoding type
62           =cut
63
64       To explain them each in detail:
65
66       "=head1 Heading Text"
67       "=head2 Heading Text"
68       "=head3 Heading Text"
69       "=head4 Heading Text"
70           Head1 through head4 produce headings, head1 being the highest
71           level.  The text in the rest of this paragraph is the content of
72           the heading.  For example:
73
74             =head2 Object Attributes
75
76           The text "Object Attributes" comprises the heading there.  (Note
77           that head3 and head4 are recent additions, not supported in older
78           Pod translators.)  The text in these heading commands can use
79           formatting codes, as seen here:
80
81             =head2 Possible Values for C<$/>
82
83           Such commands are explained in the "Formatting Codes" section,
84           below.
85
86       "=over indentlevel"
87       "=item stuff..."
88       "=back"
89           Item, over, and back require a little more explanation:  "=over"
90           starts a region specifically for the generation of a list using
91           "=item" commands, or for indenting (groups of) normal paragraphs.
92           At the end of your list, use "=back" to end it.  The indentlevel
93           option to "=over" indicates how far over to indent, generally in
94           ems (where one em is the width of an "M" in the document's base
95           font) or roughly comparable units; if there is no indentlevel
96           option, it defaults to four.  (And some formatters may just ignore
97           whatever indentlevel you provide.)  In the stuff in "=item
98           stuff...", you may use formatting codes, as seen here:
99
100             =item Using C<$|> to Control Buffering
101
102           Such commands are explained in the "Formatting Codes" section,
103           below.
104
105           Note also that there are some basic rules to using "=over" ...
106           "=back" regions:
107
108           ·   Don't use "=item"s outside of an "=over" ... "=back" region.
109
110           ·   The first thing after the "=over" command should be an "=item",
111               unless there aren't going to be any items at all in this
112               "=over" ... "=back" region.
113
114           ·   Don't put "=headn" commands inside an "=over" ... "=back"
115               region.
116
117           ·   And perhaps most importantly, keep the items consistent: either
118               use "=item *" for all of them, to produce bullets; or use
119               "=item 1.", "=item 2.", etc., to produce numbered lists; or use
120               "=item foo", "=item bar", etc.--namely, things that look
121               nothing like bullets or numbers.
122
123               If you start with bullets or numbers, stick with them, as
124               formatters use the first "=item" type to decide how to format
125               the list.
126
127       "=cut"
128           To end a Pod block, use a blank line, then a line beginning with
129           "=cut", and a blank line after it.  This lets Perl (and the Pod
130           formatter) know that this is where Perl code is resuming.  (The
131           blank line before the "=cut" is not technically necessary, but many
132           older Pod processors require it.)
133
134       "=pod"
135           The "=pod" command by itself doesn't do much of anything, but it
136           signals to Perl (and Pod formatters) that a Pod block starts here.
137           A Pod block starts with any command paragraph, so a "=pod" command
138           is usually used just when you want to start a Pod block with an
139           ordinary paragraph or a verbatim paragraph.  For example:
140
141             =item stuff()
142
143             This function does stuff.
144
145             =cut
146
147             sub stuff {
148               ...
149             }
150
151             =pod
152
153             Remember to check its return value, as in:
154
155               stuff() || die "Couldn't do stuff!";
156
157             =cut
158
159       "=begin formatname"
160       "=end formatname"
161       "=for formatname text..."
162           For, begin, and end will let you have regions of text/code/data
163           that are not generally interpreted as normal Pod text, but are
164           passed directly to particular formatters, or are otherwise special.
165           A formatter that can use that format will use the region, otherwise
166           it will be completely ignored.
167
168           A command "=begin formatname", some paragraphs, and a command "=end
169           formatname", mean that the text/data in between is meant for
170           formatters that understand the special format called formatname.
171           For example,
172
173             =begin html
174
175             <hr> <img src="thang.png">
176             <p> This is a raw HTML paragraph </p>
177
178             =end html
179
180           The command "=for formatname text..."  specifies that the remainder
181           of just this paragraph (starting right after formatname) is in that
182           special format.
183
184             =for html <hr> <img src="thang.png">
185             <p> This is a raw HTML paragraph </p>
186
187           This means the same thing as the above "=begin html" ... "=end
188           html" region.
189
190           That is, with "=for", you can have only one paragraph's worth of
191           text (i.e., the text in "=foo targetname text..."), but with
192           "=begin targetname" ... "=end targetname", you can have any amount
193           of stuff in between.  (Note that there still must be a blank line
194           after the "=begin" command and a blank line before the "=end"
195           command.
196
197           Here are some examples of how to use these:
198
199             =begin html
200
201             <br>Figure 1.<br><IMG SRC="figure1.png"><br>
202
203             =end html
204
205             =begin text
206
207               ---------------
208               |  foo        |
209               |        bar  |
210               ---------------
211
212             ^^^^ Figure 1. ^^^^
213
214             =end text
215
216           Some format names that formatters currently are known to accept
217           include "roff", "man", "latex", "tex", "text", and "html".  (Some
218           formatters will treat some of these as synonyms.)
219
220           A format name of "comment" is common for just making notes
221           (presumably to yourself) that won't appear in any formatted version
222           of the Pod document:
223
224             =for comment
225             Make sure that all the available options are documented!
226
227           Some formatnames will require a leading colon (as in "=for
228           :formatname", or "=begin :formatname" ... "=end :formatname"), to
229           signal that the text is not raw data, but instead is Pod text
230           (i.e., possibly containing formatting codes) that's just not for
231           normal formatting (e.g., may not be a normal-use paragraph, but
232           might be for formatting as a footnote).
233
234       "=encoding encodingname"
235           This command is used for declaring the encoding of a document.
236           Most users won't need this; but if your encoding isn't US-ASCII or
237           Latin-1, then put a "=encoding encodingname" command early in the
238           document so that pod formatters will know how to decode the
239           document.  For encodingname, use a name recognized by the
240           Encode::Supported module.  Examples:
241
242             =encoding utf8
243
244             =encoding koi8-r
245
246             =encoding ShiftJIS
247
248             =encoding big5
249
250       "=encoding" affects the whole document, and must occur only once.
251
252       And don't forget, when using any other command, that the command lasts
253       up until the end of its paragraph, not its line.  So in the examples
254       below, you can see that every command needs the blank line after it, to
255       end its paragraph.
256
257       Some examples of lists include:
258
259         =over
260
261         =item *
262
263         First item
264
265         =item *
266
267         Second item
268
269         =back
270
271         =over
272
273         =item Foo()
274
275         Description of Foo function
276
277         =item Bar()
278
279         Description of Bar function
280
281         =back
282
283   Formatting Codes
284       In ordinary paragraphs and in some command paragraphs, various
285       formatting codes (a.k.a. "interior sequences") can be used:
286
287       "I<text>" -- italic text
288           Used for emphasis (""be I<careful!>"") and parameters (""redo
289           I<LABEL>"")
290
291       "B<text>" -- bold text
292           Used for switches (""perl's B<-n> switch""), programs (""some
293           systems provide a B<chfn> for that""), emphasis (""be
294           B<careful!>""), and so on (""and that feature is known as
295           B<autovivification>"").
296
297       "C<code>" -- code text
298           Renders code in a typewriter font, or gives some other indication
299           that this represents program text (""C<gmtime($^T)>"") or some
300           other form of computerese (""C<drwxr-xr-x>"").
301
302       "L<name>" -- a hyperlink
303           There are various syntaxes, listed below.  In the syntaxes given,
304           "text", "name", and "section" cannot contain the characters '/' and
305           '|'; and any '<' or '>' should be matched.
306
307           ·   "L<name>"
308
309               Link to a Perl manual page (e.g., "L<Net::Ping>").  Note that
310               "name" should not contain spaces.  This syntax is also
311               occasionally used for references to Unix man pages, as in
312               "L<crontab(5)>".
313
314           ·   "L<name/"sec">" or "L<name/sec>"
315
316               Link to a section in other manual page.  E.g., "L<perlsyn/"For
317               Loops">"
318
319           ·   "L</"sec">" or "L</sec>"
320
321               Link to a section in this manual page.  E.g., "L</"Object
322               Methods">"
323
324           A section is started by the named heading or item.  For example,
325           "L<perlvar/$.>" or "L<perlvar/"$.">" both link to the section
326           started by ""=item $."" in perlvar.  And "L<perlsyn/For Loops>" or
327           "L<perlsyn/"For Loops">" both link to the section started by
328           ""=head2 For Loops"" in perlsyn.
329
330           To control what text is used for display, you use ""L<text|...>"",
331           as in:
332
333           ·   "L<text|name>"
334
335               Link this text to that manual page.  E.g., "L<Perl Error
336               Messages|perldiag>"
337
338           ·   "L<text|name/"sec">" or "L<text|name/sec>"
339
340               Link this text to that section in that manual page.  E.g.,
341               "L<postfix "if"|perlsyn/"Statement Modifiers">"
342
343           ·   "L<text|/"sec">" or "L<text|/sec>" or "L<text|"sec">"
344
345               Link this text to that section in this manual page.  E.g.,
346               "L<the various attributes|/"Member Data">"
347
348           Or you can link to a web page:
349
350           ·   "L<scheme:...>"
351
352               "L<text|scheme:...>"
353
354               Links to an absolute URL.  For example,
355               "L<http://www.perl.org/>" or "L<The Perl Home
356               Page|http://www.perl.org/>".
357
358       "E<escape>" -- a character escape
359           Very similar to HTML/XML "&foo;" "entity references":
360
361           ·   "E<lt>" -- a literal < (less than)
362
363           ·   "E<gt>" -- a literal > (greater than)
364
365           ·   "E<verbar>" -- a literal | (vertical bar)
366
367           ·   "E<sol>" -- a literal / (solidus)
368
369               The above four are optional except in other formatting codes,
370               notably "L<...>", and when preceded by a capital letter.
371
372           ·   "E<htmlname>"
373
374               Some non-numeric HTML entity name, such as "E<eacute>", meaning
375               the same thing as "&eacute;" in HTML -- i.e., a lowercase e
376               with an acute (/-shaped) accent.
377
378           ·   "E<number>"
379
380               The ASCII/Latin-1/Unicode character with that number.  A
381               leading "0x" means that number is hex, as in "E<0x201E>".  A
382               leading "0" means that number is octal, as in "E<075>".
383               Otherwise number is interpreted as being in decimal, as in
384               "E<181>".
385
386               Note that older Pod formatters might not recognize octal or hex
387               numeric escapes, and that many formatters cannot reliably
388               render characters above 255.  (Some formatters may even have to
389               use compromised renderings of Latin-1 characters, like
390               rendering "E<eacute>" as just a plain "e".)
391
392       "F<filename>" -- used for filenames
393           Typically displayed in italics.  Example: ""F<.cshrc>""
394
395       "S<text>" -- text contains non-breaking spaces
396           This means that the words in text should not be broken across
397           lines.  Example: "S<$x ? $y : $z>".
398
399       "X<topic name>" -- an index entry
400           This is ignored by most formatters, but some may use it for
401           building indexes.  It always renders as empty-string.  Example:
402           "X<absolutizing relative URLs>"
403
404       "Z<>" -- a null (zero-effect) formatting code
405           This is rarely used.  It's one way to get around using an E<...>
406           code sometimes.  For example, instead of ""NE<lt>3"" (for "N<3")
407           you could write ""NZ<><3"" (the "Z<>" breaks up the "N" and the "<"
408           so they can't be considered the part of a (fictitious) "N<...>"
409           code.
410
411       Most of the time, you will need only a single set of angle brackets to
412       delimit the beginning and end of formatting codes.  However, sometimes
413       you will want to put a real right angle bracket (a greater-than sign,
414       '>') inside of a formatting code.  This is particularly common when
415       using a formatting code to provide a different font-type for a snippet
416       of code.  As with all things in Perl, there is more than one way to do
417       it.  One way is to simply escape the closing bracket using an "E" code:
418
419           C<$a E<lt>=E<gt> $b>
420
421       This will produce: ""$a <=> $b""
422
423       A more readable, and perhaps more "plain" way is to use an alternate
424       set of delimiters that doesn't require a single ">" to be escaped.
425       Doubled angle brackets ("<<" and ">>") may be used if and only if there
426       is whitespace right after the opening delimiter and whitespace right
427       before the closing delimiter!  For example, the following will do the
428       trick:
429
430           C<< $a <=> $b >>
431
432       In fact, you can use as many repeated angle-brackets as you like so
433       long as you have the same number of them in the opening and closing
434       delimiters, and make sure that whitespace immediately follows the last
435       '<' of the opening delimiter, and immediately precedes the first '>' of
436       the closing delimiter.  (The whitespace is ignored.)  So the following
437       will also work:
438
439           C<<< $a <=> $b >>>
440           C<<<<  $a <=> $b     >>>>
441
442       And they all mean exactly the same as this:
443
444           C<$a E<lt>=E<gt> $b>
445
446       The multiple-bracket form does not affect the interpretation of the
447       contents of the formatting code, only how it must end.  That means that
448       the examples above are also exactly the same as this:
449
450           C<< $a E<lt>=E<gt> $b >>
451
452       As a further example, this means that if you wanted to put these bits
453       of code in "C" (code) style:
454
455           open(X, ">>thing.dat") || die $!
456           $foo->bar();
457
458       you could do it like so:
459
460           C<<< open(X, ">>thing.dat") || die $! >>>
461           C<< $foo->bar(); >>
462
463       which is presumably easier to read than the old way:
464
465           C<open(X, "E<gt>E<gt>thing.dat") || die $!>
466           C<$foo-E<gt>bar();>
467
468       This is currently supported by pod2text (Pod::Text), pod2man
469       (Pod::Man), and any other pod2xxx or Pod::Xxxx translators that use
470       Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
471
472   The Intent
473       The intent is simplicity of use, not power of expression.  Paragraphs
474       look like paragraphs (block format), so that they stand out visually,
475       and so that I could run them through "fmt" easily to reformat them
476       (that's F7 in my version of vi, or Esc Q in my version of emacs).  I
477       wanted the translator to always leave the "'" and "`" and """ quotes
478       alone, in verbatim mode, so I could slurp in a working program, shift
479       it over four spaces, and have it print out, er, verbatim.  And
480       presumably in a monospace font.
481
482       The Pod format is not necessarily sufficient for writing a book.  Pod
483       is just meant to be an idiot-proof common source for nroff, HTML, TeX,
484       and other markup languages, as used for online documentation.
485       Translators exist for pod2text, pod2html, pod2man (that's for nroff(1)
486       and troff(1)), pod2latex, and pod2fm.  Various others are available in
487       CPAN.
488
489   Embedding Pods in Perl Modules
490       You can embed Pod documentation in your Perl modules and scripts.
491       Start your documentation with an empty line, a "=head1" command at the
492       beginning, and end it with a "=cut" command and an empty line.  Perl
493       will ignore the Pod text.  See any of the supplied library modules for
494       examples.  If you're going to put your Pod at the end of the file, and
495       you're using an __END__ or __DATA__ cut mark, make sure to put an empty
496       line there before the first Pod command.
497
498         __END__
499
500         =head1 NAME
501
502         Time::Local - efficiently compute time from local and GMT time
503
504       Without that empty line before the "=head1", many translators wouldn't
505       have recognized the "=head1" as starting a Pod block.
506
507   Hints for Writing Pod
508       ·
509
510
511           The podchecker command is provided for checking Pod syntax for
512           errors and warnings.  For example, it checks for completely blank
513           lines in Pod blocks and for unknown commands and formatting codes.
514           You should still also pass your document through one or more
515           translators and proofread the result, or print out the result and
516           proofread that.  Some of the problems found may be bugs in the
517           translators, which you may or may not wish to work around.
518
519       ·   If you're more familiar with writing in HTML than with writing in
520           Pod, you can try your hand at writing documentation in simple HTML,
521           and converting it to Pod with the experimental Pod::HTML2Pod
522           module, (available in CPAN), and looking at the resulting code.
523           The experimental Pod::PXML module in CPAN might also be useful.
524
525       ·   Many older Pod translators require the lines before every Pod
526           command and after every Pod command (including "=cut"!) to be a
527           blank line.  Having something like this:
528
529            # - - - - - - - - - - - -
530            =item $firecracker->boom()
531
532            This noisily detonates the firecracker object.
533            =cut
534            sub boom {
535            ...
536
537           ...will make such Pod translators completely fail to see the Pod
538           block at all.
539
540           Instead, have it like this:
541
542            # - - - - - - - - - - - -
543
544            =item $firecracker->boom()
545
546            This noisily detonates the firecracker object.
547
548            =cut
549
550            sub boom {
551            ...
552
553       ·   Some older Pod translators require paragraphs (including command
554           paragraphs like "=head2 Functions") to be separated by completely
555           empty lines.  If you have an apparently empty line with some spaces
556           on it, this might not count as a separator for those translators,
557           and that could cause odd formatting.
558
559       ·   Older translators might add wording around an L<> link, so that
560           "L<Foo::Bar>" may become "the Foo::Bar manpage", for example.  So
561           you shouldn't write things like "the L<foo> documentation", if you
562           want the translated document to read sensibly.  Instead, write "the
563           L<Foo::Bar|Foo::Bar> documentation" or "L<the Foo::Bar
564           documentation|Foo::Bar>", to control how the link comes out.
565
566       ·   Going past the 70th column in a verbatim block might be
567           ungracefully wrapped by some formatters.
568

SEE ALSO

570       perlpodspec, "PODs: Embedded Documentation" in perlsyn, perlnewmod,
571       perldoc, pod2html, pod2man, podchecker.
572

AUTHOR

574       Larry Wall, Sean M. Burke
575
576
577
578perl v5.16.3                      2013-03-04                        PERLPOD(1)
Impressum