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

SEE ALSO

579       perlpodspec, "PODs: Embedded Documentation" in perlsyn, perlnewmod,
580       perldoc, pod2html, pod2man, podchecker.
581

AUTHOR

583       Larry Wall, Sean M. Burke
584
585
586
587perl v5.28.2                      2018-03-01                        PERLPOD(1)
Impressum