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.  The text
77           in these heading commands can use formatting codes, as seen here:
78
79             =head2 Possible Values for C<$/>
80
81           Such commands are explained in the "Formatting Codes" section,
82           below.
83
84       "=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
98             =item Using C<$|> to Control Buffering
99
100           Such commands are explained in the "Formatting Codes" section,
101           below.
102
103           Note also that there are some basic rules to using "=over" ...
104           "=back" regions:
105
106           ·   Don't use "=item"s outside of an "=over" ... "=back" region.
107
108           ·   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
112           ·   Don't put "=headn" commands inside an "=over" ... "=back"
113               region.
114
115           ·   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
125               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
129       "=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
136       "=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
143             =item stuff()
144
145             This function does stuff.
146
147             =cut
148
149             sub stuff {
150               ...
151             }
152
153             =pod
154
155             Remember to check its return value, as in:
156
157               stuff() || die "Couldn't do stuff!";
158
159             =cut
160
161       "=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
170           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
175             =begin html
176
177             <hr> <img src="thang.png">
178             <p> This is a raw HTML paragraph </p>
179
180             =end html
181
182           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
186             =for html <hr> <img src="thang.png">
187             <p> This is a raw HTML paragraph </p>
188
189           This means the same thing as the above "=begin html" ... "=end
190           html" region.
191
192           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
199           Here are some examples of how to use these:
200
201             =begin html
202
203             <br>Figure 1.<br><IMG SRC="figure1.png"><br>
204
205             =end html
206
207             =begin text
208
209               ---------------
210               |  foo        |
211               |        bar  |
212               ---------------
213
214             ^^^^ Figure 1. ^^^^
215
216             =end text
217
218           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
222           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
226             =for comment
227             Make sure that all the available options are documented!
228
229           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
236       "=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
247             =encoding latin1
248
249             =encoding utf8
250
251             =encoding koi8-r
252
253             =encoding ShiftJIS
254
255             =encoding big5
256
257           "=encoding" affects the whole document, and must occur only once.
258
259       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
266       Some examples of lists include:
267
268         =over
269
270         =item *
271
272         First item
273
274         =item *
275
276         Second item
277
278         =back
279
280         =over
281
282         =item Foo()
283
284         Description of Foo function
285
286         =item Bar()
287
288         Description of Bar function
289
290         =back
291
292   Formatting Codes
293       In ordinary paragraphs and in some command paragraphs, various
294       formatting codes (a.k.a. "interior sequences") can be used:
295
296       "I<text>" -- italic text
297           Used for emphasis (""be I<careful!>"") and parameters (""redo
298           I<LABEL>"")
299
300       "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
306       "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
311       "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
316           ·   "L<name>"
317
318               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
323           ·   "L<name/"sec">" or "L<name/sec>"
324
325               Link to a section in other manual page.  E.g., "L<perlsyn/"For
326               Loops">"
327
328           ·   "L</"sec">" or "L</sec>"
329
330               Link to a section in this manual page.  E.g., "L</"Object
331               Methods">"
332
333           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
339           To control what text is used for display, you use ""L<text|...>"",
340           as in:
341
342           ·   "L<text|name>"
343
344               Link this text to that manual page.  E.g., "L<Perl Error
345               Messages|perldiag>"
346
347           ·   "L<text|name/"sec">" or "L<text|name/sec>"
348
349               Link this text to that section in that manual page.  E.g.,
350               "L<postfix "if"|perlsyn/"Statement Modifiers">"
351
352           ·   "L<text|/"sec">" or "L<text|/sec>" or "L<text|"sec">"
353
354               Link this text to that section in this manual page.  E.g.,
355               "L<the various attributes|/"Member Data">"
356
357           Or you can link to a web page:
358
359           ·   "L<scheme:...>"
360
361               "L<text|scheme:...>"
362
363               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
367       "E<escape>" -- a character escape
368           Very similar to HTML/XML "&foo;" "entity references":
369
370           ·   "E<lt>" -- a literal < (less than)
371
372           ·   "E<gt>" -- a literal > (greater than)
373
374           ·   "E<verbar>" -- a literal | (vertical bar)
375
376           ·   "E<sol>" -- a literal / (solidus)
377
378               The above four are optional except in other formatting codes,
379               notably "L<...>", and when preceded by a capital letter.
380
381           ·   "E<htmlname>"
382
383               Some non-numeric HTML entity name, such as "E<eacute>", meaning
384               the same thing as "&eacute;" in HTML -- i.e., a lowercase e
385               with an acute (/-shaped) accent.
386
387           ·   "E<number>"
388
389               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
395               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
401       "F<filename>" -- used for filenames
402           Typically displayed in italics.  Example: ""F<.cshrc>""
403
404       "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
408       "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
413       "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
420           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
424            =item Z<>500 Server error
425
426           could possibly be parsed as an item in a numbered list when it
427           isn't meant to be.
428
429           Still another use is to maintain visual space between "=item"
430           lines.  If you specify
431
432            =item foo
433
434            =item bar
435
436           it will typically get rendered as
437
438            foo
439            bar
440
441           That may be what you want, but if what you really want is
442
443            foo
444
445            bar
446
447           you can use "Z<>" to accomplish that
448
449            =item foo
450
451            Z<>
452
453            =item bar
454
455       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
463           C<$a E<lt>=E<gt> $b>
464
465       This will produce: ""$a <=> $b""
466
467       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
474           C<< $a <=> $b >>
475
476       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
483           C<<< $a <=> $b >>>
484           C<<<<  $a <=> $b     >>>>
485
486       And they all mean exactly the same as this:
487
488           C<$a E<lt>=E<gt> $b>
489
490       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
494           C<< $a E<lt>=E<gt> $b >>
495
496       As a further example, this means that if you wanted to put these bits
497       of code in "C" (code) style:
498
499           open(X, ">>thing.dat") || die $!
500           $foo->bar();
501
502       you could do it like so:
503
504           C<<< open(X, ">>thing.dat") || die $! >>>
505           C<< $foo->bar(); >>
506
507       which is presumably easier to read than the old way:
508
509           C<open(X, "E<gt>E<gt>thing.dat") || die $!>
510           C<$foo-E<gt>bar();>
511
512       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
516   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
526       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
533   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
542       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
546         __END__
547
548         =head1 NAME
549
550         Time::Local - efficiently compute time from local and GMT time
551
552       Without that empty line before the "=head1", many translators wouldn't
553       have recognized the "=head1" as starting a Pod block.
554
555   Hints for Writing Pod
556       ·
557
558
559           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
567       ·   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
573       ·   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
577            # - - - - - - - - - - - -
578            =item $firecracker->boom()
579
580            This noisily detonates the firecracker object.
581            =cut
582            sub boom {
583            ...
584
585           ...will make such Pod translators completely fail to see the Pod
586           block at all.
587
588           Instead, have it like this:
589
590            # - - - - - - - - - - - -
591
592            =item $firecracker->boom()
593
594            This noisily detonates the firecracker object.
595
596            =cut
597
598            sub boom {
599            ...
600
601       ·   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
607       ·   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
614       ·   Going past the 70th column in a verbatim block might be
615           ungracefully wrapped by some formatters.
616

SEE ALSO

618       perlpodspec, "PODs: Embedded Documentation" in perlsyn, perlnewmod,
619       perldoc, pod2html, pod2man, podchecker.
620

AUTHOR

622       Larry Wall, Sean M. Burke
623
624
625
626perl v5.32.1                      2021-03-31                        PERLPOD(1)
Impressum