1PERLPODSPEC(1) Perl Programmers Reference Guide PERLPODSPEC(1)
2
6 perlpodspec - Plain Old Documentation: format specification and notes
7
9 This document is detailed notes on the Pod markup language. Most peo‐
10 ple will only have to read perlpod to know how to write in Pod, but
11 this document may answer some incidental questions to do with parsing
12 and rendering Pod.
13 In this document, "must" / "must not", "should" / "should not", and
15 "may" have their conventional (cf. RFC 2119) meanings: "X must do Y"
16 means that if X doesn't do Y, it's against this specification, and
17 should really be fixed. "X should do Y" means that it's recommended,
18 but X may fail to do Y, if there's a good reason. "X may do Y" is
19 merely a note that X can do Y at will (although it is up to the reader
20 to detect any connotation of "and I think it would be nice if X did Y"
21 versus "it wouldn't really bother me if X did Y").
22 Notably, when I say "the parser should do Y", the parser may fail to do
24 Y, if the calling application explicitly requests that the parser not
25 do Y. I often phrase this as "the parser should, by default, do Y."
26 This doesn't require the parser to provide an option for turning off
27 whatever feature Y is (like expanding tabs in verbatim paragraphs),
28 although it implicates that such an option may be provided.
29
31 Pod is embedded in files, typically Perl source files -- although you
32 can write a file that's nothing but Pod.
33 A line in a file consists of zero or more non-newline characters, ter‐
35 minated by either a newline or the end of the file.
36 A newline sequence is usually a platform-dependent concept, but Pod
38 parsers should understand it to mean any of CR (ASCII 13), LF (ASCII
39 10), or a CRLF (ASCII 13 followed immediately by ASCII 10), in addition
40 to any other system-specific meaning. The first CR/CRLF/LF sequence in
41 the file may be used as the basis for identifying the newline sequence
42 for parsing the rest of the file.
43 A blank line is a line consisting entirely of zero or more spaces
45 (ASCII 32) or tabs (ASCII 9), and terminated by a newline or
46 end-of-file. A non-blank line is a line containing one or more charac‐
47 ters other than space or tab (and terminated by a newline or
48 end-of-file).
49 (Note: Many older Pod parsers did not accept a line consisting of spa‐
51 ces/tabs and then a newline as a blank line -- the only lines they con‐
52 sidered blank were lines consisting of no characters at all, terminated
53 by a newline.)
54 Whitespace is used in this document as a blanket term for spaces, tabs,
56 and newline sequences. (By itself, this term usually refers to literal
57 whitespace. That is, sequences of whitespace characters in Pod source,
58 as opposed to "E<32>", which is a formatting code that denotes a white‐
59 space character.)
60 A Pod parser is a module meant for parsing Pod (regardless of whether
62 this involves calling callbacks or building a parse tree or directly
63 formatting it). A Pod formatter (or Pod translator) is a module or
64 program that converts Pod to some other format (HTML, plaintext, TeX,
65 PostScript, RTF). A Pod processor might be a formatter or translator,
66 or might be a program that does something else with the Pod (like word‐
67 counting it, scanning for index points, etc.).
68 Pod content is contained in Pod blocks. A Pod block starts with a line
70 that matches <m/\A=[a-zA-Z]/>, and continues up to the next line that
71 matches "m/\A=cut/" -- or up to the end of the file, if there is no
72 "m/\A=cut/" line.
73 Within a Pod block, there are Pod paragraphs. A Pod paragraph consists
75 of non-blank lines of text, separated by one or more blank lines.
76 For purposes of Pod processing, there are four types of paragraphs in a
78 Pod block:
79 · A command paragraph (also called a "directive"). The first line of
81 this paragraph must match "m/\A=[a-zA-Z]/". Command paragraphs are
82 typically one line, as in:
83 =head1 NOTES
85 =item *
87 But they may span several (non-blank) lines:
89 =for comment
91 Hm, I wonder what it would look like if
92 you tried to write a BNF for Pod from this.
93 =head3 Dr. Strangelove, or: How I Learned to
95 Stop Worrying and Love the Bomb
96 Some command paragraphs allow formatting codes in their content
98 (i.e., after the part that matches "m/\A=[a-zA-Z]\S*\s*/"), as in:
99 =head1 Did You Remember to C<use strict;>?
101 In other words, the Pod processing handler for "head1" will apply
103 the same processing to "Did You Remember to C<use strict;>?" that
104 it would to an ordinary paragraph -- i.e., formatting codes (like
105 "C<...>") are parsed and presumably formatted appropriately, and
106 whitespace in the form of literal spaces and/or tabs is not signif‐
107 icant.
108 · A verbatim paragraph. The first line of this paragraph must be a
110 literal space or tab, and this paragraph must not be inside a
111 "=begin identifier", ... "=end identifier" sequence unless "identi‐
112 fier" begins with a colon (":"). That is, if a paragraph starts
113 with a literal space or tab, but is inside a "=begin identifier",
114 ... "=end identifier" region, then it's a data paragraph, unless
115 "identifier" begins with a colon.
116 Whitespace is significant in verbatim paragraphs (although, in pro‐
118 cessing, tabs are probably expanded).
119 · An ordinary paragraph. A paragraph is an ordinary paragraph if its
121 first line matches neither "m/\A=[a-zA-Z]/" nor "m/\A[ \t]/", and
122 if it's not inside a "=begin identifier", ... "=end identifier"
123 sequence unless "identifier" begins with a colon (":").
124 · A data paragraph. This is a paragraph that is inside a "=begin
126 identifier" ... "=end identifier" sequence where "identifier" does
127 not begin with a literal colon (":"). In some sense, a data para‐
128 graph is not part of Pod at all (i.e., effectively it's
129 "out-of-band"), since it's not subject to most kinds of Pod pars‐
130 ing; but it is specified here, since Pod parsers need to be able to
131 call an event for it, or store it in some form in a parse tree, or
132 at least just parse around it.
133 For example: consider the following paragraphs:
135 # <- that's the 0th column
137 =head1 Foo
139 Stuff
141 $foo->bar
143 =cut
145 Here, "=head1 Foo" and "=cut" are command paragraphs because the first
147 line of each matches "m/\A=[a-zA-Z]/". "[space][space]$foo->bar" is a
148 verbatim paragraph, because its first line starts with a literal white‐
149 space character (and there's no "=begin"..."=end" region around).
150 The "=begin identifier" ... "=end identifier" commands stop paragraphs
152 that they surround from being parsed as data or verbatim paragraphs, if
153 identifier doesn't begin with a colon. This is discussed in detail in
154 the section "About Data Paragraphs and "=begin/=end" Regions".
155
157 This section is intended to supplement and clarify the discussion in
158 "Command Paragraph" in perlpod. These are the currently recognized Pod
159 commands:
160 "=head1", "=head2", "=head3", "=head4"
162 This command indicates that the text in the remainder of the para‐
163 graph is a heading. That text may contain formatting codes. Exam‐
164 ples:
165 =head1 Object Attributes
167 =head3 What B<Not> to Do!
169 "=pod"
171 This command indicates that this paragraph begins a Pod block. (If
172 we are already in the middle of a Pod block, this command has no
173 effect at all.) If there is any text in this command paragraph
174 after "=pod", it must be ignored. Examples:
175 =pod
177 This is a plain Pod paragraph.
179 =pod This text is ignored.
181 "=cut"
183 This command indicates that this line is the end of this previously
184 started Pod block. If there is any text after "=cut" on the line,
185 it must be ignored. Examples:
186 =cut
188 =cut The documentation ends here.
190 =cut
192 # This is the first line of program text.
193 sub foo { # This is the second.
194 It is an error to try to start a Pod block with a "=cut" command.
196 In that case, the Pod processor must halt parsing of the input
197 file, and must by default emit a warning.
198 "=over"
200 This command indicates that this is the start of a list/indent
201 region. If there is any text following the "=over", it must con‐
202 sist of only a nonzero positive numeral. The semantics of this
203 numeral is explained in the "About =over...=back Regions" section,
204 further below. Formatting codes are not expanded. Examples:
205 =over 3
207 =over 3.5
209 =over
211 "=item"
213 This command indicates that an item in a list begins here. Format‐
214 ting codes are processed. The semantics of the (optional) text in
215 the remainder of this paragraph are explained in the "About
216 =over...=back Regions" section, further below. Examples:
217 =item
219 =item *
221 =item *
223 =item 14
225 =item 3.
227 =item C<< $thing->stuff(I<dodad>) >>
229 =item For transporting us beyond seas to be tried for pretended
231 offenses
232 =item He is at this time transporting large armies of foreign
234 mercenaries to complete the works of death, desolation and
235 tyranny, already begun with circumstances of cruelty and perfidy
236 scarcely paralleled in the most barbarous ages, and totally
237 unworthy the head of a civilized nation.
238 "=back"
240 This command indicates that this is the end of the region begun by
241 the most recent "=over" command. It permits no text after the
242 "=back" command.
243 "=begin formatname"
245 This marks the following paragraphs (until the matching "=end for‐
246 matname") as being for some special kind of processing. Unless
247 "formatname" begins with a colon, the contained non-command para‐
248 graphs are data paragraphs. But if "formatname" does begin with a
249 colon, then non-command paragraphs are ordinary paragraphs or data
250 paragraphs. This is discussed in detail in the section "About Data
251 Paragraphs and "=begin/=end" Regions".
252 It is advised that formatnames match the regexp
254 "m/\A:?[-a-zA-Z0-9_]+\z/". Implementors should anticipate future
255 expansion in the semantics and syntax of the first parameter to
256 "=begin"/"=end"/"=for".
257 "=end formatname"
259 This marks the end of the region opened by the matching "=begin
260 formatname" region. If "formatname" is not the formatname of the
261 most recent open "=begin formatname" region, then this is an error,
262 and must generate an error message. This is discussed in detail in
263 the section "About Data Paragraphs and "=begin/=end" Regions".
264 "=for formatname text..."
266 This is synonymous with:
267 =begin formatname
269 text...
271 =end formatname
273 That is, it creates a region consisting of a single paragraph; that
275 paragraph is to be treated as a normal paragraph if "formatname"
276 begins with a ":"; if "formatname" doesn't begin with a colon, then
277 "text..." will constitute a data paragraph. There is no way to use
278 "=for formatname text..." to express "text..." as a verbatim para‐
279 graph.
280 "=encoding encodingname"
282 This command, which should occur early in the document (at least
283 before any non-US-ASCII data!), declares that this document is
284 encoded in the encoding encodingname, which must be an encoding
285 name that Encoding recognizes. (Encoding's list of supported
286 encodings, in Encoding::Supported, is useful here.) If the Pod
287 parser cannot decode the declared encoding, it should emit a warn‐
288 ing and may abort parsing the document altogether.
289 A document having more than one "=encoding" line should be consid‐
291 ered an error. Pod processors may silently tolerate this if the
292 not-first "=encoding" lines are just duplicates of the first one
293 (e.g., if there's a "=use utf8" line, and later on another "=use
294 utf8" line). But Pod processors should complain if there are con‐
295 tradictory "=encoding" lines in the same document (e.g., if there
296 is a "=encoding utf8" early in the document and "=encoding big5"
297 later). Pod processors that recognize BOMs may also complain if
298 they see an "=encoding" line that contradicts the BOM (e.g., if a
299 document with a UTF-16LE BOM has an "=encoding shiftjis" line).
300 If a Pod processor sees any command other than the ones listed above
302 (like "=head", or "=haed1", or "=stuff", or "=cuttlefish", or "=w123"),
303 that processor must by default treat this as an error. It must not
304 process the paragraph beginning with that command, must by default warn
305 of this as an error, and may abort the parse. A Pod parser may allow a
306 way for particular applications to add to the above list of known com‐
307 mands, and to stipulate, for each additional command, whether format‐
308 ting codes should be processed.
309 Future versions of this specification may add additional commands.
311
313 (Note that in previous drafts of this document and of perlpod, format‐
314 ting codes were referred to as "interior sequences", and this term may
315 still be found in the documentation for Pod parsers, and in error mes‐
316 sages from Pod processors.)
317 There are two syntaxes for formatting codes:
319 · A formatting code starts with a capital letter (just US-ASCII
321 [A-Z]) followed by a "<", any number of characters, and ending with
322 the first matching ">". Examples:
323 That's what I<you> think!
325 What's C<dump()> for?
327 X<C<chmod> and C<unlink()> Under Different Operating Systems>
329 · A formatting code starts with a capital letter (just US-ASCII
331 [A-Z]) followed by two or more "<"'s, one or more whitespace char‐
332 acters, any number of characters, one or more whitespace charac‐
333 ters, and ending with the first matching sequence of two or more
334 ">"'s, where the number of ">"'s equals the number of "<"'s in the
335 opening of this formatting code. Examples:
336 That's what I<< you >> think!
338 C<<< open(X, ">>thing.dat") ⎪⎪ die $! >>>
340 B<< $foo->bar(); >>
342 With this syntax, the whitespace character(s) after the "C<<<" and
344 before the ">>" (or whatever letter) are not renderable -- they do
345 not signify whitespace, are merely part of the formatting codes
346 themselves. That is, these are all synonymous:
347 C<thing>
349 C<< thing >>
350 C<< thing >>
351 C<<< thing >>>
352 C<<<<
353 thing
354 >>>>
355 and so on.
357 In parsing Pod, a notably tricky part is the correct parsing of (poten‐
359 tially nested!) formatting codes. Implementors should consult the code
360 in the "parse_text" routine in Pod::Parser as an example of a correct
361 implementation.
362 "I<text>" -- italic text
364 See the brief discussion in "Formatting Codes" in perlpod.
365 "B<text>" -- bold text
367 See the brief discussion in "Formatting Codes" in perlpod.
368 "C<code>" -- code text
370 See the brief discussion in "Formatting Codes" in perlpod.
371 "F<filename>" -- style for filenames
373 See the brief discussion in "Formatting Codes" in perlpod.
374 "X<topic name>" -- an index entry
376 See the brief discussion in "Formatting Codes" in perlpod.
377 This code is unusual in that most formatters completely discard
379 this code and its content. Other formatters will render it with
380 invisible codes that can be used in building an index of the cur‐
381 rent document.
382 "Z<>" -- a null (zero-effect) formatting code
384 Discussed briefly in "Formatting Codes" in perlpod.
385 This code is unusual is that it should have no content. That is, a
387 processor may complain if it sees "Z<potatoes>". Whether or not it
388 complains, the potatoes text should ignored.
389 "L<name>" -- a hyperlink
391 The complicated syntaxes of this code are discussed at length in
392 "Formatting Codes" in perlpod, and implementation details are dis‐
393 cussed below, in "About L<...> Codes". Parsing the contents of
394 L<content> is tricky. Notably, the content has to be checked for
395 whether it looks like a URL, or whether it has to be split on lit‐
396 eral "⎪" and/or "/" (in the right order!), and so on, before E<...>
397 codes are resolved.
398 "E<escape>" -- a character escape
400 See "Formatting Codes" in perlpod, and several points in "Notes on
401 Implementing Pod Processors".
402 "S<text>" -- text contains non-breaking spaces
404 This formatting code is syntactically simple, but semantically com‐
405 plex. What it means is that each space in the printable content of
406 this code signifies a non-breaking space.
407 Consider:
409 C<$x ? $y : $z>
411 S<C<$x ? $y : $z>>
413 Both signify the monospace (c[ode] style) text consisting of "$x",
415 one space, "?", one space, ":", one space, "$z". The difference is
416 that in the latter, with the S code, those spaces are not "normal"
417 spaces, but instead are non-breaking spaces.
418 If a Pod processor sees any formatting code other than the ones listed
420 above (as in "N<...>", or "Q<...>", etc.), that processor must by
421 default treat this as an error. A Pod parser may allow a way for par‐
422 ticular applications to add to the above list of known formatting
423 codes; a Pod parser might even allow a way to stipulate, for each addi‐
424 tional command, whether it requires some form of special processing, as
425 L<...> does.
426 Future versions of this specification may add additional formatting
428 codes.
429 Historical note: A few older Pod processors would not see a ">" as
431 closing a "C<" code, if the ">" was immediately preceded by a "-".
432 This was so that this:
433 C<$foo->bar>
435 would parse as equivalent to this:
437 C<$foo-E<gt>bar>
439 instead of as equivalent to a "C" formatting code containing only
441 "$foo-", and then a "bar>" outside the "C" formatting code. This prob‐
442 lem has since been solved by the addition of syntaxes like this:
443 C<< $foo->bar >>
445 Compliant parsers must not treat "->" as special.
447 Formatting codes absolutely cannot span paragraphs. If a code is
449 opened in one paragraph, and no closing code is found by the end of
450 that paragraph, the Pod parser must close that formatting code, and
451 should complain (as in "Unterminated I code in the paragraph starting
452 at line 123: 'Time objects are not...'"). So these two paragraphs:
453 I<I told you not to do this!
455 Don't make me say it again!>
457 ...must not be parsed as two paragraphs in italics (with the I code
459 starting in one paragraph and starting in another.) Instead, the first
460 paragraph should generate a warning, but that aside, the above code
461 must parse as if it were:
462 I<I told you not to do this!>
464 Don't make me say it again!E<gt>
466 (In SGMLish jargon, all Pod commands are like block-level elements,
468 whereas all Pod formatting codes are like inline-level elements.)
469
471 The following is a long section of miscellaneous requirements and sug‐
472 gestions to do with Pod processing.
473 · Pod formatters should tolerate lines in verbatim blocks that are of
475 any length, even if that means having to break them (possibly sev‐
476 eral times, for very long lines) to avoid text running off the side
477 of the page. Pod formatters may warn of such line-breaking. Such
478 warnings are particularly appropriate for lines are over 100 char‐
479 acters long, which are usually not intentional.
480 · Pod parsers must recognize all of the three well-known newline for‐
482 mats: CR, LF, and CRLF. See perlport.
483 · Pod parsers should accept input lines that are of any length.
485 · Since Perl recognizes a Unicode Byte Order Mark at the start of
487 files as signaling that the file is Unicode encoded as in UTF-16
488 (whether big-endian or little-endian) or UTF-8, Pod parsers should
489 do the same. Otherwise, the character encoding should be under‐
490 stood as being UTF-8 if the first highbit byte sequence in the file
491 seems valid as a UTF-8 sequence, or otherwise as Latin-1.
492 Future versions of this specification may specify how Pod can
494 accept other encodings. Presumably treatment of other encodings in
495 Pod parsing would be as in XML parsing: whatever the encoding
496 declared by a particular Pod file, content is to be stored in mem‐
497 ory as Unicode characters.
498 · The well known Unicode Byte Order Marks are as follows: if the
500 file begins with the two literal byte values 0xFE 0xFF, this is the
501 BOM for big-endian UTF-16. If the file begins with the two literal
502 byte value 0xFF 0xFE, this is the BOM for little-endian UTF-16. If
503 the file begins with the three literal byte values 0xEF 0xBB 0xBF,
504 this is the BOM for UTF-8.
505 · A naive but sufficient heuristic for testing the first highbit
507 byte-sequence in a BOM-less file (whether in code or in Pod!), to
508 see whether that sequence is valid as UTF-8 (RFC 2279) is to check
509 whether that the first byte in the sequence is in the range 0xC0 -
510 0xFD and whether the next byte is in the range 0x80 - 0xBF. If so,
511 the parser may conclude that this file is in UTF-8, and all highbit
512 sequences in the file should be assumed to be UTF-8. Otherwise the
513 parser should treat the file as being in Latin-1. In the unlikely
514 circumstance that the first highbit sequence in a truly non-UTF-8
515 file happens to appear to be UTF-8, one can cater to our heuristic
516 (as well as any more intelligent heuristic) by prefacing that line
517 with a comment line containing a highbit sequence that is clearly
518 not valid as UTF-8. A line consisting of simply "#", an e-acute,
519 and any non-highbit byte, is sufficient to establish this file's
520 encoding.
521 · This document's requirements and suggestions about encodings do not
523 apply to Pod processors running on non-ASCII platforms, notably
524 EBCDIC platforms.
525 · Pod processors must treat a "=for [label] [content...]" paragraph
527 as meaning the same thing as a "=begin [label]" paragraph, content,
528 and an "=end [label]" paragraph. (The parser may conflate these
529 two constructs, or may leave them distinct, in the expectation that
530 the formatter will nevertheless treat them the same.)
531 · When rendering Pod to a format that allows comments (i.e., to
533 nearly any format other than plaintext), a Pod formatter must
534 insert comment text identifying its name and version number, and
535 the name and version numbers of any modules it might be using to
536 process the Pod. Minimal examples:
537 %% POD::Pod2PS v3.14159, using POD::Parser v1.92
539 <!-- Pod::HTML v3.14159, using POD::Parser v1.92 -->
541 {\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08}
543 .\" Pod::Man version 3.14159, using POD::Parser version 1.92
545 Formatters may also insert additional comments, including: the
547 release date of the Pod formatter program, the contact address for
548 the author(s) of the formatter, the current time, the name of input
549 file, the formatting options in effect, version of Perl used, etc.
550 Formatters may also choose to note errors/warnings as comments,
552 besides or instead of emitting them otherwise (as in messages to
553 STDERR, or "die"ing).
554 · Pod parsers may emit warnings or error messages ("Unknown E code
556 E<zslig>!") to STDERR (whether through printing to STDERR, or
557 "warn"ing/"carp"ing, or "die"ing/"croak"ing), but must allow sup‐
558 pressing all such STDERR output, and instead allow an option for
559 reporting errors/warnings in some other way, whether by triggering
560 a callback, or noting errors in some attribute of the document
561 object, or some similarly unobtrusive mechanism -- or even by
562 appending a "Pod Errors" section to the end of the parsed form of
563 the document.
564 · In cases of exceptionally aberrant documents, Pod parsers may abort
566 the parse. Even then, using "die"ing/"croak"ing is to be avoided;
567 where possible, the parser library may simply close the input file
568 and add text like "*** Formatting Aborted ***" to the end of the
569 (partial) in-memory document.
570 · In paragraphs where formatting codes (like E<...>, B<...>) are
572 understood (i.e., not verbatim paragraphs, but including ordinary
573 paragraphs, and command paragraphs that produce renderable text,
574 like "=head1"), literal whitespace should generally be considered
575 "insignificant", in that one literal space has the same meaning as
576 any (nonzero) number of literal spaces, literal newlines, and lit‐
577 eral tabs (as long as this produces no blank lines, since those
578 would terminate the paragraph). Pod parsers should compact literal
579 whitespace in each processed paragraph, but may provide an option
580 for overriding this (since some processing tasks do not require
581 it), or may follow additional special rules (for example, specially
582 treating period-space-space or period-newline sequences).
583 · Pod parsers should not, by default, try to coerce apostrophe (')
585 and quote (") into smart quotes (little 9's, 66's, 99's, etc), nor
586 try to turn backtick (`) into anything else but a single backtick
587 character (distinct from an openquote character!), nor "--" into
588 anything but two minus signs. They must never do any of those
589 things to text in C<...> formatting codes, and never ever to text
590 in verbatim paragraphs.
591 · When rendering Pod to a format that has two kinds of hyphens (-),
593 one that's a non-breaking hyphen, and another that's a breakable
594 hyphen (as in "object-oriented", which can be split across lines as
595 "object-", newline, "oriented"), formatters are encouraged to gen‐
596 erally translate "-" to non-breaking hyphen, but may apply heuris‐
597 tics to convert some of these to breaking hyphens.
598 · Pod formatters should make reasonable efforts to keep words of Perl
600 code from being broken across lines. For example, "Foo::Bar" in
601 some formatting systems is seen as eligible for being broken across
602 lines as "Foo::" newline "Bar" or even "Foo::-" newline "Bar".
603 This should be avoided where possible, either by disabling all
604 line-breaking in mid-word, or by wrapping particular words with
605 internal punctuation in "don't break this across lines" codes
606 (which in some formats may not be a single code, but might be a
607 matter of inserting non-breaking zero-width spaces between every
608 pair of characters in a word.)
609 · Pod parsers should, by default, expand tabs in verbatim paragraphs
611 as they are processed, before passing them to the formatter or
612 other processor. Parsers may also allow an option for overriding
613 this.
614 · Pod parsers should, by default, remove newlines from the end of
616 ordinary and verbatim paragraphs before passing them to the format‐
617 ter. For example, while the paragraph you're reading now could be
618 considered, in Pod source, to end with (and contain) the newline(s)
619 that end it, it should be processed as ending with (and containing)
620 the period character that ends this sentence.
621 · Pod parsers, when reporting errors, should make some effort to
623 report an approximate line number ("Nested E<>'s in Paragraph #52,
624 near line 633 of Thing/Foo.pm!"), instead of merely noting the
625 paragraph number ("Nested E<>'s in Paragraph #52 of
626 Thing/Foo.pm!"). Where this is problematic, the paragraph number
627 should at least be accompanied by an excerpt from the paragraph
628 ("Nested E<>'s in Paragraph #52 of Thing/Foo.pm, which begins
629 'Read/write accessor for the C<interest rate> attribute...'").
630 · Pod parsers, when processing a series of verbatim paragraphs one
632 after another, should consider them to be one large verbatim para‐
633 graph that happens to contain blank lines. I.e., these two lines,
634 which have a blank line between them:
635 use Foo;
637 print Foo->VERSION
639 should be unified into one paragraph ("\tuse Foo;\n\n\tprint
641 Foo->VERSION") before being passed to the formatter or other pro‐
642 cessor. Parsers may also allow an option for overriding this.
643 While this might be too cumbersome to implement in event-based Pod
645 parsers, it is straightforward for parsers that return parse trees.
646 · Pod formatters, where feasible, are advised to avoid splitting
648 short verbatim paragraphs (under twelve lines, say) across pages.
649 · Pod parsers must treat a line with only spaces and/or tabs on it as
651 a "blank line" such as separates paragraphs. (Some older parsers
652 recognized only two adjacent newlines as a "blank line" but would
653 not recognize a newline, a space, and a newline, as a blank line.
654 This is noncompliant behavior.)
655 · Authors of Pod formatters/processors should make every effort to
657 avoid writing their own Pod parser. There are already several in
658 CPAN, with a wide range of interface styles -- and one of them,
659 Pod::Parser, comes with modern versions of Perl.
660 · Characters in Pod documents may be conveyed either as literals, or
662 by number in E<n> codes, or by an equivalent mnemonic, as in
663 E<eacute> which is exactly equivalent to E<233>.
664 Characters in the range 32-126 refer to those well known US-ASCII
666 characters (also defined there by Unicode, with the same meaning),
667 which all Pod formatters must render faithfully. Characters in the
668 ranges 0-31 and 127-159 should not be used (neither as literals,
669 nor as E<number> codes), except for the literal byte-sequences for
670 newline (13, 13 10, or 10), and tab (9).
671 Characters in the range 160-255 refer to Latin-1 characters (also
673 defined there by Unicode, with the same meaning). Characters above
674 255 should be understood to refer to Unicode characters.
675 · Be warned that some formatters cannot reliably render characters
677 outside 32-126; and many are able to handle 32-126 and 160-255, but
678 nothing above 255.
679 · Besides the well-known "E<lt>" and "E<gt>" codes for less-than and
681 greater-than, Pod parsers must understand "E<sol>" for "/"
682 (solidus, slash), and "E<verbar>" for "⎪" (vertical bar, pipe).
683 Pod parsers should also understand "E<lchevron>" and "E<rchevron>"
684 as legacy codes for characters 171 and 187, i.e., "left-pointing
685 double angle quotation mark" = "left pointing guillemet" and
686 "right-pointing double angle quotation mark" = "right pointing
687 guillemet". (These look like little "<<" and ">>", and they are
688 now preferably expressed with the HTML/XHTML codes "E<laquo>" and
689 "E<raquo>".)
690 · Pod parsers should understand all "E<html>" codes as defined in the
692 entity declarations in the most recent XHTML specification at
693 "www.W3.org". Pod parsers must understand at least the entities
694 that define characters in the range 160-255 (Latin-1). Pod
695 parsers, when faced with some unknown "E<identifier>" code,
696 shouldn't simply replace it with nullstring (by default, at least),
697 but may pass it through as a string consisting of the literal char‐
698 acters E, less-than, identifier, greater-than. Or Pod parsers may
699 offer the alternative option of processing such unknown "E<identi‐
700 fier>" codes by firing an event especially for such codes, or by
701 adding a special node-type to the in-memory document tree. Such
702 "E<identifier>" may have special meaning to some processors, or
703 some processors may choose to add them to a special error report.
704 · Pod parsers must also support the XHTML codes "E<quot>" for charac‐
706 ter 34 (doublequote, "), "E<amp>" for character 38 (ampersand, &),
707 and "E<apos>" for character 39 (apostrophe, ').
708 · Note that in all cases of "E<whatever>", whatever (whether an html‐
710 name, or a number in any base) must consist only of alphanumeric
711 characters -- that is, whatever must watch "m/\A\w+\z/". So "E< 0
712 1 2 3 >" is invalid, because it contains spaces, which aren't
713 alphanumeric characters. This presumably does not need special
714 treatment by a Pod processor; " 0 1 2 3 " doesn't look like a num‐
715 ber in any base, so it would presumably be looked up in the table
716 of HTML-like names. Since there isn't (and cannot be) an HTML-like
717 entity called " 0 1 2 3 ", this will be treated as an error. How‐
718 ever, Pod processors may treat "E< 0 1 2 3 >" or "E<e-acute>" as
719 syntactically invalid, potentially earning a different error mes‐
720 sage than the error message (or warning, or event) generated by a
721 merely unknown (but theoretically valid) htmlname, as in
722 "E<qacute>" [sic]. However, Pod parsers are not required to make
723 this distinction.
724 · Note that E<number> must not be interpreted as simply "codepoint
726 number in the current/native character set". It always means only
727 "the character represented by codepoint number in Unicode." (This
728 is identical to the semantics of &#number; in XML.)
729 This will likely require many formatters to have tables mapping
731 from treatable Unicode codepoints (such as the "\xE9" for the
732 e-acute character) to the escape sequences or codes necessary for
733 conveying such sequences in the target output format. A converter
734 to *roff would, for example know that "\xE9" (whether conveyed lit‐
735 erally, or via a E<...> sequence) is to be conveyed as "e\\*'".
736 Similarly, a program rendering Pod in a Mac OS application window,
737 would presumably need to know that "\xE9" maps to codepoint 142 in
738 MacRoman encoding that (at time of writing) is native for Mac OS.
739 Such Unicode2whatever mappings are presumably already widely avail‐
740 able for common output formats. (Such mappings may be incomplete!
741 Implementers are not expected to bend over backwards in an attempt
742 to render Cherokee syllabics, Etruscan runes, Byzantine musical
743 symbols, or any of the other weird things that Unicode can encode.)
744 And if a Pod document uses a character not found in such a mapping,
745 the formatter should consider it an unrenderable character.
746 · If, surprisingly, the implementor of a Pod formatter can't find a
748 satisfactory pre-existing table mapping from Unicode characters to
749 escapes in the target format (e.g., a decent table of Unicode char‐
750 acters to *roff escapes), it will be necessary to build such a ta‐
751 ble. If you are in this circumstance, you should begin with the
752 characters in the range 0x00A0 - 0x00FF, which is mostly the heav‐
753 ily used accented characters. Then proceed (as patience permits
754 and fastidiousness compels) through the characters that the (X)HTML
755 standards groups judged important enough to merit mnemonics for.
756 These are declared in the (X)HTML specifications at the www.W3.org
757 site. At time of writing (September 2001), the most recent entity
758 declaration files are:
759 http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
761 http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
762 http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent
763 Then you can progress through any remaining notable Unicode charac‐
765 ters in the range 0x2000-0x204D (consult the character tables at
766 www.unicode.org), and whatever else strikes your fancy. For exam‐
767 ple, in xhtml-symbol.ent, there is the entry:
768 <!ENTITY infin "∞"> <!-- infinity, U+221E ISOtech -->
770 While the mapping "infin" to the character "\x{221E}" will (hope‐
772 fully) have been already handled by the Pod parser, the presence of
773 the character in this file means that it's reasonably important
774 enough to include in a formatter's table that maps from notable
775 Unicode characters to the codes necessary for rendering them. So
776 for a Unicode-to-*roff mapping, for example, this would merit the
777 entry:
778 "\x{221E}" => '\(in',
780 It is eagerly hoped that in the future, increasing numbers of for‐
782 mats (and formatters) will support Unicode characters directly (as
783 (X)HTML does with "∞", "∞", or "∞"), reducing
784 the need for idiosyncratic mappings of Unicode-to-my_escapes.
785 · It is up to individual Pod formatter to display good judgment when
787 confronted with an unrenderable character (which is distinct from
788 an unknown E<thing> sequence that the parser couldn't resolve to
789 anything, renderable or not). It is good practice to map Latin
790 letters with diacritics (like "E<eacute>"/"E<233>") to the corre‐
791 sponding unaccented US-ASCII letters (like a simple character 101,
792 "e"), but clearly this is often not feasible, and an unrenderable
793 character may be represented as "?", or the like. In attempting a
794 sane fallback (as from E<233> to "e"), Pod formatters may use the
795 %Latin1Code_to_fallback table in Pod::Escapes, or Text::Unidecode,
796 if available.
797 For example, this Pod text:
799 magic is enabled if you set C<$Currency> to 'E<euro>'.
801 may be rendered as: "magic is enabled if you set $Currency to '?'"
803 or as "magic is enabled if you set $Currency to '[euro]'", or as
804 "magic is enabled if you set $Currency to '[x20AC]', etc.
805 A Pod formatter may also note, in a comment or warning, a list of
807 what unrenderable characters were encountered.
808 · E<...> may freely appear in any formatting code (other than in
810 another E<...> or in an Z<>). That is, "X<The E<euro>1,000,000
811 Solution>" is valid, as is "L<The E<euro>1,000,000 Solution⎪Mil‐
812 lion::Euros>".
813 · Some Pod formatters output to formats that implement non-breaking
815 spaces as an individual character (which I'll call "NBSP"), and
816 others output to formats that implement non-breaking spaces just as
817 spaces wrapped in a "don't break this across lines" code. Note
818 that at the level of Pod, both sorts of codes can occur: Pod can
819 contain a NBSP character (whether as a literal, or as a "E<160>" or
820 "E<nbsp>" code); and Pod can contain "S<foo I<bar> baz>" codes,
821 where "mere spaces" (character 32) in such codes are taken to rep‐
822 resent non-breaking spaces. Pod parsers should consider supporting
823 the optional parsing of "S<foo I<bar> baz>" as if it were "fooNB‐
824 SPI<bar>NBSPbaz", and, going the other way, the optional parsing of
825 groups of words joined by NBSP's as if each group were in a S<...>
826 code, so that formatters may use the representation that maps best
827 to what the output format demands.
828 · Some processors may find that the "S<...>" code is easiest to
830 implement by replacing each space in the parse tree under the con‐
831 tent of the S, with an NBSP. But note: the replacement should
832 apply not to spaces in all text, but only to spaces in printable
833 text. (This distinction may or may not be evident in the particu‐
834 lar tree/event model implemented by the Pod parser.) For example,
835 consider this unusual case:
836 S<L</Autoloaded Functions>>
838 This means that the space in the middle of the visible link text
840 must not be broken across lines. In other words, it's the same as
841 this:
842 L<"AutoloadedE<160>Functions"/Autoloaded Functions>
844 However, a misapplied space-to-NBSP replacement could (wrongly)
846 produce something equivalent to this:
847 L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions>
849 ...which is almost definitely not going to work as a hyperlink
851 (assuming this formatter outputs a format supporting hypertext).
852 Formatters may choose to just not support the S format code, espe‐
854 cially in cases where the output format simply has no NBSP charac‐
855 ter/code and no code for "don't break this stuff across lines".
856 · Besides the NBSP character discussed above, implementors are
858 reminded of the existence of the other "special" character in
859 Latin-1, the "soft hyphen" character, also known as "discretionary
860 hyphen", i.e. "E<173>" = "E<0xAD>" = "E<shy>"). This character
861 expresses an optional hyphenation point. That is, it normally ren‐
862 ders as nothing, but may render as a "-" if a formatter breaks the
863 word at that point. Pod formatters should, as appropriate, do one
864 of the following: 1) render this with a code with the same meaning
865 (e.g., "\-" in RTF), 2) pass it through in the expectation that the
866 formatter understands this character as such, or 3) delete it.
867 For example:
869 sigE<shy>action
871 manuE<shy>script
872 JarkE<shy>ko HieE<shy>taE<shy>nieE<shy>mi
873 These signal to a formatter that if it is to hyphenate "sigaction"
875 or "manuscript", then it should be done as "sig-[linebreak]action"
876 or "manu-[linebreak]script" (and if it doesn't hyphenate it, then
877 the "E<shy>" doesn't show up at all). And if it is to hyphenate
878 "Jarkko" and/or "Hietaniemi", it can do so only at the points where
879 there is a "E<shy>" code.
880 In practice, it is anticipated that this character will not be used
882 often, but formatters should either support it, or delete it.
883 · If you think that you want to add a new command to Pod (like, say,
885 a "=biblio" command), consider whether you could get the same
886 effect with a for or begin/end sequence: "=for biblio ..." or
887 "=begin biblio" ... "=end biblio". Pod processors that don't
888 understand "=for biblio", etc, will simply ignore it, whereas they
889 may complain loudly if they see "=biblio".
890 · Throughout this document, "Pod" has been the preferred spelling for
892 the name of the documentation format. One may also use "POD" or
893 "pod". For the documentation that is (typically) in the Pod for‐
894 mat, you may use "pod", or "Pod", or "POD". Understanding these
895 distinctions is useful; but obsessing over how to spell them, usu‐
896 ally is not.
897
899 As you can tell from a glance at perlpod, the L<...> code is the most
900 complex of the Pod formatting codes. The points below will hopefully
901 clarify what it means and how processors should deal with it.
902 · In parsing an L<...> code, Pod parsers must distinguish at least
904 four attributes:
905 First:
907 The link-text. If there is none, this must be undef. (E.g.,
908 in "L<Perl Functions⎪perlfunc>", the link-text is "Perl Func‐
909 tions". In "L<Time::HiRes>" and even "L<⎪Time::HiRes>", there
910 is no link text. Note that link text may contain formatting.)
911 Second:
913 The possibly inferred link-text -- i.e., if there was no real
914 link text, then this is the text that we'll infer in its place.
915 (E.g., for "L<Getopt::Std>", the inferred link text is
916 "Getopt::Std".)
917 Third:
919 The name or URL, or undef if none. (E.g., in "L<Perl Func‐
920 tions⎪perlfunc>", the name -- also sometimes called the page --
921 is "perlfunc". In "L</CAVEATS>", the name is undef.)
922 Fourth:
924 The section (AKA "item" in older perlpods), or undef if none.
925 E.g., in "DESCRIPTION" in Getopt::Std, "DESCRIPTION" is the
926 section. (Note that this is not the same as a manpage section
927 like the "5" in "man 5 crontab". "Section Foo" in the Pod
928 sense means the part of the text that's introduced by the head‐
929 ing or item whose text is "Foo".)
930 Pod parsers may also note additional attributes including:
932 Fifth:
934 A flag for whether item 3 (if present) is a URL (like
935 "http://lists.perl.org" is), in which case there should be no
936 section attribute; a Pod name (like "perldoc" and "Getopt::Std"
937 are); or possibly a man page name (like "crontab(5)" is).
938 Sixth:
940 The raw original L<...> content, before text is split on "⎪",
941 "/", etc, and before E<...> codes are expanded.
942 (The above were numbered only for concise reference below. It is
944 not a requirement that these be passed as an actual list or array.)
945 For example:
947 L<Foo::Bar>
949 => undef, # link text
950 "Foo::Bar", # possibly inferred link text
951 "Foo::Bar", # name
952 undef, # section
953 'pod', # what sort of link
954 "Foo::Bar" # original content
955 L<Perlport's section on NL's⎪perlport/Newlines>
957 => "Perlport's section on NL's", # link text
958 "Perlport's section on NL's", # possibly inferred link text
959 "perlport", # name
960 "Newlines", # section
961 'pod', # what sort of link
962 "Perlport's section on NL's⎪perlport/Newlines" # orig. content
963 L<perlport/Newlines>
965 => undef, # link text
966 '"Newlines" in perlport', # possibly inferred link text
967 "perlport", # name
968 "Newlines", # section
969 'pod', # what sort of link
970 "perlport/Newlines" # original content
971 L<crontab(5)/"DESCRIPTION">
973 => undef, # link text
974 '"DESCRIPTION" in crontab(5)', # possibly inferred link text
975 "crontab(5)", # name
976 "DESCRIPTION", # section
977 'man', # what sort of link
978 'crontab(5)/"DESCRIPTION"' # original content
979 L</Object Attributes>
981 => undef, # link text
982 '"Object Attributes"', # possibly inferred link text
983 undef, # name
984 "Object Attributes", # section
985 'pod', # what sort of link
986 "/Object Attributes" # original content
987 L<http://www.perl.org/>
989 => undef, # link text
990 "http://www.perl.org/", # possibly inferred link text
991 "http://www.perl.org/", # name
992 undef, # section
993 'url', # what sort of link
994 "http://www.perl.org/" # original content
995 Note that you can distinguish URL-links from anything else by the
997 fact that they match "m/\A\w+:[^:\s]\S*\z/". So
998 "L<http://www.perl.com>" is a URL, but "L<HTTP::Response>" isn't.
999 · In case of L<...> codes with no "text⎪" part in them, older format‐
1001 ters have exhibited great variation in actually displaying the link
1002 or cross reference. For example, L<crontab(5)> would render as
1003 "the crontab(5) manpage", or "in the crontab(5) manpage" or just
1004 "crontab(5)".
1005 Pod processors must now treat "text⎪"-less links as follows:
1007 L<name> => L<name⎪name>
1009 L</section> => L<"section"⎪/section>
1010 L<name/section> => L<"section" in name⎪name/section>
1011 · Note that section names might contain markup. I.e., if a section
1013 starts with:
1014 =head2 About the C<-M> Operator
1016 or with:
1018 =item About the C<-M> Operator
1020 then a link to it would look like this:
1022 L<somedoc/About the C<-M> Operator>
1024 Formatters may choose to ignore the markup for purposes of resolv‐
1026 ing the link and use only the renderable characters in the section
1027 name, as in:
1028 <h1><a name="About_the_-M_Operator">About the <code>-M</code>
1030 Operator</h1>
1031 ...
1033 <a href="somedoc#About_the_-M_Operator">About the <code>-M</code>
1035 Operator" in somedoc</a>
1036 · Previous versions of perlpod distinguished "L<name/"section">"
1038 links from "L<name/item>" links (and their targets). These have
1039 been merged syntactically and semantically in the current specifi‐
1040 cation, and section can refer either to a "=headn Heading Content"
1041 command or to a "=item Item Content" command. This specification
1042 does not specify what behavior should be in the case of a given
1043 document having several things all seeming to produce the same sec‐
1044 tion identifier (e.g., in HTML, several things all producing the
1045 same anchorname in <a name="anchorname">...</a> elements). Where
1046 Pod processors can control this behavior, they should use the first
1047 such anchor. That is, "L<Foo/Bar>" refers to the first "Bar" sec‐
1048 tion in Foo.
1049 But for some processors/formats this cannot be easily controlled;
1051 as with the HTML example, the behavior of multiple ambiguous <a
1052 name="anchorname">...</a> is most easily just left up to browsers
1053 to decide.
1054 · Authors wanting to link to a particular (absolute) URL, must do so
1056 only with "L<scheme:...>" codes (like L<http://www.perl.org>), and
1057 must not attempt "L<Some Site Name⎪scheme:...>" codes. This
1058 restriction avoids many problems in parsing and rendering L<...>
1059 codes.
1060 · In a "L<text⎪...>" code, text may contain formatting codes for for‐
1062 matting or for E<...> escapes, as in:
1063 L<B<ummE<234>stuff>⎪...>
1065 For "L<...>" codes without a "name⎪" part, only "E<...>" and "Z<>"
1067 codes may occur -- no other formatting codes. That is, authors
1068 should not use ""L<B<Foo::Bar>>"".
1069 Note, however, that formatting codes and Z<>'s can occur in any and
1071 all parts of an L<...> (i.e., in name, section, text, and url).
1072 Authors must not nest L<...> codes. For example, "L<The
1074 L<Foo::Bar> man page>" should be treated as an error.
1075 · Note that Pod authors may use formatting codes inside the "text"
1077 part of "L<text⎪name>" (and so on for L<text⎪/"sec">).
1078 In other words, this is valid:
1080 Go read L<the docs on C<$.>⎪perlvar/"$.">
1082 Some output formats that do allow rendering "L<...>" codes as
1084 hypertext, might not allow the link-text to be formatted; in that
1085 case, formatters will have to just ignore that formatting.
1086 · At time of writing, "L<name>" values are of two types: either the
1088 name of a Pod page like "L<Foo::Bar>" (which might be a real Perl
1089 module or program in an @INC / PATH directory, or a .pod file in
1090 those places); or the name of a UNIX man page, like
1091 "L<crontab(5)>". In theory, "L<chmod>" in ambiguous between a Pod
1092 page called "chmod", or the Unix man page "chmod" (in whatever
1093 man-section). However, the presence of a string in parens, as in
1094 "crontab(5)", is sufficient to signal that what is being discussed
1095 is not a Pod page, and so is presumably a UNIX man page. The dis‐
1096 tinction is of no importance to many Pod processors, but some pro‐
1097 cessors that render to hypertext formats may need to distinguish
1098 them in order to know how to render a given "L<foo>" code.
1099 · Previous versions of perlpod allowed for a "L<section>" syntax (as
1101 in ""L<Object Attributes>""), which was not easily distinguishable
1102 from "L<name>" syntax. This syntax is no longer in the specifica‐
1103 tion, and has been replaced by the "L<"section">" syntax (where the
1104 quotes were formerly optional). Pod parsers should tolerate the
1105 "L<section>" syntax, for a while at least. The suggested heuristic
1106 for distinguishing "L<section>" from "L<name>" is that if it con‐
1107 tains any whitespace, it's a section. Pod processors may warn
1108 about this being deprecated syntax.
1109
1111 "=over"..."=back" regions are used for various kinds of list-like
1112 structures. (I use the term "region" here simply as a collective term
1113 for everything from the "=over" to the matching "=back".)
1114 · The non-zero numeric indentlevel in "=over indentlevel" ...
1116 "=back" is used for giving the formatter a clue as to how many
1117 "spaces" (ems, or roughly equivalent units) it should tab over,
1118 although many formatters will have to convert this to an absolute
1119 measurement that may not exactly match with the size of spaces (or
1120 M's) in the document's base font. Other formatters may have to
1121 completely ignore the number. The lack of any explicit indentlevel
1122 parameter is equivalent to an indentlevel value of 4. Pod proces‐
1123 sors may complain if indentlevel is present but is not a positive
1124 number matching "m/\A(\d*\.)?\d+\z/".
1125 · Authors of Pod formatters are reminded that "=over" ... "=back" may
1127 map to several different constructs in your output format. For
1128 example, in converting Pod to (X)HTML, it can map to any of
1129 <ul>...</ul>, <ol>...</ol>, <dl>...</dl>, or <block‐
1130 quote>...</blockquote>. Similarly, "=item" can map to <li> or
1131 <dt>.
1132 · Each "=over" ... "=back" region should be one of the following:
1134 · An "=over" ... "=back" region containing only "=item *" com‐
1136 mands, each followed by some number of ordinary/verbatim para‐
1137 graphs, other nested "=over" ... "=back" regions, "=for..."
1138 paragraphs, and "=begin"..."=end" regions.
1139 (Pod processors must tolerate a bare "=item" as if it were
1141 "=item *".) Whether "*" is rendered as a literal asterisk, an
1142 "o", or as some kind of real bullet character, is left up to
1143 the Pod formatter, and may depend on the level of nesting.
1144 · An "=over" ... "=back" region containing only
1146 "m/\A=item\s+\d+\.?\s*\z/" paragraphs, each one (or each group
1147 of them) followed by some number of ordinary/verbatim para‐
1148 graphs, other nested "=over" ... "=back" regions, "=for..."
1149 paragraphs, and/or "=begin"..."=end" codes. Note that the num‐
1150 bers must start at 1 in each section, and must proceed in order
1151 and without skipping numbers.
1152 (Pod processors must tolerate lines like "=item 1" as if they
1154 were "=item 1.", with the period.)
1155 · An "=over" ... "=back" region containing only "=item [text]"
1157 commands, each one (or each group of them) followed by some
1158 number of ordinary/verbatim paragraphs, other nested "=over"
1159 ... "=back" regions, or "=for..." paragraphs, and
1160 "=begin"..."=end" regions.
1161 The "=item [text]" paragraph should not match
1163 "m/\A=item\s+\d+\.?\s*\z/" or "m/\A=item\s+\*\s*\z/", nor
1164 should it match just "m/\A=item\s*\z/".
1165 · An "=over" ... "=back" region containing no "=item" paragraphs
1167 at all, and containing only some number of ordinary/verbatim
1168 paragraphs, and possibly also some nested "=over" ... "=back"
1169 regions, "=for..." paragraphs, and "=begin"..."=end" regions.
1170 Such an itemless "=over" ... "=back" region in Pod is equiva‐
1171 lent in meaning to a "<blockquote>...</blockquote>" element in
1172 HTML.
1173 Note that with all the above cases, you can determine which type of
1175 "=over" ... "=back" you have, by examining the first (non-"=cut",
1176 non-"=pod") Pod paragraph after the "=over" command.
1177 · Pod formatters must tolerate arbitrarily large amounts of text in
1179 the "=item text..." paragraph. In practice, most such paragraphs
1180 are short, as in:
1181 =item For cutting off our trade with all parts of the world
1183 But they may be arbitrarily long:
1185 =item For transporting us beyond seas to be tried for pretended
1187 offenses
1188 =item He is at this time transporting large armies of foreign
1190 mercenaries to complete the works of death, desolation and
1191 tyranny, already begun with circumstances of cruelty and perfidy
1192 scarcely paralleled in the most barbarous ages, and totally
1193 unworthy the head of a civilized nation.
1194 · Pod processors should tolerate "=item *" / "=item number" commands
1196 with no accompanying paragraph. The middle item is an example:
1197 =over
1199 =item 1
1201 Pick up dry cleaning.
1203 =item 2
1205 =item 3
1207 Stop by the store. Get Abba Zabas, Stoli, and cheap lawn chairs.
1209 =back
1211 · No "=over" ... "=back" region can contain headings. Processors may
1213 treat such a heading as an error.
1214 · Note that an "=over" ... "=back" region should have some content.
1216 That is, authors should not have an empty region like this:
1217 =over
1219 =back
1221 Pod processors seeing such a contentless "=over" ... "=back"
1223 region, may ignore it, or may report it as an error.
1224 · Processors must tolerate an "=over" list that goes off the end of
1226 the document (i.e., which has no matching "=back"), but they may
1227 warn about such a list.
1228 · Authors of Pod formatters should note that this construct:
1230 =item Neque
1232 =item Porro
1234 =item Quisquam Est
1236 Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
1238 velit, sed quia non numquam eius modi tempora incidunt ut
1239 labore et dolore magnam aliquam quaerat voluptatem.
1240 =item Ut Enim
1242 is semantically ambiguous, in a way that makes formatting decisions
1244 a bit difficult. On the one hand, it could be mention of an item
1245 "Neque", mention of another item "Porro", and mention of another
1246 item "Quisquam Est", with just the last one requiring the explana‐
1247 tory paragraph "Qui dolorem ipsum quia dolor..."; and then an item
1248 "Ut Enim". In that case, you'd want to format it like so:
1249 Neque
1251 Porro
1253 Quisquam Est
1255 Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
1256 velit, sed quia non numquam eius modi tempora incidunt ut
1257 labore et dolore magnam aliquam quaerat voluptatem.
1258 Ut Enim
1260 But it could equally well be a discussion of three (related or
1262 equivalent) items, "Neque", "Porro", and "Quisquam Est", followed
1263 by a paragraph explaining them all, and then a new item "Ut Enim".
1264 In that case, you'd probably want to format it like so:
1265 Neque
1267 Porro
1268 Quisquam Est
1269 Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
1270 velit, sed quia non numquam eius modi tempora incidunt ut
1271 labore et dolore magnam aliquam quaerat voluptatem.
1272 Ut Enim
1274 But (for the forseeable future), Pod does not provide any way for
1276 Pod authors to distinguish which grouping is meant by the above
1277 "=item"-cluster structure. So formatters should format it like so:
1278 Neque
1280 Porro
1282 Quisquam Est
1284 Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
1286 velit, sed quia non numquam eius modi tempora incidunt ut
1287 labore et dolore magnam aliquam quaerat voluptatem.
1288 Ut Enim
1290 That is, there should be (at least roughly) equal spacing between
1292 items as between paragraphs (although that spacing may well be less
1293 than the full height of a line of text). This leaves it to the
1294 reader to use (con)textual cues to figure out whether the "Qui
1295 dolorem ipsum..." paragraph applies to the "Quisquam Est" item or
1296 to all three items "Neque", "Porro", and "Quisquam Est". While not
1297 an ideal situation, this is preferable to providing formatting cues
1298 that may be actually contrary to the author's intent.
1299
1301 Data paragraphs are typically used for inlining non-Pod data that is to
1302 be used (typically passed through) when rendering the document to a
1303 specific format:
1304 =begin rtf
1306 \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}
1308 =end rtf
1310 The exact same effect could, incidentally, be achieved with a single
1312 "=for" paragraph:
1313 =for rtf \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}
1315 (Although that is not formally a data paragraph, it has the same mean‐
1317 ing as one, and Pod parsers may parse it as one.)
1318 Another example of a data paragraph:
1320 =begin html
1322 I like <em>PIE</em>!
1324 <hr>Especially pecan pie!
1326 =end html
1328 If these were ordinary paragraphs, the Pod parser would try to expand
1330 the "E</em>" (in the first paragraph) as a formatting code, just like
1331 "E<lt>" or "E<eacute>". But since this is in a "=begin identi‐
1332 fier"..."=end identifier" region and the identifier "html" doesn't
1333 begin have a ":" prefix, the contents of this region are stored as data
1334 paragraphs, instead of being processed as ordinary paragraphs (or if
1335 they began with a spaces and/or tabs, as verbatim paragraphs).
1336 As a further example: At time of writing, no "biblio" identifier is
1338 supported, but suppose some processor were written to recognize it as a
1339 way of (say) denoting a bibliographic reference (necessarily containing
1340 formatting codes in ordinary paragraphs). The fact that "biblio" para‐
1341 graphs were meant for ordinary processing would be indicated by prefac‐
1342 ing each "biblio" identifier with a colon:
1343 =begin :biblio
1345 Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
1347 Programs.> Prentice-Hall, Englewood Cliffs, NJ.
1348 =end :biblio
1350 This would signal to the parser that paragraphs in this begin...end
1352 region are subject to normal handling as ordinary/verbatim paragraphs
1353 (while still tagged as meant only for processors that understand the
1354 "biblio" identifier). The same effect could be had with:
1355 =for :biblio
1357 Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
1358 Programs.> Prentice-Hall, Englewood Cliffs, NJ.
1359 The ":" on these identifiers means simply "process this stuff normally,
1361 even though the result will be for some special target". I suggest
1362 that parser APIs report "biblio" as the target identifier, but also
1363 report that it had a ":" prefix. (And similarly, with the above
1364 "html", report "html" as the target identifier, and note the lack of a
1365 ":" prefix.)
1366 Note that a "=begin identifier"..."=end identifier" region where iden‐
1368 tifier begins with a colon, can contain commands. For example:
1369 =begin :biblio
1371 Wirth's classic is available in several editions, including:
1373 =for comment
1375 hm, check abebooks.com for how much used copies cost.
1376 =over
1378 =item
1380 Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.>
1382 Teubner, Stuttgart. [Yes, it's in German.]
1383 =item
1385 Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
1387 Programs.> Prentice-Hall, Englewood Cliffs, NJ.
1388 =back
1390 =end :biblio
1392 Note, however, a "=begin identifier"..."=end identifier" region where
1394 identifier does not begin with a colon, should not directly contain
1395 "=head1" ... "=head4" commands, nor "=over", nor "=back", nor "=item".
1396 For example, this may be considered invalid:
1397 =begin somedata
1399 This is a data paragraph.
1401 =head1 Don't do this!
1403 This is a data paragraph too.
1405 =end somedata
1407 A Pod processor may signal that the above (specifically the "=head1"
1409 paragraph) is an error. Note, however, that the following should not
1410 be treated as an error:
1411 =begin somedata
1413 This is a data paragraph.
1415 =cut
1417 # Yup, this isn't Pod anymore.
1419 sub excl { (rand() > .5) ? "hoo!" : "hah!" }
1420 =pod
1422 This is a data paragraph too.
1424 =end somedata
1426 And this too is valid:
1428 =begin someformat
1430 This is a data paragraph.
1432 And this is a data paragraph.
1434 =begin someotherformat
1436 This is a data paragraph too.
1438 And this is a data paragraph too.
1440 =begin :yetanotherformat
1442 =head2 This is a command paragraph!
1444 This is an ordinary paragraph!
1446 And this is a verbatim paragraph!
1448 =end :yetanotherformat
1450 =end someotherformat
1452 Another data paragraph!
1454 =end someformat
1456 The contents of the above "=begin :yetanotherformat" ... "=end :yetan‐
1458 otherformat" region aren't data paragraphs, because the immediately
1459 containing region's identifier (":yetanotherformat") begins with a
1460 colon. In practice, most regions that contain data paragraphs will
1461 contain only data paragraphs; however, the above nesting is syntacti‐
1462 cally valid as Pod, even if it is rare. However, the handlers for some
1463 formats, like "html", will accept only data paragraphs, not nested
1464 regions; and they may complain if they see (targeted for them) nested
1465 regions, or commands, other than "=end", "=pod", and "=cut".
1466 Also consider this valid structure:
1468 =begin :biblio
1470 Wirth's classic is available in several editions, including:
1472 =over
1474 =item
1476 Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.>
1478 Teubner, Stuttgart. [Yes, it's in German.]
1479 =item
1481 Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
1483 Programs.> Prentice-Hall, Englewood Cliffs, NJ.
1484 =back
1486 Buy buy buy!
1488 =begin html
1490 <img src='wirth_spokesmodeling_book.png'>
1492 <hr>
1494 =end html
1496 Now now now!
1498 =end :biblio
1500 There, the "=begin html"..."=end html" region is nested inside the
1502 larger "=begin :biblio"..."=end :biblio" region. Note that the content
1503 of the "=begin html"..."=end html" region is data paragraph(s), because
1504 the immediately containing region's identifier ("html") doesn't begin
1505 with a colon.
1506 Pod parsers, when processing a series of data paragraphs one after
1508 another (within a single region), should consider them to be one large
1509 data paragraph that happens to contain blank lines. So the content of
1510 the above "=begin html"..."=end html" may be stored as two data para‐
1511 graphs (one consisting of "<img src='wirth_spokesmodeling_book.png'>\n"
1512 and another consisting of "<hr>\n"), but should be stored as a single
1513 data paragraph (consisting of "<img src='wirth_spokesmodel‐
1514 ing_book.png'>\n\n<hr>\n").
1515 Pod processors should tolerate empty "=begin something"..."=end some‐
1517 thing" regions, empty "=begin :something"..."=end :something" regions,
1518 and contentless "=for something" and "=for :something" paragraphs.
1519 I.e., these should be tolerated:
1520 =for html
1522 =begin html
1524 =end html
1526 =begin :biblio
1528 =end :biblio
1530 Incidentally, note that there's no easy way to express a data paragraph
1532 starting with something that looks like a command. Consider:
1533 =begin stuff
1535 =shazbot
1537 =end stuff
1539 There, "=shazbot" will be parsed as a Pod command "shazbot", not as a
1541 data paragraph "=shazbot\n". However, you can express a data paragraph
1542 consisting of "=shazbot\n" using this code:
1543 =for stuff =shazbot
1545 The situation where this is necessary, is presumably quite rare.
1547 Note that =end commands must match the currently open =begin command.
1549 That is, they must properly nest. For example, this is valid:
1550 =begin outer
1552 X
1554 =begin inner
1556 Y
1558 =end inner
1560 Z
1562 =end outer
1564 while this is invalid:
1566 =begin outer
1568 X
1570 =begin inner
1572 Y
1574 =end outer
1576 Z
1578 =end inner
1580 This latter is improper because when the "=end outer" command is seen,
1582 the currently open region has the formatname "inner", not "outer". (It
1583 just happens that "outer" is the format name of a higher-up region.)
1584 This is an error. Processors must by default report this as an error,
1585 and may halt processing the document containing that error. A corol‐
1586 lary of this is that regions cannot "overlap" -- i.e., the latter block
1587 above does not represent a region called "outer" which contains X and
1588 Y, overlapping a region called "inner" which contains Y and Z. But
1589 because it is invalid (as all apparently overlapping regions would be),
1590 it doesn't represent that, or anything at all.
1591 Similarly, this is invalid:
1593 =begin thing
1595 =end hting
1597 This is an error because the region is opened by "thing", and the
1599 "=end" tries to close "hting" [sic].
1600 This is also invalid:
1602 =begin thing
1604 =end
1606 This is invalid because every "=end" command must have a formatname
1608 parameter.
1609
1611 perlpod, "PODs: Embedded Documentation" in perlsyn, podchecker
1612
1614 Sean M. Burke
1615perl v5.8.8 2006-01-07 PERLPODSPEC(1)