1PERLPOD(1) Perl Programmers Reference Guide PERLPOD(1)
2
6 perlpod - the Plain Old Documentation format
7
9 Pod is a simple-to-use markup language used for writing documentation
10 for Perl, Perl programs, and Perl modules.
11 Translators are available for converting Pod to various formats like
13 plain text, HTML, man pages, and more.
14 Pod markup consists of three basic kinds of paragraphs: ordinary, ver‐
16 batim, and command.
17 Ordinary Paragraph
19 Most paragraphs in your documentation will be ordinary blocks of text,
21 like this one. You can simply type in your text without any markup
22 whatsoever, and with just a blank line before and after. When it gets
23 formatted, it will undergo minimal formatting, like being rewrapped,
24 probably put into a proportionally spaced font, and maybe even justi‐
25 fied.
26 You can use formatting codes in ordinary paragraphs, for bold, italic,
28 "code-style", hyperlinks, and more. Such codes are explained in the
29 "Formatting Codes" section, below.
30 Verbatim Paragraph
32 Verbatim paragraphs are usually used for presenting a codeblock or
34 other text which does not require any special parsing or formatting,
35 and which shouldn't be wrapped.
36 A verbatim paragraph is distinguished by having its first character be
38 a space or a tab. (And commonly, all its lines begin with spaces
39 and/or tabs.) It should be reproduced exactly, with tabs assumed to be
40 on 8-column boundaries. There are no special formatting codes, so you
41 can't italicize or anything like that. A \ means \, and nothing else.
42 Command Paragraph
44 A command paragraph is used for special treatment of whole chunks of
46 text, usually as headings or parts of lists.
47 All command paragraphs (which are typically only one line long) start
49 with "=", followed by an identifier, followed by arbitrary text that
50 the command can use however it pleases. Currently recognized commands
51 are
52 =pod
54 =head1 Heading Text
55 =head2 Heading Text
56 =head3 Heading Text
57 =head4 Heading Text
58 =over indentlevel
59 =item stuff
60 =back
61 =begin format
62 =end format
63 =for format text...
64 =encoding type
65 =cut
66 To explain them each in detail:
68 "=head1 Heading Text"
70 "=head2 Heading Text"
71 "=head3 Heading Text"
72 "=head4 Heading Text"
73 Head1 through head4 produce headings, head1 being the highest
74 level. The text in the rest of this paragraph is the content of
75 the heading. For example:
76 =head2 Object Attributes
78 The text "Object Attributes" comprises the heading there. (Note
80 that head3 and head4 are recent additions, not supported in older
81 Pod translators.) The text in these heading commands can use for‐
82 matting codes, as seen here:
83 =head2 Possible Values for C<$/>
85 Such commands are explained in the "Formatting Codes" section,
87 below.
88 "=over indentlevel"
90 "=item stuff..."
91 "=back"
92 Item, over, and back require a little more explanation: "=over"
93 starts a region specifically for the generation of a list using
94 "=item" commands, or for indenting (groups of) normal paragraphs.
95 At the end of your list, use "=back" to end it. The indentlevel
96 option to "=over" indicates how far over to indent, generally in
97 ems (where one em is the width of an "M" in the document's base
98 font) or roughly comparable units; if there is no indentlevel
99 option, it defaults to four. (And some formatters may just ignore
100 whatever indentlevel you provide.) In the stuff in "=item
101 stuff...", you may use formatting codes, as seen here:
102 =item Using C<$⎪> to Control Buffering
104 Such commands are explained in the "Formatting Codes" section,
106 below.
107 Note also that there are some basic rules to using "=over" ...
109 "=back" regions:
110 * Don't use "=item"s outside of an "=over" ... "=back" region.
112 * The first thing after the "=over" command should be an "=item",
114 unless there aren't going to be any items at all in this
115 "=over" ... "=back" region.
116 * Don't put "=headn" commands inside an "=over" ... "=back"
118 region.
119 * And perhaps most importantly, keep the items consistent: either
121 use "=item *" for all of them, to produce bullets; or use
122 "=item 1.", "=item 2.", etc., to produce numbered lists; or use
123 "=item foo", "=item bar", etc. -- namely, things that look
124 nothing like bullets or numbers.
125 If you start with bullets or numbers, stick with them, as for‐
127 matters use the first "=item" type to decide how to format the
128 list.
129 "=cut"
131 To end a Pod block, use a blank line, then a line beginning with
132 "=cut", and a blank line after it. This lets Perl (and the Pod
133 formatter) know that this is where Perl code is resuming. (The
134 blank line before the "=cut" is not technically necessary, but many
135 older Pod processors require it.)
136 "=pod"
138 The "=pod" command by itself doesn't do much of anything, but it
139 signals to Perl (and Pod formatters) that a Pod block starts here.
140 A Pod block starts with any command paragraph, so a "=pod" command
141 is usually used just when you want to start a Pod block with an
142 ordinary paragraph or a verbatim paragraph. For example:
143 =item stuff()
145 This function does stuff.
147 =cut
149 sub stuff {
151 ...
152 }
153 =pod
155 Remember to check its return value, as in:
157 stuff() ⎪⎪ die "Couldn't do stuff!";
159 =cut
161 "=begin formatname"
163 "=end formatname"
164 "=for formatname text..."
165 For, begin, and end will let you have regions of text/code/data
166 that are not generally interpreted as normal Pod text, but are
167 passed directly to particular formatters, or are otherwise special.
168 A formatter that can use that format will use the region, otherwise
169 it will be completely ignored.
170 A command "=begin formatname", some paragraphs, and a command "=end
172 formatname", mean that the text/data inbetween is meant for format‐
173 ters that understand the special format called formatname. For
174 example,
175 =begin html
177 <hr> <img src="thang.png">
179 <p> This is a raw HTML paragraph </p>
180 =end html
182 The command "=for formatname text..." specifies that the remainder
184 of just this paragraph (starting right after formatname) is in that
185 special format.
186 =for html <hr> <img src="thang.png">
188 <p> This is a raw HTML paragraph </p>
189 This means the same thing as the above "=begin html" ... "=end
191 html" region.
192 That is, with "=for", you can have only one paragraph's worth of
194 text (i.e., the text in "=foo targetname text..."), but with
195 "=begin targetname" ... "=end targetname", you can have any amount
196 of stuff inbetween. (Note that there still must be a blank line
197 after the "=begin" command and a blank line before the "=end" com‐
198 mand.
199 Here are some examples of how to use these:
201 =begin html
203 <br>Figure 1.<br><IMG SRC="figure1.png"><br>
205 =end html
207 =begin text
209 ---------------
211 ⎪ foo ⎪
212 ⎪ bar ⎪
213 ---------------
214 ^^^^ Figure 1. ^^^^
216 =end text
218 Some format names that formatters currently are known to accept
220 include "roff", "man", "latex", "tex", "text", and "html". (Some
221 formatters will treat some of these as synonyms.)
222 A format name of "comment" is common for just making notes (presum‐
224 ably to yourself) that won't appear in any formatted version of the
225 Pod document:
226 =for comment
228 Make sure that all the available options are documented!
229 Some formatnames will require a leading colon (as in "=for :format‐
231 name", or "=begin :formatname" ... "=end :formatname"), to signal
232 that the text is not raw data, but instead is Pod text (i.e., pos‐
233 sibly containing formatting codes) that's just not for normal for‐
234 matting (e.g., may not be a normal-use paragraph, but might be for
235 formatting as a footnote).
236 "=encoding encodingname"
238 This command is used for declaring the encoding of a document.
239 Most users won't need this; but if your encoding isn't US-ASCII or
240 Latin-1, then put a "=encoding encodingname" command early in the
241 document so that pod formatters will know how to decode the docu‐
242 ment. For encodingname, use a name recognized by the Encode::Sup‐
243 ported module. Examples:
244 =encoding utf8
246 =encoding koi8-r
248 =encoding ShiftJIS
250 =encoding big5
252 And don't forget, when using any command, that the command lasts up
254 until the end of its paragraph, not its line. So in the examples
255 below, you can see that every command needs the blank line after it, to
256 end its paragraph.
257 Some examples of lists include:
259 =over
261 =item *
263 First item
265 =item *
267 Second item
269 =back
271 =over
273 =item Foo()
275 Description of Foo function
277 =item Bar()
279 Description of Bar function
281 =back
283 Formatting Codes
285 In ordinary paragraphs and in some command paragraphs, various format‐
287 ting codes (a.k.a. "interior sequences") can be used:
288 "I<text>" -- italic text
290 Used for emphasis (""be I<careful!>"") and parameters (""redo
291 I<LABEL>"")
292 "B<text>" -- bold text
294 Used for switches (""perl's B<-n> switch""), programs (""some sys‐
295 tems provide a B<chfn> for that""), emphasis (""be B<careful!>""),
296 and so on (""and that feature is known as B<autovivification>"").
297 "C<code>" -- code text
299 Renders code in a typewriter font, or gives some other indication
300 that this represents program text (""C<gmtime($^T)>"") or some
301 other form of computerese (""C<drwxr-xr-x>"").
302 "L<name>" -- a hyperlink
304 There are various syntaxes, listed below. In the syntaxes given,
305 "text", "name", and "section" cannot contain the characters '/' and
306 '⎪'; and any '<' or '>' should be matched.
307 * "L<name>"
309 Link to a Perl manual page (e.g., "L<Net::Ping>"). Note that
311 "name" should not contain spaces. This syntax is also occa‐
312 sionally used for references to UNIX man pages, as in
313 "L<crontab(5)>".
314 * "L<name/"sec">" or "L<name/sec>"
316 Link to a section in other manual page. E.g., "L<perlsyn/"For
318 Loops">"
319 * "L</"sec">" or "L</sec>" or "L<"sec">"
321 Link to a section in this manual page. E.g., "L</"Object Meth‐
323 ods">"
324 A section is started by the named heading or item. For example,
326 "L<perlvar/$.>" or "L<perlvar/"$.">" both link to the section
327 started by ""=item $."" in perlvar. And "L<perlsyn/For Loops>" or
328 "L<perlsyn/"For Loops">" both link to the section started by
329 ""=head2 For Loops"" in perlsyn.
330 To control what text is used for display, you use ""L<text⎪...>"",
332 as in:
333 * "L<text⎪name>"
335 Link this text to that manual page. E.g., "L<Perl Error Mes‐
337 sages⎪perldiag>"
338 * "L<text⎪name/"sec">" or "L<text⎪name/sec>"
340 Link this text to that section in that manual page. E.g.,
342 "L<SWITCH statements⎪perlsyn/"Basic BLOCKs and Switch State‐
343 ments">"
344 * "L<text⎪/"sec">" or "L<text⎪/sec>" or "L<text⎪"sec">"
346 Link this text to that section in this manual page. E.g.,
348 "L<the various attributes⎪/"Member Data">"
349 Or you can link to a web page:
351 * "L<scheme:...>"
353 Links to an absolute URL. For example,
355 "L<http://www.perl.org/>". But note that there is no corre‐
356 sponding "L<text⎪scheme:...>" syntax, for various reasons.
357 "E<escape>" -- a character escape
359 Very similar to HTML/XML "&foo;" "entity references":
360 * "E<lt>" -- a literal < (less than)
362 * "E<gt>" -- a literal > (greater than)
364 * "E<verbar>" -- a literal ⎪ (vertical bar)
366 * "E<sol>" = a literal / (solidus)
368 The above four are optional except in other formatting codes,
370 notably "L<...>", and when preceded by a capital letter.
371 * "E<htmlname>"
373 Some non-numeric HTML entity name, such as "E<eacute>", meaning
375 the same thing as "é" in HTML -- i.e., a lowercase e
376 with an acute (/-shaped) accent.
377 * "E<number>"
379 The ASCII/Latin-1/Unicode character with that number. A lead‐
381 ing "0x" means that number is hex, as in "E<0x201E>". A lead‐
382 ing "0" means that number is octal, as in "E<075>". Otherwise
383 number is interpreted as being in decimal, as in "E<181>".
384 Note that older Pod formatters might not recognize octal or hex
386 numeric escapes, and that many formatters cannot reliably ren‐
387 der characters above 255. (Some formatters may even have to
388 use compromised renderings of Latin-1 characters, like render‐
389 ing "E<eacute>" as just a plain "e".)
390 "F<filename>" -- used for filenames
392 Typically displayed in italics. Example: ""F<.cshrc>""
393 "S<text>" -- text contains non-breaking spaces
395 This means that the words in text should not be broken across
396 lines. Example: "S<$x ? $y : $z>".
397 "X<topic name>" -- an index entry
399 This is ignored by most formatters, but some may use it for build‐
400 ing indexes. It always renders as empty-string. Example: "X<abso‐
401 lutizing relative URLs>"
402 "Z<>" -- a null (zero-effect) formatting code
404 This is rarely used. It's one way to get around using an E<...>
405 code sometimes. For example, instead of ""NE<lt>3"" (for "N<3")
406 you could write ""NZ<><3"" (the "Z<>" breaks up the "N" and the "<"
407 so they can't be considered the part of a (fictitious) "N<...>"
408 code.
409 Most of the time, you will need only a single set of angle brackets to
411 delimit the beginning and end of formatting codes. However, sometimes
412 you will want to put a real right angle bracket (a greater-than sign,
413 '>') inside of a formatting code. This is particularly common when
414 using a formatting code to provide a different font-type for a snippet
415 of code. As with all things in Perl, there is more than one way to do
416 it. One way is to simply escape the closing bracket using an "E" code:
417 C<$a E<lt>=E<gt> $b>
419 This will produce: ""$a <=> $b""
421 A more readable, and perhaps more "plain" way is to use an alternate
423 set of delimiters that doesn't require a single ">" to be escaped.
424 With the Pod formatters that are standard starting with perl5.5.660,
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 C<< $a <=> $b >>
431 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 C<<< $a <=> $b >>>
440 C<<<< $a <=> $b >>>>
441 And they all mean exactly the same as this:
443 C<$a E<lt>=E<gt> $b>
445 As a further example, this means that if you wanted to put these bits
447 of code in "C" (code) style:
448 open(X, ">>thing.dat") ⎪⎪ die $!
450 $foo->bar();
451 you could do it like so:
453 C<<< open(X, ">>thing.dat") ⎪⎪ die $! >>>
455 C<< $foo->bar(); >>
456 which is presumably easier to read than the old way:
458 C<open(X, "E<gt>E<gt>thing.dat") ⎪⎪ die $!>
460 C<$foo-E<gt>bar();>
461 This is currently supported by pod2text (Pod::Text), pod2man
463 (Pod::Man), and any other pod2xxx or Pod::Xxxx translators that use
464 Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
465 The Intent
467 The intent is simplicity of use, not power of expression. Paragraphs
469 look like paragraphs (block format), so that they stand out visually,
470 and so that I could run them through "fmt" easily to reformat them
471 (that's F7 in my version of vi, or Esc Q in my version of emacs). I
472 wanted the translator to always leave the "'" and "`" and """ quotes
473 alone, in verbatim mode, so I could slurp in a working program, shift
474 it over four spaces, and have it print out, er, verbatim. And presum‐
475 ably in a monospace font.
476 The Pod format is not necessarily sufficient for writing a book. Pod
478 is just meant to be an idiot-proof common source for nroff, HTML, TeX,
479 and other markup languages, as used for online documentation. Transla‐
480 tors exist for pod2text, pod2html, pod2man (that's for nroff(1) and
481 troff(1)), pod2latex, and pod2fm. Various others are available in
482 CPAN.
483 Embedding Pods in Perl Modules
485 You can embed Pod documentation in your Perl modules and scripts.
487 Start your documentation with an empty line, a "=head1" command at the
488 beginning, and end it with a "=cut" command and an empty line. Perl
489 will ignore the Pod text. See any of the supplied library modules for
490 examples. If you're going to put your Pod at the end of the file, and
491 you're using an __END__ or __DATA__ cut mark, make sure to put an empty
492 line there before the first Pod command.
493 __END__
495 =head1 NAME
497 Time::Local - efficiently compute time from local and GMT time
499 Without that empty line before the "=head1", many translators wouldn't
501 have recognized the "=head1" as starting a Pod block.
502 Hints for Writing Pod
504 · The podchecker command is provided for checking Pod syntax for
506 errors and warnings. For example, it checks for completely blank
507 lines in Pod blocks and for unknown commands and formatting codes.
508 You should still also pass your document through one or more trans‐
509 lators and proofread the result, or print out the result and proof‐
510 read that. Some of the problems found may be bugs in the transla‐
511 tors, which you may or may not wish to work around.
512 · If you're more familiar with writing in HTML than with writing in
514 Pod, you can try your hand at writing documentation in simple HTML,
515 and converting it to Pod with the experimental Pod::HTML2Pod mod‐
516 ule, (available in CPAN), and looking at the resulting code. The
517 experimental Pod::PXML module in CPAN might also be useful.
518 · Many older Pod translators require the lines before every Pod com‐
520 mand and after every Pod command (including "=cut"!) to be a blank
521 line. Having something like this:
522 # - - - - - - - - - - - -
524 =item $firecracker->boom()
525 This noisily detonates the firecracker object.
527 =cut
528 sub boom {
529 ...
530 ...will make such Pod translators completely fail to see the Pod
532 block at all.
533 Instead, have it like this:
535 # - - - - - - - - - - - -
537 =item $firecracker->boom()
539 This noisily detonates the firecracker object.
541 =cut
543 sub boom {
545 ...
546 · Some older Pod translators require paragraphs (including command
548 paragraphs like "=head2 Functions") to be separated by completely
549 empty lines. If you have an apparently empty line with some spaces
550 on it, this might not count as a separator for those translators,
551 and that could cause odd formatting.
552 · Older translators might add wording around an L<> link, so that
554 "L<Foo::Bar>" may become "the Foo::Bar manpage", for example. So
555 you shouldn't write things like "the L<foo> documentation", if you
556 want the translated document to read sensibly -- instead write "the
557 L<Foo::Bar⎪Foo::Bar> documentation" or "L<the Foo::Bar documenta‐
558 tion⎪Foo::Bar>", to control how the link comes out.
559 · Going past the 70th column in a verbatim block might be ungrace‐
561 fully wrapped by some formatters.
562
564 perlpodspec, "PODs: Embedded Documentation" in perlsyn, perlnewmod,
565 perldoc, pod2html, pod2man, podchecker.
566
568 Larry Wall, Sean M. Burke
569perl v5.8.8 2006-01-07 PERLPOD(1)