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