This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
pod/perlpod: Add advice about Z<> uses
[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
ba77fc59
KW
157numbers. (If you have a list that contains both: 1) things that don't
158look like bullets nor numbers, plus 2) things that do, you should
159preface the bullet- or number-like items with C<ZE<lt>E<gt>>. See
160L<ZE<lt>E<gt>|/ZE<lt>E<gt> -- a null (zero-effect) formatting code>
161below for an example.)
8a93676d
SB
162
163If you start with bullets or numbers, stick with them, as
164formatters use the first "=item" type to decide how to format the
165list.
166
167=back
168
169=item C<=cut>
d74e8afc 170X<=cut> X<cut>
8a93676d
SB
171
172To end a Pod block, use a blank line,
173then a line beginning with "=cut", and a blank
174line after it. This lets Perl (and the Pod formatter) know that
175this is where Perl code is resuming. (The blank line before the "=cut"
176is not technically necessary, but many older Pod processors require it.)
177
178=item C<=pod>
d74e8afc 179X<=pod> X<pod>
8a93676d
SB
180
181The "=pod" command by itself doesn't do much of anything, but it
182signals to Perl (and Pod formatters) that a Pod block starts here. A
183Pod block starts with I<any> command paragraph, so a "=pod" command is
184usually used just when you want to start a Pod block with an ordinary
185paragraph or a verbatim paragraph. For example:
186
187 =item stuff()
210b36aa 188
8a93676d 189 This function does stuff.
210b36aa 190
8a93676d 191 =cut
210b36aa 192
8a93676d
SB
193 sub stuff {
194 ...
195 }
210b36aa 196
8a93676d 197 =pod
210b36aa 198
8a93676d 199 Remember to check its return value, as in:
210b36aa
AMS
200
201 stuff() || die "Couldn't do stuff!";
202
8a93676d
SB
203 =cut
204
205=item C<=begin I<formatname>>
d74e8afc 206X<=begin> X<=end> X<=for> X<begin> X<end> X<for>
8a93676d
SB
207
208=item C<=end I<formatname>>
209
210=item C<=for I<formatname> I<text...>>
211
212For, begin, and end will let you have regions of text/code/data that
213are not generally interpreted as normal Pod text, but are passed
214directly to particular formatters, or are otherwise special. A
215formatter that can use that format will use the region, otherwise it
216will be completely ignored.
217
218A command "=begin I<formatname>", some paragraphs, and a
353c6505 219command "=end I<formatname>", mean that the text/data in between
8a93676d
SB
220is meant for formatters that understand the special format
221called I<formatname>. For example,
222
223 =begin html
210b36aa 224
8a93676d 225 <hr> <img src="thang.png">
c7c9f956 226 <p> This is a raw HTML paragraph </p>
210b36aa 227
8a93676d
SB
228 =end html
229
230The command "=for I<formatname> I<text...>"
231specifies that the remainder of just this paragraph (starting
232right after I<formatname>) is in that special format.
233
234 =for html <hr> <img src="thang.png">
235 <p> This is a raw HTML paragraph </p>
236
237This means the same thing as the above "=begin html" ... "=end html"
238region.
c7c9f956 239
8a93676d
SB
240That is, with "=for", you can have only one paragraph's worth
241of text (i.e., the text in "=foo targetname text..."), but with
242"=begin targetname" ... "=end targetname", you can have any amount
1cecf2c0 243of stuff in between. (Note that there still must be a blank line
8a93676d 244after the "=begin" command and a blank line before the "=end"
943fc58e 245command.)
c7c9f956
KA
246
247Here are some examples of how to use these:
248
8a93676d
SB
249 =begin html
250
251 <br>Figure 1.<br><IMG SRC="figure1.png"><br>
252
253 =end html
254
255 =begin text
256
257 ---------------
258 | foo |
259 | bar |
260 ---------------
a6006777 261
8a93676d 262 ^^^^ Figure 1. ^^^^
a6006777 263
8a93676d 264 =end text
a6006777 265
8a93676d
SB
266Some format names that formatters currently are known to accept
267include "roff", "man", "latex", "tex", "text", and "html". (Some
268formatters will treat some of these as synonyms.)
a6006777 269
8a93676d
SB
270A format name of "comment" is common for just making notes (presumably
271to yourself) that won't appear in any formatted version of the Pod
272document:
a6006777 273
8a93676d
SB
274 =for comment
275 Make sure that all the available options are documented!
a6006777 276
8a93676d
SB
277Some I<formatnames> will require a leading colon (as in
278C<"=for :formatname">, or
279C<"=begin :formatname" ... "=end :formatname">),
280to signal that the text is not raw data, but instead I<is> Pod text
281(i.e., possibly containing formatting codes) that's just not for
282normal formatting (e.g., may not be a normal-use paragraph, but might
283be for formatting as a footnote).
c7c9f956 284
a179871b 285=item C<=encoding I<encodingname>>
d74e8afc 286X<=encoding> X<encoding>
a179871b
SB
287
288This command is used for declaring the encoding of a document. Most
a0879bf8
KW
289users won't need this; but if your encoding isn't US-ASCII,
290then put a C<=encoding I<encodingname>> command very early in the document so
a179871b
SB
291that pod formatters will know how to decode the document. For
292I<encodingname>, use a name recognized by the L<Encode::Supported>
8f226aee
DW
293module. Some pod formatters may try to guess between a Latin-1 or
294CP-1252 versus
a0879bf8
KW
295UTF-8 encoding, but they may guess wrong. It's best to be explicit if
296you use anything besides strict ASCII. Examples:
297
298 =encoding latin1
a179871b
SB
299
300 =encoding utf8
301
302 =encoding koi8-r
f703fc96 303
a179871b 304 =encoding ShiftJIS
f703fc96 305
a179871b
SB
306 =encoding big5
307
7a9a6fa1
DJ
308C<=encoding> affects the whole document, and must occur only once.
309
e023b52d
KW
310=back
311
312And don't forget, all commands but C<=encoding> last up
8a93676d
SB
313until the end of its I<paragraph>, not its line. So in the
314examples below, you can see that every command needs the blank
556e7d6c
KW
315line after it, to end its paragraph. (And some older Pod translators
316may require the C<=encoding> line to have a following blank line as
317well, even though it should be legal to omit.)
cb1a09d0
AD
318
319Some examples of lists include:
320
8a93676d
SB
321 =over
322
323 =item *
324
325 First item
326
327 =item *
328
329 Second item
330
331 =back
332
333 =over
334
335 =item Foo()
336
337 Description of Foo function
338
339 =item Bar()
cb1a09d0 340
8a93676d 341 Description of Bar function
cb1a09d0 342
8a93676d 343 =back
cb1a09d0 344
cb1a09d0 345
8a93676d 346=head2 Formatting Codes
d74e8afc
ITB
347X<POD, formatting code> X<formatting code>
348X<POD, interior sequence> X<interior sequence>
cb1a09d0 349
8a93676d
SB
350In ordinary paragraphs and in some command paragraphs, various
351formatting codes (a.k.a. "interior sequences") can be used:
cb1a09d0 352
8a93676d
SB
353=for comment
354 "interior sequences" is such an opaque term.
355 Prefer "formatting codes" instead.
cb1a09d0 356
8a93676d 357=over
cb1a09d0 358
8a93676d 359=item C<IE<lt>textE<gt>> -- italic text
d74e8afc 360X<I> X<< IZ<><> >> X<POD, formatting code, italic> X<italic>
cb1a09d0 361
8a93676d
SB
362Used for emphasis ("C<be IE<lt>careful!E<gt>>") and parameters
363("C<redo IE<lt>LABELE<gt>>")
364
365=item C<BE<lt>textE<gt>> -- bold text
d74e8afc 366X<B> X<< BZ<><> >> X<POD, formatting code, bold> X<bold>
8a93676d
SB
367
368Used for switches ("C<perl's BE<lt>-nE<gt> switch>"), programs
369("C<some systems provide a BE<lt>chfnE<gt> for that>"),
370emphasis ("C<be BE<lt>careful!E<gt>>"), and so on
371("C<and that feature is known as BE<lt>autovivificationE<gt>>").
372
373=item C<CE<lt>codeE<gt>> -- code text
d74e8afc 374X<C> X<< CZ<><> >> X<POD, formatting code, code> X<code>
8a93676d
SB
375
376Renders code in a typewriter font, or gives some other indication that
377this represents program text ("C<CE<lt>gmtime($^T)E<gt>>") or some other
378form of computerese ("C<CE<lt>drwxr-xr-xE<gt>>").
379
380=item C<LE<lt>nameE<gt>> -- a hyperlink
d74e8afc 381X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink> X<hyperlink>
8a93676d
SB
382
383There are various syntaxes, listed below. In the syntaxes given,
384C<text>, C<name>, and C<section> cannot contain the characters
385'/' and '|'; and any '<' or '>' should be matched.
386
387=over
388
389=item *
cb1a09d0 390
8a93676d 391C<LE<lt>nameE<gt>>
cb1a09d0 392
8a93676d
SB
393Link to a Perl manual page (e.g., C<LE<lt>Net::PingE<gt>>). Note
394that C<name> should not contain spaces. This syntax
e1020413 395is also occasionally used for references to Unix man pages, as in
8a93676d
SB
396C<LE<lt>crontab(5)E<gt>>.
397
398=item *
399
400C<LE<lt>name/"sec"E<gt>> or C<LE<lt>name/secE<gt>>
401
402Link to a section in other manual page. E.g.,
403C<LE<lt>perlsyn/"For Loops"E<gt>>
404
405=item *
406
b41aadf2 407C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>>
8a93676d
SB
408
409Link to a section in this manual page. E.g.,
410C<LE<lt>/"Object Methods"E<gt>>
a0d0e21e 411
b74bceb9
AB
412=back
413
8a93676d
SB
414A section is started by the named heading or item. For
415example, C<LE<lt>perlvar/$.E<gt>> or C<LE<lt>perlvar/"$."E<gt>> both
416link to the section started by "C<=item $.>" in perlvar. And
417C<LE<lt>perlsyn/For LoopsE<gt>> or C<LE<lt>perlsyn/"For Loops"E<gt>>
418both link to the section started by "C<=head2 For Loops>"
419in perlsyn.
420
421To control what text is used for display, you
422use "C<LE<lt>text|...E<gt>>", as in:
423
424=over
425
426=item *
427
428C<LE<lt>text|nameE<gt>>
429
430Link this text to that manual page. E.g.,
431C<LE<lt>Perl Error Messages|perldiagE<gt>>
432
433=item *
434
435C<LE<lt>text|name/"sec"E<gt>> or C<LE<lt>text|name/secE<gt>>
436
437Link this text to that section in that manual page. E.g.,
8325efec 438C<LE<lt>postfix "if"|perlsyn/"Statement Modifiers"E<gt>>
8a93676d
SB
439
440=item *
441
442C<LE<lt>text|/"sec"E<gt>> or C<LE<lt>text|/secE<gt>>
443or C<LE<lt>text|"sec"E<gt>>
444
445Link this text to that section in this manual page. E.g.,
446C<LE<lt>the various attributes|/"Member Data"E<gt>>
447
448=back
449
450Or you can link to a web page:
451
452=over
453
454=item *
455
456C<LE<lt>scheme:...E<gt>>
457
f6e963e4
RS
458C<LE<lt>text|scheme:...E<gt>>
459
460Links to an absolute URL. For example, C<LE<lt>http://www.perl.org/E<gt>> or
461C<LE<lt>The Perl Home Page|http://www.perl.org/E<gt>>.
8a93676d
SB
462
463=back
464
465=item C<EE<lt>escapeE<gt>> -- a character escape
d74e8afc 466X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape>
8a93676d
SB
467
468Very similar to HTML/XML C<&I<foo>;> "entity references":
469
470=over
471
472=item *
473
474C<EE<lt>ltE<gt>> -- a literal E<lt> (less than)
475
476=item *
477
478C<EE<lt>gtE<gt>> -- a literal E<gt> (greater than)
479
480=item *
481
482C<EE<lt>verbarE<gt>> -- a literal | (I<ver>tical I<bar>)
483
484=item *
485
1f1448d9 486C<EE<lt>solE<gt>> -- a literal / (I<sol>idus)
8a93676d
SB
487
488The above four are optional except in other formatting codes,
489notably C<LE<lt>...E<gt>>, and when preceded by a
490capital letter.
491
492=item *
493
494C<EE<lt>htmlnameE<gt>>
495
496Some non-numeric HTML entity name, such as C<EE<lt>eacuteE<gt>>,
497meaning the same thing as C<&eacute;> in HTML -- i.e., a lowercase
498e with an acute (/-shaped) accent.
499
500=item *
501
502C<EE<lt>numberE<gt>>
503
1a3afb4f 504The ASCII/Latin-1/Unicode character with that number. A
8a93676d
SB
505leading "0x" means that I<number> is hex, as in
506C<EE<lt>0x201EE<gt>>. A leading "0" means that I<number> is octal,
507as in C<EE<lt>075E<gt>>. Otherwise I<number> is interpreted as being
508in decimal, as in C<EE<lt>181E<gt>>.
509
510Note that older Pod formatters might not recognize octal or
511hex numeric escapes, and that many formatters cannot reliably
512render characters above 255. (Some formatters may even have
8f226aee 513to use compromised renderings of Latin-1/CP-1252 characters, like
8a93676d
SB
514rendering C<EE<lt>eacuteE<gt>> as just a plain "e".)
515
516=back
517
518=item C<FE<lt>filenameE<gt>> -- used for filenames
d74e8afc 519X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename>
8a93676d
SB
520
521Typically displayed in italics. Example: "C<FE<lt>.cshrcE<gt>>"
522
523=item C<SE<lt>textE<gt>> -- text contains non-breaking spaces
d74e8afc
ITB
524X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space>
525X<non-breaking space>
8a93676d
SB
526
527This means that the words in I<text> should not be broken
528across lines. Example: S<C<SE<lt>$x ? $y : $zE<gt>>>.
529
530=item C<XE<lt>topic nameE<gt>> -- an index entry
d74e8afc 531X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry>
8a93676d
SB
532
533This is ignored by most formatters, but some may use it for building
534indexes. It always renders as empty-string.
535Example: C<XE<lt>absolutizing relative URLsE<gt>>
536
537=item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code
d74e8afc 538X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null>
8a93676d
SB
539
540This is rarely used. It's one way to get around using an
541EE<lt>...E<gt> code sometimes. For example, instead of
542"C<NEE<lt>ltE<gt>3>" (for "NE<lt>3") you could write
543"C<NZE<lt>E<gt>E<lt>3>" (the "ZE<lt>E<gt>" breaks up the "N" and
544the "E<lt>" so they can't be considered
6c1c521a 545the part of a (fictitious) "NE<lt>...E<gt>" code).
8a93676d 546
ba77fc59
KW
547Another use is to indicate that I<stuff> in C<=item ZE<lt>E<gt>I<stuff...>>
548is not to be considered to be a bullet or number. For example,
549without the C<ZE<lt>E<gt>>, the line
550
551 =item Z<>500 Server error
552
553could possibly be parsed as an item in a numbered list when it isn't
554meant to be.
555
556Still another use is to maintain visual space between C<=item> lines.
557If you specify
558
559 =item foo
560
561 =item bar
562
563it will typically get rendered as
564
565 foo
566 bar
567
568That may be what you want, but if what you really want is
569
570 foo
571
572 bar
573
574you can use C<ZE<lt>E<gt>> to accomplish that
575
576 =item foo
577
578 Z<>
579
580 =item bar
581
8a93676d
SB
582=for comment
583 This was formerly explained as a "zero-width character". But it in
584 most parser models, it parses to nothing at all, as opposed to parsing
585 as if it were a E<zwnj> or E<zwj>, which are REAL zero-width characters.
586 So "width" and "character" are exactly the wrong words.
587
588=back
589
590Most of the time, you will need only a single set of angle brackets to
591delimit the beginning and end of formatting codes. However,
592sometimes you will want to put a real right angle bracket (a
593greater-than sign, '>') inside of a formatting code. This is particularly
594common when using a formatting code to provide a different font-type for a
595snippet of code. As with all things in Perl, there is more than
596one way to do it. One way is to simply escape the closing bracket
597using an C<E> code:
5455df32
GS
598
599 C<$a E<lt>=E<gt> $b>
600
601This will produce: "C<$a E<lt>=E<gt> $b>"
602
8a93676d 603A more readable, and perhaps more "plain" way is to use an alternate
8162142b
JD
604set of delimiters that doesn't require a single ">" to be escaped.
605Doubled angle brackets ("<<" and ">>") may be used I<if and only if there is
8a93676d
SB
606whitespace right after the opening delimiter and whitespace right
607before the closing delimiter!> For example, the following will
608do the trick:
d74e8afc 609X<POD, formatting code, escaping with multiple brackets>
5455df32
GS
610
611 C<< $a <=> $b >>
612
613In fact, you can use as many repeated angle-brackets as you like so
614long as you have the same number of them in the opening and closing
615delimiters, and make sure that whitespace immediately follows the last
8a93676d
SB
616'<' of the opening delimiter, and immediately precedes the first '>'
617of the closing delimiter. (The whitespace is ignored.) So the
618following will also work:
d74e8afc 619X<POD, formatting code, escaping with multiple brackets>
5455df32
GS
620
621 C<<< $a <=> $b >>>
8a93676d 622 C<<<< $a <=> $b >>>>
5455df32 623
8a93676d
SB
624And they all mean exactly the same as this:
625
626 C<$a E<lt>=E<gt> $b>
627
a3d78747
RS
628The multiple-bracket form does not affect the interpretation of the contents of
629the formatting code, only how it must end. That means that the examples above
630are also exactly the same as this:
631
632 C<< $a E<lt>=E<gt> $b >>
633
8a93676d
SB
634As a further example, this means that if you wanted to put these bits of
635code in C<C> (code) style:
636
637 open(X, ">>thing.dat") || die $!
638 $foo->bar();
639
640you could do it like so:
641
642 C<<< open(X, ">>thing.dat") || die $! >>>
643 C<< $foo->bar(); >>
5455df32 644
8a93676d
SB
645which is presumably easier to read than the old way:
646
647 C<open(X, "E<gt>E<gt>thing.dat") || die $!>
c58e3c1c 648 C<$foo-E<gt>bar();>
8a93676d
SB
649
650This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
651and any other pod2xxx or Pod::Xxxx translators that use
652Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
5455df32 653
b74bceb9 654=head2 The Intent
d74e8afc 655X<POD, intent of>
3141265f 656
8a93676d
SB
657The intent is simplicity of use, not power of expression. Paragraphs
658look like paragraphs (block format), so that they stand out
659visually, and so that I could run them through C<fmt> easily to reformat
660them (that's F7 in my version of B<vi>, or Esc Q in my version of
661B<emacs>). I wanted the translator to always leave the C<'> and C<`> and
662C<"> quotes alone, in verbatim mode, so I could slurp in a
663working program, shift it over four spaces, and have it print out, er,
664verbatim. And presumably in a monospace font.
665
666The Pod format is not necessarily sufficient for writing a book. Pod
667is just meant to be an idiot-proof common source for nroff, HTML,
668TeX, and other markup languages, as used for online
669documentation. Translators exist for B<pod2text>, B<pod2html>,
670B<pod2man> (that's for nroff(1) and troff(1)), B<pod2latex>, and
671B<pod2fm>. Various others are available in CPAN.
672
a0d0e21e 673
b74bceb9 674=head2 Embedding Pods in Perl Modules
d74e8afc 675X<POD, embedding>
4633a7c4 676
13d0d101
JK
677You can embed Pod documentation in your Perl modules and scripts. Start
678your documentation with an empty line, a "=head1" command at the
679beginning, and end it with a "=cut" command and an empty line. The
680B<perl> executable will ignore the Pod text. You can place a Pod
681statement where B<perl> expects the beginning of a new statement, but
682not within a statement, as that would result in an error. See any of
683the supplied library modules for examples.
684
685If you're going to put your Pod at the end of the file, and you're using
686an C<__END__> or C<__DATA__> cut mark, make sure to put an empty line there
687before the first Pod command.
cb1a09d0 688
8a93676d 689 __END__
cb1a09d0 690
8a93676d 691 =head1 NAME
cb1a09d0 692
8a93676d 693 Time::Local - efficiently compute time from local and GMT time
cb1a09d0 694
8a93676d
SB
695Without that empty line before the "=head1", many translators wouldn't
696have recognized the "=head1" as starting a Pod block.
cb1a09d0 697
8a93676d 698=head2 Hints for Writing Pod
1294c5d8 699
8a93676d 700=over
1294c5d8
JM
701
702=item *
d74e8afc 703X<podchecker> X<POD, validating>
1294c5d8 704
8a93676d
SB
705The B<podchecker> command is provided for checking Pod syntax for errors
706and warnings. For example, it checks for completely blank lines in
707Pod blocks and for unknown commands and formatting codes. You should
708still also pass your document through one or more translators and proofread
709the result, or print out the result and proofread that. Some of the
710problems found may be bugs in the translators, which you may or may not
711wish to work around.
1294c5d8
JM
712
713=item *
714
8a93676d 715If you're more familiar with writing in HTML than with writing in Pod, you
210b36aa 716can try your hand at writing documentation in simple HTML, and converting
8a93676d
SB
717it to Pod with the experimental L<Pod::HTML2Pod|Pod::HTML2Pod> module,
718(available in CPAN), and looking at the resulting code. The experimental
719L<Pod::PXML|Pod::PXML> module in CPAN might also be useful.
720
721=item *
722
723Many older Pod translators require the lines before every Pod
724command and after every Pod command (including "=cut"!) to be a blank
725line. Having something like this:
726
727 # - - - - - - - - - - - -
728 =item $firecracker->boom()
210b36aa 729
8a93676d
SB
730 This noisily detonates the firecracker object.
731 =cut
732 sub boom {
733 ...
734
735...will make such Pod translators completely fail to see the Pod block
736at all.
737
738Instead, have it like this:
739
740 # - - - - - - - - - - - -
210b36aa 741
8a93676d 742 =item $firecracker->boom()
210b36aa 743
8a93676d 744 This noisily detonates the firecracker object.
210b36aa 745
8a93676d 746 =cut
210b36aa 747
8a93676d
SB
748 sub boom {
749 ...
750
751=item *
752
753Some older Pod translators require paragraphs (including command
754paragraphs like "=head2 Functions") to be separated by I<completely>
755empty lines. If you have an apparently empty line with some spaces
756on it, this might not count as a separator for those translators, and
757that could cause odd formatting.
758
759=item *
1294c5d8 760
8a93676d
SB
761Older translators might add wording around an LE<lt>E<gt> link, so that
762C<LE<lt>Foo::BarE<gt>> may become "the Foo::Bar manpage", for example.
763So you shouldn't write things like C<the LE<lt>fooE<gt>
ac036724 764documentation>, if you want the translated document to read sensibly.
765Instead, write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or
8a93676d
SB
766C<LE<lt>the Foo::Bar documentation|Foo::BarE<gt>>, to control how the
767link comes out.
b74bceb9 768
1294c5d8
JM
769=item *
770
8a93676d
SB
771Going past the 70th column in a verbatim block might be ungracefully
772wrapped by some formatters.
1294c5d8
JM
773
774=back
775
cb1a09d0
AD
776=head1 SEE ALSO
777
8a93676d
SB
778L<perlpodspec>, L<perlsyn/"PODs: Embedded Documentation">,
779L<perlnewmod>, L<perldoc>, L<pod2html>, L<pod2man>, L<podchecker>.
4633a7c4 780
cb1a09d0 781=head1 AUTHOR
a0d0e21e 782
8a93676d 783Larry Wall, Sean M. Burke
a0d0e21e 784
8a93676d 785=cut