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,
16 verbatim, and command.
17 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 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 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 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 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 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 =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 To explain them each in detail:
65 "=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 =head2 Object Attributes
75 The text "Object Attributes" comprises the heading there. The text
77 in these heading commands can use formatting codes, as seen here:
78 =head2 Possible Values for C<$/>
80 Such commands are explained in the "Formatting Codes" section,
82 below.
83 "=over indentlevel"
85 "=item stuff..."
86 "=back"
87 Item, over, and back require a little more explanation: "=over"
88 starts a region specifically for the generation of a list using
89 "=item" commands, or for indenting (groups of) normal paragraphs.
90 At the end of your list, use "=back" to end it. The indentlevel
91 option to "=over" indicates how far over to indent, generally in
92 ems (where one em is the width of an "M" in the document's base
93 font) or roughly comparable units; if there is no indentlevel
94 option, it defaults to four. (And some formatters may just ignore
95 whatever indentlevel you provide.) In the stuff in "=item
96 stuff...", you may use formatting codes, as seen here:
97 =item Using C<$|> to Control Buffering
99 Such commands are explained in the "Formatting Codes" section,
101 below.
102 Note also that there are some basic rules to using "=over" ...
104 "=back" regions:
105 • Don't use "=item"s outside of an "=over" ... "=back" region.
107 • The first thing after the "=over" command should be an "=item",
109 unless there aren't going to be any items at all in this
110 "=over" ... "=back" region.
111 • Don't put "=headn" commands inside an "=over" ... "=back"
113 region.
114 • And perhaps most importantly, keep the items consistent: either
116 use "=item *" for all of them, to produce bullets; or use
117 "=item 1.", "=item 2.", etc., to produce numbered lists; or use
118 "=item foo", "=item bar", etc.--namely, things that look
119 nothing like bullets or numbers. (If you have a list that
120 contains both: 1) things that don't look like bullets nor
121 numbers, plus 2) things that do, you should preface the
122 bullet- or number-like items with "Z<>". See Z<> below for an
123 example.)
124 If you start with bullets or numbers, stick with them, as
126 formatters use the first "=item" type to decide how to format
127 the list.
128 "=cut"
130 To end a Pod block, use a blank line, then a line beginning with
131 "=cut", and a blank line after it. This lets Perl (and the Pod
132 formatter) know that this is where Perl code is resuming. (The
133 blank line before the "=cut" is not technically necessary, but many
134 older Pod processors require it.)
135 "=pod"
137 The "=pod" command by itself doesn't do much of anything, but it
138 signals to Perl (and Pod formatters) that a Pod block starts here.
139 A Pod block starts with any command paragraph, so a "=pod" command
140 is usually used just when you want to start a Pod block with an
141 ordinary paragraph or a verbatim paragraph. For example:
142 =item stuff()
144 This function does stuff.
146 =cut
148 sub stuff {
150 ...
151 }
152 =pod
154 Remember to check its return value, as in:
156 stuff() || die "Couldn't do stuff!";
158 =cut
160 "=begin formatname"
162 "=end formatname"
163 "=for formatname text..."
164 For, begin, and end will let you have regions of text/code/data
165 that are not generally interpreted as normal Pod text, but are
166 passed directly to particular formatters, or are otherwise special.
167 A formatter that can use that format will use the region, otherwise
168 it will be completely ignored.
169 A command "=begin formatname", some paragraphs, and a command "=end
171 formatname", mean that the text/data in between is meant for
172 formatters that understand the special format called formatname.
173 For example,
174 =begin html
176 <hr> <img src="thang.png">
178 <p> This is a raw HTML paragraph </p>
179 =end html
181 The command "=for formatname text..." specifies that the remainder
183 of just this paragraph (starting right after formatname) is in that
184 special format.
185 =for html <hr> <img src="thang.png">
187 <p> This is a raw HTML paragraph </p>
188 This means the same thing as the above "=begin html" ... "=end
190 html" region.
191 That is, with "=for", you can have only one paragraph's worth of
193 text (i.e., the text in "=foo targetname text..."), but with
194 "=begin targetname" ... "=end targetname", you can have any amount
195 of stuff in between. (Note that there still must be a blank line
196 after the "=begin" command and a blank line before the "=end"
197 command.)
198 Here are some examples of how to use these:
200 =begin html
202 <br>Figure 1.<br><IMG SRC="figure1.png"><br>
204 =end html
206 =begin text
208 ---------------
210 | foo |
211 | bar |
212 ---------------
213 ^^^^ Figure 1. ^^^^
215 =end text
217 Some format names that formatters currently are known to accept
219 include "roff", "man", "latex", "tex", "text", and "html". (Some
220 formatters will treat some of these as synonyms.)
221 A format name of "comment" is common for just making notes
223 (presumably to yourself) that won't appear in any formatted version
224 of the Pod document:
225 =for comment
227 Make sure that all the available options are documented!
228 Some formatnames will require a leading colon (as in "=for
230 :formatname", or "=begin :formatname" ... "=end :formatname"), to
231 signal that the text is not raw data, but instead is Pod text
232 (i.e., possibly containing formatting codes) that's just not for
233 normal formatting (e.g., may not be a normal-use paragraph, but
234 might be for formatting as a footnote).
235 "=encoding encodingname"
237 This command is used for declaring the encoding of a document.
238 Most users won't need this; but if your encoding isn't US-ASCII,
239 then put a "=encoding encodingname" command very early in the
240 document so that pod formatters will know how to decode the
241 document. For encodingname, use a name recognized by the
242 Encode::Supported module. Some pod formatters may try to guess
243 between a Latin-1 or CP-1252 versus UTF-8 encoding, but they may
244 guess wrong. It's best to be explicit if you use anything besides
245 strict ASCII. Examples:
246 =encoding latin1
248 =encoding utf8
250 =encoding koi8-r
252 =encoding ShiftJIS
254 =encoding big5
256 "=encoding" affects the whole document, and must occur only once.
258 And don't forget, all commands but "=encoding" last up until the end of
260 its paragraph, not its line. So in the examples below, you can see
261 that every command needs the blank line after it, to end its paragraph.
262 (And some older Pod translators may require the "=encoding" line to
263 have a following blank line as well, even though it should be legal to
264 omit.)
265 Some examples of lists include:
267 =over
269 =item *
271 First item
273 =item *
275 Second item
277 =back
279 =over
281 =item Foo()
283 Description of Foo function
285 =item Bar()
287 Description of Bar function
289 =back
291 Formatting Codes
293 In ordinary paragraphs and in some command paragraphs, various
294 formatting codes (a.k.a. "interior sequences") can be used:
295 "I<text>" -- italic text
297 Used for emphasis (""be I<careful!>"") and parameters (""redo
298 I<LABEL>"")
299 "B<text>" -- bold text
301 Used for switches (""perl's B<-n> switch""), programs (""some
302 systems provide a B<chfn> for that""), emphasis (""be
303 B<careful!>""), and so on (""and that feature is known as
304 B<autovivification>"").
305 "C<code>" -- code text
307 Renders code in a typewriter font, or gives some other indication
308 that this represents program text (""C<gmtime($^T)>"") or some
309 other form of computerese (""C<drwxr-xr-x>"").
310 "L<name>" -- a hyperlink
312 There are various syntaxes, listed below. In the syntaxes given,
313 "text", "name", and "section" cannot contain the characters '/' and
314 '|'; and any '<' or '>' should be matched.
315 • "L<name>"
317 Link to a Perl manual page (e.g., "L<Net::Ping>"). Note that
319 "name" should not contain spaces. This syntax is also
320 occasionally used for references to Unix man pages, as in
321 "L<crontab(5)>".
322 • "L<name/"sec">" or "L<name/sec>"
324 Link to a section in other manual page. E.g., "L<perlsyn/"For
326 Loops">"
327 • "L</"sec">" or "L</sec>"
329 Link to a section in this manual page. E.g., "L</"Object
331 Methods">"
332 A section is started by the named heading or item. For example,
334 "L<perlvar/$.>" or "L<perlvar/"$.">" both link to the section
335 started by ""=item $."" in perlvar. And "L<perlsyn/For Loops>" or
336 "L<perlsyn/"For Loops">" both link to the section started by
337 ""=head2 For Loops"" in perlsyn.
338 To control what text is used for display, you use ""L<text|...>"",
340 as in:
341 • "L<text|name>"
343 Link this text to that manual page. E.g., "L<Perl Error
345 Messages|perldiag>"
346 • "L<text|name/"sec">" or "L<text|name/sec>"
348 Link this text to that section in that manual page. E.g.,
350 "L<postfix "if"|perlsyn/"Statement Modifiers">"
351 • "L<text|/"sec">" or "L<text|/sec>" or "L<text|"sec">"
353 Link this text to that section in this manual page. E.g.,
355 "L<the various attributes|/"Member Data">"
356 Or you can link to a web page:
358 • "L<scheme:...>"
360 "L<text|scheme:...>"
362 Links to an absolute URL. For example,
364 "L<http://www.perl.org/>" or "L<The Perl Home
365 Page|http://www.perl.org/>".
366 "E<escape>" -- a character escape
368 Very similar to HTML/XML "&foo;" "entity references":
369 • "E<lt>" -- a literal < (less than)
371 • "E<gt>" -- a literal > (greater than)
373 • "E<verbar>" -- a literal | (vertical bar)
375 • "E<sol>" -- a literal / (solidus)
377 The above four are optional except in other formatting codes,
379 notably "L<...>", and when preceded by a capital letter.
380 • "E<htmlname>"
382 Some non-numeric HTML entity name, such as "E<eacute>", meaning
384 the same thing as "é" in HTML -- i.e., a lowercase e
385 with an acute (/-shaped) accent.
386 • "E<number>"
388 The ASCII/Latin-1/Unicode character with that number. A
390 leading "0x" means that number is hex, as in "E<0x201E>". A
391 leading "0" means that number is octal, as in "E<075>".
392 Otherwise number is interpreted as being in decimal, as in
393 "E<181>".
394 Note that older Pod formatters might not recognize octal or hex
396 numeric escapes, and that many formatters cannot reliably
397 render characters above 255. (Some formatters may even have to
398 use compromised renderings of Latin-1/CP-1252 characters, like
399 rendering "E<eacute>" as just a plain "e".)
400 "F<filename>" -- used for filenames
402 Typically displayed in italics. Example: ""F<.cshrc>""
403 "S<text>" -- text contains non-breaking spaces
405 This means that the words in text should not be broken across
406 lines. Example: "S<$x ? $y : $z>".
407 "X<topic name>" -- an index entry
409 This is ignored by most formatters, but some may use it for
410 building indexes. It always renders as empty-string. Example:
411 "X<absolutizing relative URLs>"
412 "Z<>" -- a null (zero-effect) formatting code
414 This is rarely used. It's one way to get around using an E<...>
415 code sometimes. For example, instead of ""NE<lt>3"" (for "N<3")
416 you could write ""NZ<><3"" (the "Z<>" breaks up the "N" and the "<"
417 so they can't be considered the part of a (fictitious) "N<...>"
418 code).
419 Another use is to indicate that stuff in "=item Z<>stuff..." is
421 not to be considered to be a bullet or number. For example,
422 without the "Z<>", the line
423 =item Z<>500 Server error
425 could possibly be parsed as an item in a numbered list when it
427 isn't meant to be.
428 Still another use is to maintain visual space between "=item"
430 lines. If you specify
431 =item foo
433 =item bar
435 it will typically get rendered as
437 foo
439 bar
440 That may be what you want, but if what you really want is
442 foo
444 bar
446 you can use "Z<>" to accomplish that
448 =item foo
450 Z<>
452 =item bar
454 Most of the time, you will need only a single set of angle brackets to
456 delimit the beginning and end of formatting codes. However, sometimes
457 you will want to put a real right angle bracket (a greater-than sign,
458 '>') inside of a formatting code. This is particularly common when
459 using a formatting code to provide a different font-type for a snippet
460 of code. As with all things in Perl, there is more than one way to do
461 it. One way is to simply escape the closing bracket using an "E" code:
462 C<$a E<lt>=E<gt> $b>
464 This will produce: ""$a <=> $b""
466 A more readable, and perhaps more "plain" way is to use an alternate
468 set of delimiters that doesn't require a single ">" to be escaped.
469 Doubled angle brackets ("<<" and ">>") may be used if and only if there
470 is whitespace right after the opening delimiter and whitespace right
471 before the closing delimiter! For example, the following will do the
472 trick:
473 C<< $a <=> $b >>
475 In fact, you can use as many repeated angle-brackets as you like so
477 long as you have the same number of them in the opening and closing
478 delimiters, and make sure that whitespace immediately follows the last
479 '<' of the opening delimiter, and immediately precedes the first '>' of
480 the closing delimiter. (The whitespace is ignored.) So the following
481 will also work:
482 C<<< $a <=> $b >>>
484 C<<<< $a <=> $b >>>>
485 And they all mean exactly the same as this:
487 C<$a E<lt>=E<gt> $b>
489 The multiple-bracket form does not affect the interpretation of the
491 contents of the formatting code, only how it must end. That means that
492 the examples above are also exactly the same as this:
493 C<< $a E<lt>=E<gt> $b >>
495 As a further example, this means that if you wanted to put these bits
497 of code in "C" (code) style:
498 open(X, ">>thing.dat") || die $!
500 $foo->bar();
501 you could do it like so:
503 C<<< open(X, ">>thing.dat") || die $! >>>
505 C<< $foo->bar(); >>
506 which is presumably easier to read than the old way:
508 C<open(X, "E<gt>E<gt>thing.dat") || die $!>
510 C<$foo-E<gt>bar();>
511 This is currently supported by pod2text (Pod::Text), pod2man
513 (Pod::Man), and any other pod2xxx or Pod::Xxxx translators that use
514 Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
515 The Intent
517 The intent is simplicity of use, not power of expression. Paragraphs
518 look like paragraphs (block format), so that they stand out visually,
519 and so that I could run them through "fmt" easily to reformat them
520 (that's F7 in my version of vi, or Esc Q in my version of emacs). I
521 wanted the translator to always leave the "'" and "`" and """ quotes
522 alone, in verbatim mode, so I could slurp in a working program, shift
523 it over four spaces, and have it print out, er, verbatim. And
524 presumably in a monospace font.
525 The Pod format is not necessarily sufficient for writing a book. Pod
527 is just meant to be an idiot-proof common source for nroff, HTML, TeX,
528 and other markup languages, as used for online documentation.
529 Translators exist for pod2text, pod2html, pod2man (that's for nroff(1)
530 and troff(1)), pod2latex, and pod2fm. Various others are available in
531 CPAN.
532 Embedding Pods in Perl Modules
534 You can embed Pod documentation in your Perl modules and scripts.
535 Start your documentation with an empty line, a "=head1" command at the
536 beginning, and end it with a "=cut" command and an empty line. The
537 perl executable will ignore the Pod text. You can place a Pod
538 statement where perl expects the beginning of a new statement, but not
539 within a statement, as that would result in an error. See any of the
540 supplied library modules for examples.
541 If you're going to put your Pod at the end of the file, and you're
543 using an "__END__" or "__DATA__" cut mark, make sure to put an empty
544 line there before the first Pod command.
545 __END__
547 =head1 NAME
549 Time::Local - efficiently compute time from local and GMT time
551 Without that empty line before the "=head1", many translators wouldn't
553 have recognized the "=head1" as starting a Pod block.
554 Hints for Writing Pod
556 •
557 The podchecker command is provided for checking Pod syntax for
560 errors and warnings. For example, it checks for completely blank
561 lines in Pod blocks and for unknown commands and formatting codes.
562 You should still also pass your document through one or more
563 translators and proofread the result, or print out the result and
564 proofread that. Some of the problems found may be bugs in the
565 translators, which you may or may not wish to work around.
566 • If you're more familiar with writing in HTML than with writing in
568 Pod, you can try your hand at writing documentation in simple HTML,
569 and converting it to Pod with the experimental Pod::HTML2Pod
570 module, (available in CPAN), and looking at the resulting code.
571 The experimental Pod::PXML module in CPAN might also be useful.
572 • Many older Pod translators require the lines before every Pod
574 command and after every Pod command (including "=cut"!) to be a
575 blank line. Having something like this:
576 # - - - - - - - - - - - -
578 =item $firecracker->boom()
579 This noisily detonates the firecracker object.
581 =cut
582 sub boom {
583 ...
584 ...will make such Pod translators completely fail to see the Pod
586 block at all.
587 Instead, have it like this:
589 # - - - - - - - - - - - -
591 =item $firecracker->boom()
593 This noisily detonates the firecracker object.
595 =cut
597 sub boom {
599 ...
600 • Some older Pod translators require paragraphs (including command
602 paragraphs like "=head2 Functions") to be separated by completely
603 empty lines. If you have an apparently empty line with some spaces
604 on it, this might not count as a separator for those translators,
605 and that could cause odd formatting.
606 • Older translators might add wording around an L<> link, so that
608 "L<Foo::Bar>" may become "the Foo::Bar manpage", for example. So
609 you shouldn't write things like "the L<foo> documentation", if you
610 want the translated document to read sensibly. Instead, write "the
611 L<Foo::Bar|Foo::Bar> documentation" or "L<the Foo::Bar
612 documentation|Foo::Bar>", to control how the link comes out.
613 • Going past the 70th column in a verbatim block might be
615 ungracefully wrapped by some formatters.
616
618 perlpodspec, "PODs: Embedded Documentation" in perlsyn, perlnewmod,
619 perldoc, pod2html, pod2man, podchecker.
620
622 Larry Wall, Sean M. Burke
623perl v5.32.1 2021-05-31 PERLPOD(1)