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. (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 =head2 Possible Values for C<$/>
82 Such commands are explained in the "Formatting Codes" section,
84 below.
85 "=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 =item Using C<$|> to Control Buffering
101 Such commands are explained in the "Formatting Codes" section,
103 below.
104 Note also that there are some basic rules to using "=over" ...
106 "=back" regions:
107 · Don't use "=item"s outside of an "=over" ... "=back" region.
109 · 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 · Don't put "=headn" commands inside an "=over" ... "=back"
115 region.
116 · 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 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 "=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 "=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 =item stuff()
142 This function does stuff.
144 =cut
146 sub stuff {
148 ...
149 }
150 =pod
152 Remember to check its return value, as in:
154 stuff() || die "Couldn't do stuff!";
156 =cut
158 "=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 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 =begin html
174 <hr> <img src="thang.png">
176 <p> This is a raw HTML paragraph </p>
177 =end html
179 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 =for html <hr> <img src="thang.png">
185 <p> This is a raw HTML paragraph </p>
186 This means the same thing as the above "=begin html" ... "=end
188 html" region.
189 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 inbetween. (Note that there still must be a blank line
194 after the "=begin" command and a blank line before the "=end"
195 command.
196 Here are some examples of how to use these:
198 =begin html
200 <br>Figure 1.<br><IMG SRC="figure1.png"><br>
202 =end html
204 =begin text
206 ---------------
208 | foo |
209 | bar |
210 ---------------
211 ^^^^ Figure 1. ^^^^
213 =end text
215 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 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 =for comment
225 Make sure that all the available options are documented!
226 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 "=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 =encoding utf8
243 =encoding koi8-r
245 =encoding ShiftJIS
247 =encoding big5
249 "=encoding" affects the whole document, and must occur only once.
251 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 Some examples of lists include:
258 =over
260 =item *
262 First item
264 =item *
266 Second item
268 =back
270 =over
272 =item Foo()
274 Description of Foo function
276 =item Bar()
278 Description of Bar function
280 =back
282 Formatting Codes
284 In ordinary paragraphs and in some command paragraphs, various
285 formatting codes (a.k.a. "interior sequences") can be used:
286 "I<text>" -- italic text
288 Used for emphasis (""be I<careful!>"") and parameters (""redo
289 I<LABEL>"")
290 "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 "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 "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 · "L<name>"
308 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 · "L<name/"sec">" or "L<name/sec>"
315 Link to a section in other manual page. E.g., "L<perlsyn/"For
317 Loops">"
318 · "L</"sec">" or "L</sec>"
320 Link to a section in this manual page. E.g., "L</"Object
322 Methods">"
323 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 To control what text is used for display, you use ""L<text|...>"",
331 as in:
332 · "L<text|name>"
334 Link this text to that manual page. E.g., "L<Perl Error
336 Messages|perldiag>"
337 · "L<text|name/"sec">" or "L<text|name/sec>"
339 Link this text to that section in that manual page. E.g.,
341 "L<postfix "if"|perlsyn/"Statement Modifiers">"
342 · "L<text|/"sec">" or "L<text|/sec>" or "L<text|"sec">"
344 Link this text to that section in this manual page. E.g.,
346 "L<the various attributes|/"Member Data">"
347 Or you can link to a web page:
349 · "L<scheme:...>"
351 "L<text|scheme:...>"
353 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 "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
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 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 "F<filename>" -- used for filenames
393 Typically displayed in italics. Example: ""F<.cshrc>""
394 "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 "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 "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 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 C<$a E<lt>=E<gt> $b>
420 This will produce: ""$a <=> $b""
422 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 With the Pod formatters that are standard starting with perl5.5.660,
426 doubled angle brackets ("<<" and ">>") may be used if and only if there
427 is whitespace right after the opening delimiter and whitespace right
428 before the closing delimiter! For example, the following will do the
429 trick:
430 C<< $a <=> $b >>
432 In fact, you can use as many repeated angle-brackets as you like so
434 long as you have the same number of them in the opening and closing
435 delimiters, and make sure that whitespace immediately follows the last
436 '<' of the opening delimiter, and immediately precedes the first '>' of
437 the closing delimiter. (The whitespace is ignored.) So the following
438 will also work:
439 C<<< $a <=> $b >>>
441 C<<<< $a <=> $b >>>>
442 And they all mean exactly the same as this:
444 C<$a E<lt>=E<gt> $b>
446 As a further example, this means that if you wanted to put these bits
448 of code in "C" (code) style:
449 open(X, ">>thing.dat") || die $!
451 $foo->bar();
452 you could do it like so:
454 C<<< open(X, ">>thing.dat") || die $! >>>
456 C<< $foo->bar(); >>
457 which is presumably easier to read than the old way:
459 C<open(X, "E<gt>E<gt>thing.dat") || die $!>
461 C<$foo-E<gt>bar();>
462 This is currently supported by pod2text (Pod::Text), pod2man
464 (Pod::Man), and any other pod2xxx or Pod::Xxxx translators that use
465 Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
466 The Intent
468 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
475 presumably 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.
480 Translators exist for pod2text, pod2html, pod2man (that's for nroff(1)
481 and 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.
486 Start your documentation with an empty line, a "=head1" command at the
487 beginning, and end it with a "=cut" command and an empty line. Perl
488 will ignore the Pod text. See any of the supplied library modules for
489 examples. If you're going to put your Pod at the end of the file, and
490 you're using an __END__ or __DATA__ cut mark, make sure to put an empty
491 line there before the first Pod command.
492 __END__
494 =head1 NAME
496 Time::Local - efficiently compute time from local and GMT time
498 Without that empty line before the "=head1", many translators wouldn't
500 have recognized the "=head1" as starting a Pod block.
501 Hints for Writing Pod
503 ·
504 The podchecker command is provided for checking Pod syntax for
507 errors and warnings. For example, it checks for completely blank
508 lines in Pod blocks and for unknown commands and formatting codes.
509 You should still also pass your document through one or more
510 translators and proofread the result, or print out the result and
511 proofread that. Some of the problems found may be bugs in the
512 translators, which you may or may not wish to work around.
513 · If you're more familiar with writing in HTML than with writing in
515 Pod, you can try your hand at writing documentation in simple HTML,
516 and converting it to Pod with the experimental Pod::HTML2Pod
517 module, (available in CPAN), and looking at the resulting code.
518 The experimental Pod::PXML module in CPAN might also be useful.
519 · Many older Pod translators require the lines before every Pod
521 command and after every Pod command (including "=cut"!) to be a
522 blank line. Having something like this:
523 # - - - - - - - - - - - -
525 =item $firecracker->boom()
526 This noisily detonates the firecracker object.
528 =cut
529 sub boom {
530 ...
531 ...will make such Pod translators completely fail to see the Pod
533 block at all.
534 Instead, have it like this:
536 # - - - - - - - - - - - -
538 =item $firecracker->boom()
540 This noisily detonates the firecracker object.
542 =cut
544 sub boom {
546 ...
547 · Some older Pod translators require paragraphs (including command
549 paragraphs like "=head2 Functions") to be separated by completely
550 empty lines. If you have an apparently empty line with some spaces
551 on it, this might not count as a separator for those translators,
552 and that could cause odd formatting.
553 · Older translators might add wording around an L<> link, so that
555 "L<Foo::Bar>" may become "the Foo::Bar manpage", for example. So
556 you shouldn't write things like "the L<foo> documentation", if you
557 want the translated document to read sensibly -- instead write "the
558 L<Foo::Bar|Foo::Bar> documentation" or "L<the Foo::Bar
559 documentation|Foo::Bar>", to control how the link comes out.
560 · Going past the 70th column in a verbatim block might be
562 ungracefully wrapped by some formatters.
563
565 perlpodspec, "PODs: Embedded Documentation" in perlsyn, perlnewmod,
566 perldoc, pod2html, pod2man, podchecker.
567
569 Larry Wall, Sean M. Burke
570perl v5.10.1 2017-03-22 PERLPOD(1)