This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlpod: #109408
[perl5.git] / pod / perlpod.pod
CommitLineData
8a93676d
SB
1
2=for comment
3This document is in Pod format. To read this, use a Pod formatter,
4like "perldoc perlpod".
5
a0d0e21e 6=head1 NAME
d74e8afc 7X<POD> X<plain old documentation>
a0d0e21e 8
8a93676d 9perlpod - the Plain Old Documentation format
a0d0e21e
LW
10
11=head1 DESCRIPTION
12
8a93676d
SB
13Pod is a simple-to-use markup language used for writing documentation
14for Perl, Perl programs, and Perl modules.
15
16Translators are available for converting Pod to various formats
17like plain text, HTML, man pages, and more.
18
19Pod markup consists of three basic kinds of paragraphs:
20L<ordinary|/"Ordinary Paragraph">,
21L<verbatim|/"Verbatim Paragraph">, and
22L<command|/"Command Paragraph">.
23
24
25=head2 Ordinary Paragraph
d74e8afc 26X<POD, ordinary paragraph>
8a93676d
SB
27
28Most paragraphs in your documentation will be ordinary blocks
29of text, like this one. You can simply type in your text without
30any markup whatsoever, and with just a blank line before and
31after. When it gets formatted, it will undergo minimal formatting,
32like being rewrapped, probably put into a proportionally spaced
33font, and maybe even justified.
34
35You can use formatting codes in ordinary paragraphs, for B<bold>,
36I<italic>, C<code-style>, L<hyperlinks|perlfaq>, and more. Such
37codes are explained in the "L<Formatting Codes|/"Formatting Codes">"
38section, below.
39
a0d0e21e 40
b74bceb9 41=head2 Verbatim Paragraph
d74e8afc 42X<POD, verbatim paragraph> X<verbatim>
a0d0e21e 43
8a93676d
SB
44Verbatim paragraphs are usually used for presenting a codeblock or
45other text which does not require any special parsing or formatting,
46and which shouldn't be wrapped.
47
48A verbatim paragraph is distinguished by having its first character
49be a space or a tab. (And commonly, all its lines begin with spaces
50and/or tabs.) It should be reproduced exactly, with tabs assumed to
51be on 8-column boundaries. There are no special formatting codes,
52so you can't italicize or anything like that. A \ means \, and
53nothing else.
54
a0d0e21e 55
b74bceb9 56=head2 Command Paragraph
d74e8afc 57X<POD, command>
b74bceb9 58
8a93676d
SB
59A command paragraph is used for special treatment of whole chunks
60of text, usually as headings or parts of lists.
61
62All command paragraphs (which are typically only one line long) start
63with "=", followed by an identifier, followed by arbitrary text that
64the command can use however it pleases. Currently recognized commands
65are
a0d0e21e 66
2757242d 67 =pod
8a93676d
SB
68 =head1 Heading Text
69 =head2 Heading Text
70 =head3 Heading Text
71 =head4 Heading Text
72 =over indentlevel
73 =item stuff
a0d0e21e 74 =back
8a93676d
SB
75 =begin format
76 =end format
77 =for format text...
2757242d
YO
78 =encoding type
79 =cut
8a93676d
SB
80
81To explain them each in detail:
82
83=over
84
85=item C<=head1 I<Heading Text>>
d74e8afc
ITB
86X<=head1> X<=head2> X<=head3> X<=head4>
87X<head1> X<head2> X<head3> X<head4>
cb1a09d0 88
8a93676d 89=item C<=head2 I<Heading Text>>
b74bceb9 90
8a93676d 91=item C<=head3 I<Heading Text>>
b74bceb9 92
8a93676d 93=item C<=head4 I<Heading Text>>
b74bceb9 94
8a93676d
SB
95Head1 through head4 produce headings, head1 being the highest
96level. The text in the rest of this paragraph is the content of the
97heading. For example:
cb1a09d0 98
8a93676d 99 =head2 Object Attributes
b74bceb9 100
684c7e37
BF
101The text "Object Attributes" comprises the heading there.
102The text in these heading commands can use formatting codes, as seen here:
b74bceb9 103
8a93676d 104 =head2 Possible Values for C<$/>
c6b85e5d 105
8a93676d
SB
106Such commands are explained in the
107"L<Formatting Codes|/"Formatting Codes">" section, below.
c6b85e5d 108
8a93676d 109=item C<=over I<indentlevel>>
d74e8afc 110X<=over> X<=item> X<=back> X<over> X<item> X<back>
cb1a09d0 111
8a93676d 112=item C<=item I<stuff...>>
b74bceb9 113
8a93676d 114=item C<=back>
b74bceb9 115
8a93676d
SB
116Item, over, and back require a little more explanation: "=over" starts
117a region specifically for the generation of a list using "=item"
118commands, or for indenting (groups of) normal paragraphs. At the end
119of your list, use "=back" to end it. The I<indentlevel> option to
120"=over" indicates how far over to indent, generally in ems (where
121one em is the width of an "M" in the document's base font) or roughly
122comparable units; if there is no I<indentlevel> option, it defaults
123to four. (And some formatters may just ignore whatever I<indentlevel>
124you provide.) In the I<stuff> in C<=item I<stuff...>>, you may
125use formatting codes, as seen here:
b74bceb9 126
8a93676d 127 =item Using C<$|> to Control Buffering
cb1a09d0 128
8a93676d
SB
129Such commands are explained in the
130"L<Formatting Codes|/"Formatting Codes">" section, below.
b74bceb9 131
8a93676d
SB
132Note also that there are some basic rules to using "=over" ...
133"=back" regions:
b74bceb9 134
8a93676d 135=over
b74bceb9 136
8a93676d
SB
137=item *
138
139Don't use "=item"s outside of an "=over" ... "=back" region.
140
141=item *
c7c9f956 142
8a93676d
SB
143The first thing after the "=over" command should be an "=item", unless
144there aren't going to be any items at all in this "=over" ... "=back"
145region.
146
147=item *
148
149Don't put "=headI<n>" commands inside an "=over" ... "=back" region.
150
151=item *
152
153And perhaps most importantly, keep the items consistent: either use
154"=item *" for all of them, to produce bullets; or use "=item 1.",
155"=item 2.", etc., to produce numbered lists; or use "=item foo",
ac036724 156"=item bar", etc.--namely, things that look nothing like bullets or
8a93676d
SB
157numbers.
158
159If you start with bullets or numbers, stick with them, as
160formatters use the first "=item" type to decide how to format the
161list.
162
163=back
164
165=item C<=cut>
d74e8afc 166X<=cut> X<cut>
8a93676d
SB
167
168To end a Pod block, use a blank line,
169then a line beginning with "=cut", and a blank
170line after it. This lets Perl (and the Pod formatter) know that
171this is where Perl code is resuming. (The blank line before the "=cut"
172is not technically necessary, but many older Pod processors require it.)
173
174=item C<=pod>
d74e8afc 175X<=pod> X<pod>
8a93676d
SB
176
177The "=pod" command by itself doesn't do much of anything, but it
178signals to Perl (and Pod formatters) that a Pod block starts here. A
179Pod block starts with I<any> command paragraph, so a "=pod" command is
180usually used just when you want to start a Pod block with an ordinary
181paragraph or a verbatim paragraph. For example:
182
183 =item stuff()
210b36aa 184
8a93676d 185 This function does stuff.
210b36aa 186
8a93676d 187 =cut
210b36aa 188
8a93676d
SB
189 sub stuff {
190 ...
191 }
210b36aa 192
8a93676d 193 =pod
210b36aa 194
8a93676d 195 Remember to check its return value, as in:
210b36aa
AMS
196
197 stuff() || die "Couldn't do stuff!";
198
8a93676d
SB
199 =cut
200
201=item C<=begin I<formatname>>
d74e8afc 202X<=begin> X<=end> X<=for> X<begin> X<end> X<for>
8a93676d
SB
203
204=item C<=end I<formatname>>
205
206=item C<=for I<formatname> I<text...>>
207
208For, begin, and end will let you have regions of text/code/data that
209are not generally interpreted as normal Pod text, but are passed
210directly to particular formatters, or are otherwise special. A
211formatter that can use that format will use the region, otherwise it
212will be completely ignored.
213
214A command "=begin I<formatname>", some paragraphs, and a
353c6505 215command "=end I<formatname>", mean that the text/data in between
8a93676d
SB
216is meant for formatters that understand the special format
217called I<formatname>. For example,
218
219 =begin html
210b36aa 220
8a93676d 221 <hr> <img src="thang.png">
c7c9f956 222 <p> This is a raw HTML paragraph </p>
210b36aa 223
8a93676d
SB
224 =end html
225
226The command "=for I<formatname> I<text...>"
227specifies that the remainder of just this paragraph (starting
228right after I<formatname>) is in that special format.
229
230 =for html <hr> <img src="thang.png">
231 <p> This is a raw HTML paragraph </p>
232
233This means the same thing as the above "=begin html" ... "=end html"
234region.
c7c9f956 235
8a93676d
SB
236That is, with "=for", you can have only one paragraph's worth
237of text (i.e., the text in "=foo targetname text..."), but with
238"=begin targetname" ... "=end targetname", you can have any amount
1cecf2c0 239of stuff in between. (Note that there still must be a blank line
8a93676d
SB
240after the "=begin" command and a blank line before the "=end"
241command.
c7c9f956
KA
242
243Here are some examples of how to use these:
244
8a93676d
SB
245 =begin html
246
247 <br>Figure 1.<br><IMG SRC="figure1.png"><br>
248
249 =end html
250
251 =begin text
252
253 ---------------
254 | foo |
255 | bar |
256 ---------------
a6006777 257
8a93676d 258 ^^^^ Figure 1. ^^^^
a6006777 259
8a93676d 260 =end text
a6006777 261
8a93676d
SB
262Some format names that formatters currently are known to accept
263include "roff", "man", "latex", "tex", "text", and "html". (Some
264formatters will treat some of these as synonyms.)
a6006777 265
8a93676d
SB
266A format name of "comment" is common for just making notes (presumably
267to yourself) that won't appear in any formatted version of the Pod
268document:
a6006777 269
8a93676d
SB
270 =for comment
271 Make sure that all the available options are documented!
a6006777 272
8a93676d
SB
273Some I<formatnames> will require a leading colon (as in
274C<"=for :formatname">, or
275C<"=begin :formatname" ... "=end :formatname">),
276to signal that the text is not raw data, but instead I<is> Pod text
277(i.e., possibly containing formatting codes) that's just not for
278normal formatting (e.g., may not be a normal-use paragraph, but might
279be for formatting as a footnote).
c7c9f956 280
a179871b 281=item C<=encoding I<encodingname>>
d74e8afc 282X<=encoding> X<encoding>
a179871b
SB
283
284This command is used for declaring the encoding of a document. Most
285users won't need this; but if your encoding isn't US-ASCII or Latin-1,
286then put a C<=encoding I<encodingname>> command early in the document so
287that pod formatters will know how to decode the document. For
288I<encodingname>, use a name recognized by the L<Encode::Supported>
289module. Examples:
290
291 =encoding utf8
292
293 =encoding koi8-r
294
295 =encoding ShiftJIS
296
297 =encoding big5
298
8a93676d 299=back
c7c9f956 300
7a9a6fa1
DJ
301C<=encoding> affects the whole document, and must occur only once.
302
303And don't forget, when using any other command, that the command lasts up
8a93676d
SB
304until the end of its I<paragraph>, not its line. So in the
305examples below, you can see that every command needs the blank
306line after it, to end its paragraph.
cb1a09d0
AD
307
308Some examples of lists include:
309
8a93676d
SB
310 =over
311
312 =item *
313
314 First item
315
316 =item *
317
318 Second item
319
320 =back
321
322 =over
323
324 =item Foo()
325
326 Description of Foo function
327
328 =item Bar()
cb1a09d0 329
8a93676d 330 Description of Bar function
cb1a09d0 331
8a93676d 332 =back
cb1a09d0 333
cb1a09d0 334
8a93676d 335=head2 Formatting Codes
d74e8afc
ITB
336X<POD, formatting code> X<formatting code>
337X<POD, interior sequence> X<interior sequence>
cb1a09d0 338
8a93676d
SB
339In ordinary paragraphs and in some command paragraphs, various
340formatting codes (a.k.a. "interior sequences") can be used:
cb1a09d0 341
8a93676d
SB
342=for comment
343 "interior sequences" is such an opaque term.
344 Prefer "formatting codes" instead.
cb1a09d0 345
8a93676d 346=over
cb1a09d0 347
8a93676d 348=item C<IE<lt>textE<gt>> -- italic text
d74e8afc 349X<I> X<< IZ<><> >> X<POD, formatting code, italic> X<italic>
cb1a09d0 350
8a93676d
SB
351Used for emphasis ("C<be IE<lt>careful!E<gt>>") and parameters
352("C<redo IE<lt>LABELE<gt>>")
353
354=item C<BE<lt>textE<gt>> -- bold text
d74e8afc 355X<B> X<< BZ<><> >> X<POD, formatting code, bold> X<bold>
8a93676d
SB
356
357Used for switches ("C<perl's BE<lt>-nE<gt> switch>"), programs
358("C<some systems provide a BE<lt>chfnE<gt> for that>"),
359emphasis ("C<be BE<lt>careful!E<gt>>"), and so on
360("C<and that feature is known as BE<lt>autovivificationE<gt>>").
361
362=item C<CE<lt>codeE<gt>> -- code text
d74e8afc 363X<C> X<< CZ<><> >> X<POD, formatting code, code> X<code>
8a93676d
SB
364
365Renders code in a typewriter font, or gives some other indication that
366this represents program text ("C<CE<lt>gmtime($^T)E<gt>>") or some other
367form of computerese ("C<CE<lt>drwxr-xr-xE<gt>>").
368
369=item C<LE<lt>nameE<gt>> -- a hyperlink
d74e8afc 370X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink> X<hyperlink>
8a93676d
SB
371
372There are various syntaxes, listed below. In the syntaxes given,
373C<text>, C<name>, and C<section> cannot contain the characters
374'/' and '|'; and any '<' or '>' should be matched.
375
376=over
377
378=item *
cb1a09d0 379
8a93676d 380C<LE<lt>nameE<gt>>
cb1a09d0 381
8a93676d
SB
382Link to a Perl manual page (e.g., C<LE<lt>Net::PingE<gt>>). Note
383that C<name> should not contain spaces. This syntax
e1020413 384is also occasionally used for references to Unix man pages, as in
8a93676d
SB
385C<LE<lt>crontab(5)E<gt>>.
386
387=item *
388
389C<LE<lt>name/"sec"E<gt>> or C<LE<lt>name/secE<gt>>
390
391Link to a section in other manual page. E.g.,
392C<LE<lt>perlsyn/"For Loops"E<gt>>
393
394=item *
395
b41aadf2 396C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>>
8a93676d
SB
397
398Link to a section in this manual page. E.g.,
399C<LE<lt>/"Object Methods"E<gt>>
a0d0e21e 400
b74bceb9
AB
401=back
402
8a93676d
SB
403A section is started by the named heading or item. For
404example, C<LE<lt>perlvar/$.E<gt>> or C<LE<lt>perlvar/"$."E<gt>> both
405link to the section started by "C<=item $.>" in perlvar. And
406C<LE<lt>perlsyn/For LoopsE<gt>> or C<LE<lt>perlsyn/"For Loops"E<gt>>
407both link to the section started by "C<=head2 For Loops>"
408in perlsyn.
409
410To control what text is used for display, you
411use "C<LE<lt>text|...E<gt>>", as in:
412
413=over
414
415=item *
416
417C<LE<lt>text|nameE<gt>>
418
419Link this text to that manual page. E.g.,
420C<LE<lt>Perl Error Messages|perldiagE<gt>>
421
422=item *
423
424C<LE<lt>text|name/"sec"E<gt>> or C<LE<lt>text|name/secE<gt>>
425
426Link this text to that section in that manual page. E.g.,
8325efec 427C<LE<lt>postfix "if"|perlsyn/"Statement Modifiers"E<gt>>
8a93676d
SB
428
429=item *
430
431C<LE<lt>text|/"sec"E<gt>> or C<LE<lt>text|/secE<gt>>
432or C<LE<lt>text|"sec"E<gt>>
433
434Link this text to that section in this manual page. E.g.,
435C<LE<lt>the various attributes|/"Member Data"E<gt>>
436
437=back
438
439Or you can link to a web page:
440
441=over
442
443=item *
444
445C<LE<lt>scheme:...E<gt>>
446
f6e963e4
RS
447C<LE<lt>text|scheme:...E<gt>>
448
449Links to an absolute URL. For example, C<LE<lt>http://www.perl.org/E<gt>> or
450C<LE<lt>The Perl Home Page|http://www.perl.org/E<gt>>.
8a93676d
SB
451
452=back
453
454=item C<EE<lt>escapeE<gt>> -- a character escape
d74e8afc 455X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape>
8a93676d
SB
456
457Very similar to HTML/XML C<&I<foo>;> "entity references":
458
459=over
460
461=item *
462
463C<EE<lt>ltE<gt>> -- a literal E<lt> (less than)
464
465=item *
466
467C<EE<lt>gtE<gt>> -- a literal E<gt> (greater than)
468
469=item *
470
471C<EE<lt>verbarE<gt>> -- a literal | (I<ver>tical I<bar>)
472
473=item *
474
1f1448d9 475C<EE<lt>solE<gt>> -- a literal / (I<sol>idus)
8a93676d
SB
476
477The above four are optional except in other formatting codes,
478notably C<LE<lt>...E<gt>>, and when preceded by a
479capital letter.
480
481=item *
482
483C<EE<lt>htmlnameE<gt>>
484
485Some non-numeric HTML entity name, such as C<EE<lt>eacuteE<gt>>,
486meaning the same thing as C<&eacute;> in HTML -- i.e., a lowercase
487e with an acute (/-shaped) accent.
488
489=item *
490
491C<EE<lt>numberE<gt>>
492
493The ASCII/Latin-1/Unicode character with that number. A
494leading "0x" means that I<number> is hex, as in
495C<EE<lt>0x201EE<gt>>. A leading "0" means that I<number> is octal,
496as in C<EE<lt>075E<gt>>. Otherwise I<number> is interpreted as being
497in decimal, as in C<EE<lt>181E<gt>>.
498
499Note that older Pod formatters might not recognize octal or
500hex numeric escapes, and that many formatters cannot reliably
501render characters above 255. (Some formatters may even have
502to use compromised renderings of Latin-1 characters, like
503rendering C<EE<lt>eacuteE<gt>> as just a plain "e".)
504
505=back
506
507=item C<FE<lt>filenameE<gt>> -- used for filenames
d74e8afc 508X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename>
8a93676d
SB
509
510Typically displayed in italics. Example: "C<FE<lt>.cshrcE<gt>>"
511
512=item C<SE<lt>textE<gt>> -- text contains non-breaking spaces
d74e8afc
ITB
513X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space>
514X<non-breaking space>
8a93676d
SB
515
516This means that the words in I<text> should not be broken
517across lines. Example: S<C<SE<lt>$x ? $y : $zE<gt>>>.
518
519=item C<XE<lt>topic nameE<gt>> -- an index entry
d74e8afc 520X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry>
8a93676d
SB
521
522This is ignored by most formatters, but some may use it for building
523indexes. It always renders as empty-string.
524Example: C<XE<lt>absolutizing relative URLsE<gt>>
525
526=item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code
d74e8afc 527X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null>
8a93676d
SB
528
529This is rarely used. It's one way to get around using an
530EE<lt>...E<gt> code sometimes. For example, instead of
531"C<NEE<lt>ltE<gt>3>" (for "NE<lt>3") you could write
532"C<NZE<lt>E<gt>E<lt>3>" (the "ZE<lt>E<gt>" breaks up the "N" and
533the "E<lt>" so they can't be considered
534the part of a (fictitious) "NE<lt>...E<gt>" code.
535
536=for comment
537 This was formerly explained as a "zero-width character". But it in
538 most parser models, it parses to nothing at all, as opposed to parsing
539 as if it were a E<zwnj> or E<zwj>, which are REAL zero-width characters.
540 So "width" and "character" are exactly the wrong words.
541
542=back
543
544Most of the time, you will need only a single set of angle brackets to
545delimit the beginning and end of formatting codes. However,
546sometimes you will want to put a real right angle bracket (a
547greater-than sign, '>') inside of a formatting code. This is particularly
548common when using a formatting code to provide a different font-type for a
549snippet of code. As with all things in Perl, there is more than
550one way to do it. One way is to simply escape the closing bracket
551using an C<E> code:
5455df32
GS
552
553 C<$a E<lt>=E<gt> $b>
554
555This will produce: "C<$a E<lt>=E<gt> $b>"
556
8a93676d 557A more readable, and perhaps more "plain" way is to use an alternate
8162142b
JD
558set of delimiters that doesn't require a single ">" to be escaped.
559Doubled angle brackets ("<<" and ">>") may be used I<if and only if there is
8a93676d
SB
560whitespace right after the opening delimiter and whitespace right
561before the closing delimiter!> For example, the following will
562do the trick:
d74e8afc 563X<POD, formatting code, escaping with multiple brackets>
5455df32
GS
564
565 C<< $a <=> $b >>
566
567In fact, you can use as many repeated angle-brackets as you like so
568long as you have the same number of them in the opening and closing
569delimiters, and make sure that whitespace immediately follows the last
8a93676d
SB
570'<' of the opening delimiter, and immediately precedes the first '>'
571of the closing delimiter. (The whitespace is ignored.) So the
572following will also work:
d74e8afc 573X<POD, formatting code, escaping with multiple brackets>
5455df32
GS
574
575 C<<< $a <=> $b >>>
8a93676d 576 C<<<< $a <=> $b >>>>
5455df32 577
8a93676d
SB
578And they all mean exactly the same as this:
579
580 C<$a E<lt>=E<gt> $b>
581
a3d78747
RS
582The multiple-bracket form does not affect the interpretation of the contents of
583the formatting code, only how it must end. That means that the examples above
584are also exactly the same as this:
585
586 C<< $a E<lt>=E<gt> $b >>
587
8a93676d
SB
588As a further example, this means that if you wanted to put these bits of
589code in C<C> (code) style:
590
591 open(X, ">>thing.dat") || die $!
592 $foo->bar();
593
594you could do it like so:
595
596 C<<< open(X, ">>thing.dat") || die $! >>>
597 C<< $foo->bar(); >>
5455df32 598
8a93676d
SB
599which is presumably easier to read than the old way:
600
601 C<open(X, "E<gt>E<gt>thing.dat") || die $!>
c58e3c1c 602 C<$foo-E<gt>bar();>
8a93676d
SB
603
604This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
605and any other pod2xxx or Pod::Xxxx translators that use
606Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
5455df32 607
b74bceb9 608=head2 The Intent
d74e8afc 609X<POD, intent of>
3141265f 610
8a93676d
SB
611The intent is simplicity of use, not power of expression. Paragraphs
612look like paragraphs (block format), so that they stand out
613visually, and so that I could run them through C<fmt> easily to reformat
614them (that's F7 in my version of B<vi>, or Esc Q in my version of
615B<emacs>). I wanted the translator to always leave the C<'> and C<`> and
616C<"> quotes alone, in verbatim mode, so I could slurp in a
617working program, shift it over four spaces, and have it print out, er,
618verbatim. And presumably in a monospace font.
619
620The Pod format is not necessarily sufficient for writing a book. Pod
621is just meant to be an idiot-proof common source for nroff, HTML,
622TeX, and other markup languages, as used for online
623documentation. Translators exist for B<pod2text>, B<pod2html>,
624B<pod2man> (that's for nroff(1) and troff(1)), B<pod2latex>, and
625B<pod2fm>. Various others are available in CPAN.
626
a0d0e21e 627
b74bceb9 628=head2 Embedding Pods in Perl Modules
d74e8afc 629X<POD, embedding>
4633a7c4 630
8a93676d
SB
631You can embed Pod documentation in your Perl modules and scripts.
632Start your documentation with an empty line, a "=head1" command at the
633beginning, and end it with a "=cut" command and an empty line. Perl
634will ignore the Pod text. See any of the supplied library modules for
635examples. If you're going to put your Pod at the end of the file, and
636you're using an __END__ or __DATA__ cut mark, make sure to put an
637empty line there before the first Pod command.
cb1a09d0 638
8a93676d 639 __END__
cb1a09d0 640
8a93676d 641 =head1 NAME
cb1a09d0 642
8a93676d 643 Time::Local - efficiently compute time from local and GMT time
cb1a09d0 644
8a93676d
SB
645Without that empty line before the "=head1", many translators wouldn't
646have recognized the "=head1" as starting a Pod block.
cb1a09d0 647
8a93676d 648=head2 Hints for Writing Pod
1294c5d8 649
8a93676d 650=over
1294c5d8
JM
651
652=item *
d74e8afc 653X<podchecker> X<POD, validating>
1294c5d8 654
8a93676d
SB
655The B<podchecker> command is provided for checking Pod syntax for errors
656and warnings. For example, it checks for completely blank lines in
657Pod blocks and for unknown commands and formatting codes. You should
658still also pass your document through one or more translators and proofread
659the result, or print out the result and proofread that. Some of the
660problems found may be bugs in the translators, which you may or may not
661wish to work around.
1294c5d8
JM
662
663=item *
664
8a93676d 665If you're more familiar with writing in HTML than with writing in Pod, you
210b36aa 666can try your hand at writing documentation in simple HTML, and converting
8a93676d
SB
667it to Pod with the experimental L<Pod::HTML2Pod|Pod::HTML2Pod> module,
668(available in CPAN), and looking at the resulting code. The experimental
669L<Pod::PXML|Pod::PXML> module in CPAN might also be useful.
670
671=item *
672
673Many older Pod translators require the lines before every Pod
674command and after every Pod command (including "=cut"!) to be a blank
675line. Having something like this:
676
677 # - - - - - - - - - - - -
678 =item $firecracker->boom()
210b36aa 679
8a93676d
SB
680 This noisily detonates the firecracker object.
681 =cut
682 sub boom {
683 ...
684
685...will make such Pod translators completely fail to see the Pod block
686at all.
687
688Instead, have it like this:
689
690 # - - - - - - - - - - - -
210b36aa 691
8a93676d 692 =item $firecracker->boom()
210b36aa 693
8a93676d 694 This noisily detonates the firecracker object.
210b36aa 695
8a93676d 696 =cut
210b36aa 697
8a93676d
SB
698 sub boom {
699 ...
700
701=item *
702
703Some older Pod translators require paragraphs (including command
704paragraphs like "=head2 Functions") to be separated by I<completely>
705empty lines. If you have an apparently empty line with some spaces
706on it, this might not count as a separator for those translators, and
707that could cause odd formatting.
708
709=item *
1294c5d8 710
8a93676d
SB
711Older translators might add wording around an LE<lt>E<gt> link, so that
712C<LE<lt>Foo::BarE<gt>> may become "the Foo::Bar manpage", for example.
713So you shouldn't write things like C<the LE<lt>fooE<gt>
ac036724 714documentation>, if you want the translated document to read sensibly.
715Instead, write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or
8a93676d
SB
716C<LE<lt>the Foo::Bar documentation|Foo::BarE<gt>>, to control how the
717link comes out.
b74bceb9 718
1294c5d8
JM
719=item *
720
8a93676d
SB
721Going past the 70th column in a verbatim block might be ungracefully
722wrapped by some formatters.
1294c5d8
JM
723
724=back
725
cb1a09d0
AD
726=head1 SEE ALSO
727
8a93676d
SB
728L<perlpodspec>, L<perlsyn/"PODs: Embedded Documentation">,
729L<perlnewmod>, L<perldoc>, L<pod2html>, L<pod2man>, L<podchecker>.
4633a7c4 730
cb1a09d0 731=head1 AUTHOR
a0d0e21e 732
8a93676d 733Larry Wall, Sean M. Burke
a0d0e21e 734
8a93676d 735=cut