extra code in pp_concat, Take 2
[p5sagit/p5-mst-13.2.git] / pod / perlpodspec.pod
CommitLineData
8a93676d 1
2=head1 NAME
3
4perlpodspec - Plain Old Documentation: format specification and notes
5
6=head1 DESCRIPTION
7
8This document is detailed notes on the Pod markup language. Most
9people will only have to read L<perlpod|perlpod> to know how to write
10in Pod, but this document may answer some incidental questions to do
11with parsing and rendering Pod.
12
13In this document, "must" / "must not", "should" /
14"should not", and "may" have their conventional (cf. RFC 2119)
15meanings: "X must do Y" means that if X doesn't do Y, it's against
16this specification, and should really be fixed. "X should do Y"
17means that it's recommended, but X may fail to do Y, if there's a
18good reason. "X may do Y" is merely a note that X can do Y at
19will (although it is up to the reader to detect any connotation of
20"and I think it would be I<nice> if X did Y" versus "it wouldn't
21really I<bother> me if X did Y").
22
23Notably, when I say "the parser should do Y", the
24parser may fail to do Y, if the calling application explicitly
25requests that the parser I<not> do Y. I often phrase this as
26"the parser should, by default, do Y." This doesn't I<require>
27the parser to provide an option for turning off whatever
28feature Y is (like expanding tabs in verbatim paragraphs), although
29it implicates that such an option I<may> be provided.
30
31=head1 Pod Definitions
32
33Pod is embedded in files, typically Perl source files -- although you
34can write a file that's nothing but Pod.
35
36A B<line> in a file consists of zero or more non-newline characters,
37terminated by either a newline or the end of the file.
38
39A B<newline sequence> is usually a platform-dependent concept, but
40Pod parsers should understand it to mean any of CR (ASCII 13), LF
41(ASCII 10), or a CRLF (ASCII 13 followed immediately by ASCII 10), in
42addition to any other system-specific meaning. The first CR/CRLF/LF
43sequence in the file may be used as the basis for identifying the
44newline sequence for parsing the rest of the file.
45
46A B<blank line> is a line consisting entirely of zero or more spaces
47(ASCII 32) or tabs (ASCII 9), and terminated by a newline or end-of-file.
48A B<non-blank line> is a line containing one or more characters other
49than space or tab (and terminated by a newline or end-of-file).
50
51(I<Note:> Many older Pod parsers did not accept a line consisting of
52spaces/tabs and then a newline as a blank line -- the only lines they
53considered blank were lines consisting of I<no characters at all>,
54terminated by a newline.)
55
56B<Whitespace> is used in this document as a blanket term for spaces,
57tabs, and newline sequences. (By itself, this term usually refers
58to literal whitespace. That is, sequences of whitespace characters
59in Pod source, as opposed to "EE<lt>32>", which is a formatting
60code that I<denotes> a whitespace character.)
61
62A B<Pod parser> is a module meant for parsing Pod (regardless of
63whether this involves calling callbacks or building a parse tree or
64directly formatting it). A B<Pod formatter> (or B<Pod translator>)
65is a module or program that converts Pod to some other format (HTML,
66plaintext, TeX, PostScript, RTF). A B<Pod processor> might be a
67formatter or translator, or might be a program that does something
68else with the Pod (like wordcounting it, scanning for index points,
69etc.).
70
71Pod content is contained in B<Pod blocks>. A Pod block starts with a
72line that matches <m/\A=[a-zA-Z]/>, and continues up to the next line
73that matches C<m/\A=cut/> -- or up to the end of the file, if there is
74no C<m/\A=cut/> line.
75
76=for comment
77 The current perlsyn says:
78 [beginquote]
79 Note that pod translators should look at only paragraphs beginning
80 with a pod directive (it makes parsing easier), whereas the compiler
81 actually knows to look for pod escapes even in the middle of a
82 paragraph. This means that the following secret stuff will be ignored
83 by both the compiler and the translators.
84 $a=3;
85 =secret stuff
86 warn "Neither POD nor CODE!?"
87 =cut back
88 print "got $a\n";
89 You probably shouldn't rely upon the warn() being podded out forever.
90 Not all pod translators are well-behaved in this regard, and perhaps
91 the compiler will become pickier.
92 [endquote]
93 I think that those paragraphs should just be removed; paragraph-based
94 parsing seems to have been largely abandoned, because of the hassle
95 with non-empty blank lines messing up what people meant by "paragraph".
96 Even if the "it makes parsing easier" bit were especially true,
97 it wouldn't be worth the confusion of having perl and pod2whatever
98 actually disagree on what can constitute a Pod block.
99
100Within a Pod block, there are B<Pod paragraphs>. A Pod paragraph
101consists of non-blank lines of text, separated by one or more blank
102lines.
103
104For purposes of Pod processing, there are four types of paragraphs in
105a Pod block:
106
107=over
108
109=item *
110
111A command paragraph (also called a "directive"). The first line of
112this paragraph must match C<m/\A=[a-zA-Z]/>. Command paragraphs are
113typically one line, as in:
114
115 =head1 NOTES
116
117 =item *
118
119But they may span several (non-blank) lines:
120
121 =for comment
122 Hm, I wonder what it would look like if
123 you tried to write a BNF for Pod from this.
210b36aa 124
8a93676d 125 =head3 Dr. Strangelove, or: How I Learned to
126 Stop Worrying and Love the Bomb
127
128I<Some> command paragraphs allow formatting codes in their content
129(i.e., after the part that matches C<m/\A=[a-zA-Z]\S*\s*/>), as in:
130
131 =head1 Did You Remember to C<use strict;>?
132
133In other words, the Pod processing handler for "head1" will apply the
134same processing to "Did You Remember to CE<lt>use strict;>?" that it
135would to an ordinary paragraph -- i.e., formatting codes (like
136"CE<lt>...>") are parsed and presumably formatted appropriately, and
137whitespace in the form of literal spaces and/or tabs is not
138significant.
139
140=item *
141
142A B<verbatim paragraph>. The first line of this paragraph must be a
143literal space or tab, and this paragraph must not be inside a "=begin
144I<identifier>", ... "=end I<identifier>" sequence unless
145"I<identifier>" begins with a colon (":"). That is, if a paragraph
146starts with a literal space or tab, but I<is> inside a
147"=begin I<identifier>", ... "=end I<identifier>" region, then it's
148a data paragraph, unless "I<identifier>" begins with a colon.
149
150Whitespace I<is> significant in verbatim paragraphs (although, in
151processing, tabs are probably expanded).
152
153=item *
154
155An B<ordinary paragraph>. A paragraph is an ordinary paragraph
156if its first line matches neither C<m/\A=[a-zA-Z]/> nor
157C<m/\A[ \t]/>, I<and> if it's not inside a "=begin I<identifier>",
158... "=end I<identifier>" sequence unless "I<identifier>" begins with
159a colon (":").
160
161=item *
162
163A B<data paragraph>. This is a paragraph that I<is> inside a "=begin
164I<identifier>" ... "=end I<identifier>" sequence where
165"I<identifier>" does I<not> begin with a literal colon (":"). In
166some sense, a data paragraph is not part of Pod at all (i.e.,
167effectively it's "out-of-band"), since it's not subject to most kinds
168of Pod parsing; but it is specified here, since Pod
169parsers need to be able to call an event for it, or store it in some
170form in a parse tree, or at least just parse I<around> it.
171
172=back
173
174For example: consider the following paragraphs:
175
176 # <- that's the 0th column
177
178 =head1 Foo
210b36aa 179
8a93676d 180 Stuff
210b36aa 181
8a93676d 182 $foo->bar
210b36aa 183
8a93676d 184 =cut
185
186Here, "=head1 Foo" and "=cut" are command paragraphs because the first
187line of each matches C<m/\A=[a-zA-Z]/>. "I<[space][space]>$foo->bar"
188is a verbatim paragraph, because its first line starts with a literal
189whitespace character (and there's no "=begin"..."=end" region around).
190
191The "=begin I<identifier>" ... "=end I<identifier>" commands stop
192paragraphs that they surround from being parsed as data or verbatim
193paragraphs, if I<identifier> doesn't begin with a colon. This
194is discussed in detail in the section
195L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
196
197=head1 Pod Commands
198
199This section is intended to supplement and clarify the discussion in
200L<perlpod/"Command Paragraph">. These are the currently recognized
201Pod commands:
202
203=over
204
205=item "=head1", "=head2", "=head3", "=head4"
206
207This command indicates that the text in the remainder of the paragraph
208is a heading. That text may contain formatting codes. Examples:
209
210 =head1 Object Attributes
210b36aa 211
8a93676d 212 =head3 What B<Not> to Do!
213
214=item "=pod"
215
216This command indicates that this paragraph begins a Pod block. (If we
217are already in the middle of a Pod block, this command has no effect at
218all.) If there is any text in this command paragraph after "=pod",
219it must be ignored. Examples:
220
221 =pod
210b36aa 222
8a93676d 223 This is a plain Pod paragraph.
210b36aa 224
8a93676d 225 =pod This text is ignored.
226
227=item "=cut"
228
229This command indicates that this line is the end of this previously
230started Pod block. If there is any text after "=cut" on the line, it must be
231ignored. Examples:
232
233 =cut
234
235 =cut The documentation ends here.
236
237 =cut
238 # This is the first line of program text.
239 sub foo { # This is the second.
240
659cfd94 241It is an error to try to I<start> a Pod block with a "=cut" command. In
8a93676d 242that case, the Pod processor must halt parsing of the input file, and
243must by default emit a warning.
244
245=item "=over"
246
247This command indicates that this is the start of a list/indent
248region. If there is any text following the "=over", it must consist
249of only a nonzero positive numeral. The semantics of this numeral is
250explained in the L</"About =over...=back Regions"> section, further
251below. Formatting codes are not expanded. Examples:
252
253 =over 3
210b36aa 254
8a93676d 255 =over 3.5
210b36aa 256
8a93676d 257 =over
258
259=item "=item"
260
261This command indicates that an item in a list begins here. Formatting
262codes are processed. The semantics of the (optional) text in the
263remainder of this paragraph are
264explained in the L</"About =over...=back Regions"> section, further
265below. Examples:
266
267 =item
210b36aa 268
8a93676d 269 =item *
210b36aa 270
8a93676d 271 =item *
210b36aa 272
8a93676d 273 =item 14
210b36aa 274
8a93676d 275 =item 3.
210b36aa 276
8a93676d 277 =item C<< $thing->stuff(I<dodad>) >>
210b36aa 278
8a93676d 279 =item For transporting us beyond seas to be tried for pretended
280 offenses
210b36aa 281
8a93676d 282 =item He is at this time transporting large armies of foreign
283 mercenaries to complete the works of death, desolation and
284 tyranny, already begun with circumstances of cruelty and perfidy
285 scarcely paralleled in the most barbarous ages, and totally
286 unworthy the head of a civilized nation.
287
288=item "=back"
289
290This command indicates that this is the end of the region begun
291by the most recent "=over" command. It permits no text after the
292"=back" command.
293
294=item "=begin formatname"
295
296This marks the following paragraphs (until the matching "=end
297formatname") as being for some special kind of processing. Unless
298"formatname" begins with a colon, the contained non-command
299paragraphs are data paragraphs. But if "formatname" I<does> begin
300with a colon, then non-command paragraphs are ordinary paragraphs
301or data paragraphs. This is discussed in detail in the section
302L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
303
304It is advised that formatnames match the regexp
305C<m/\A:?[-a-zA-Z0-9_]+\z/>. Implementors should anticipate future
306expansion in the semantics and syntax of the first parameter
307to "=begin"/"=end"/"=for".
308
309=item "=end formatname"
310
311This marks the end of the region opened by the matching
312"=begin formatname" region. If "formatname" is not the formatname
313of the most recent open "=begin formatname" region, then this
314is an error, and must generate an error message. This
315is discussed in detail in the section
316L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
317
318=item "=for formatname text..."
319
320This is synonymous with:
321
322 =begin formatname
210b36aa 323
8a93676d 324 text...
210b36aa 325
8a93676d 326 =end formatname
327
328That is, it creates a region consisting of a single paragraph; that
329paragraph is to be treated as a normal paragraph if "formatname"
330begins with a ":"; if "formatname" I<doesn't> begin with a colon,
331then "text..." will constitute a data paragraph. There is no way
332to use "=for formatname text..." to express "text..." as a verbatim
333paragraph.
334
a179871b 335=item "=encoding encodingname"
336
337This command, which should occur early in the document (at least
1e54db1a 338before any non-US-ASCII data!), declares that this document is
a179871b 339encoded in the encoding I<encodingname>, which must be
340an encoding name that L<Encoding> recognizes. (Encoding's list
341of supported encodings, in L<Encoding::Supported>, is useful here.)
342If the Pod parser cannot decode the declared encoding, it
343should emit a warning and may abort parsing the document
344altogether.
345
346A document having more than one "=encoding" line should be
347considered an error. Pod processors may silently tolerate this if
348the not-first "=encoding" lines are just duplicates of the
349first one (e.g., if there's a "=use utf8" line, and later on
350another "=use utf8" line). But Pod processors should complain if
351there are contradictory "=encoding" lines in the same document
352(e.g., if there is a "=encoding utf8" early in the document and
353"=encoding big5" later). Pod processors that recognize BOMs
354may also complain if they see an "=encoding" line
1e54db1a 355that contradicts the BOM (e.g., if a document with a UTF-16LE
356BOM has an "=encoding shiftjis" line).
a179871b 357
8a93676d 358=back
359
360If a Pod processor sees any command other than the ones listed
361above (like "=head", or "=haed1", or "=stuff", or "=cuttlefish",
362or "=w123"), that processor must by default treat this as an
363error. It must not process the paragraph beginning with that
364command, must by default warn of this as an error, and may
365abort the parse. A Pod parser may allow a way for particular
366applications to add to the above list of known commands, and to
367stipulate, for each additional command, whether formatting
368codes should be processed.
369
370Future versions of this specification may add additional
371commands.
372
373
374
375=head1 Pod Formatting Codes
376
377(Note that in previous drafts of this document and of perlpod,
378formatting codes were referred to as "interior sequences", and
379this term may still be found in the documentation for Pod parsers,
380and in error messages from Pod processors.)
381
382There are two syntaxes for formatting codes:
383
384=over
385
386=item *
387
388A formatting code starts with a capital letter (just US-ASCII [A-Z])
389followed by a "<", any number of characters, and ending with the first
390matching ">". Examples:
391
392 That's what I<you> think!
393
394 What's C<dump()> for?
395
396 X<C<chmod> and C<unlink()> Under Different Operating Systems>
397
398=item *
399
400A formatting code starts with a capital letter (just US-ASCII [A-Z])
401followed by two or more "<"'s, one or more whitespace characters,
402any number of characters, one or more whitespace characters,
403and ending with the first matching sequence of two or more ">"'s, where
404the number of ">"'s equals the number of "<"'s in the opening of this
405formatting code. Examples:
406
407 That's what I<< you >> think!
408
409 C<<< open(X, ">>thing.dat") || die $! >>>
410
411 B<< $foo->bar(); >>
412
413With this syntax, the whitespace character(s) after the "CE<lt><<"
414and before the ">>" (or whatever letter) are I<not> renderable -- they
415do not signify whitespace, are merely part of the formatting codes
416themselves. That is, these are all synonymous:
417
418 C<thing>
419 C<< thing >>
420 C<< thing >>
421 C<<< thing >>>
422 C<<<<
423 thing
424 >>>>
425
426and so on.
427
428=back
429
430In parsing Pod, a notably tricky part is the correct parsing of
431(potentially nested!) formatting codes. Implementors should
432consult the code in the C<parse_text> routine in Pod::Parser as an
433example of a correct implementation.
434
435=over
436
437=item C<IE<lt>textE<gt>> -- italic text
438
439See the brief discussion in L<perlpod/"Formatting Codes">.
440
441=item C<BE<lt>textE<gt>> -- bold text
442
443See the brief discussion in L<perlpod/"Formatting Codes">.
444
445=item C<CE<lt>codeE<gt>> -- code text
446
447See the brief discussion in L<perlpod/"Formatting Codes">.
448
449=item C<FE<lt>filenameE<gt>> -- style for filenames
450
451See the brief discussion in L<perlpod/"Formatting Codes">.
452
453=item C<XE<lt>topic nameE<gt>> -- an index entry
454
455See the brief discussion in L<perlpod/"Formatting Codes">.
456
457This code is unusual in that most formatters completely discard
458this code and its content. Other formatters will render it with
459invisible codes that can be used in building an index of
460the current document.
461
462=item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code
463
464Discussed briefly in L<perlpod/"Formatting Codes">.
465
466This code is unusual is that it should have no content. That is,
467a processor may complain if it sees C<ZE<lt>potatoesE<gt>>. Whether
468or not it complains, the I<potatoes> text should ignored.
469
470=item C<LE<lt>nameE<gt>> -- a hyperlink
471
472The complicated syntaxes of this code are discussed at length in
473L<perlpod/"Formatting Codes">, and implementation details are
474discussed below, in L</"About LE<lt>...E<gt> Codes">. Parsing the
475contents of LE<lt>content> is tricky. Notably, the content has to be
476checked for whether it looks like a URL, or whether it has to be split
477on literal "|" and/or "/" (in the right order!), and so on,
478I<before> EE<lt>...> codes are resolved.
479
480=item C<EE<lt>escapeE<gt>> -- a character escape
481
482See L<perlpod/"Formatting Codes">, and several points in
483L</Notes on Implementing Pod Processors>.
484
485=item C<SE<lt>textE<gt>> -- text contains non-breaking spaces
486
487This formatting code is syntactically simple, but semantically
488complex. What it means is that each space in the printable
3e666715 489content of this code signifies a non-breaking space.
8a93676d 490
491Consider:
492
493 C<$x ? $y : $z>
494
495 S<C<$x ? $y : $z>>
496
497Both signify the monospace (c[ode] style) text consisting of
498"$x", one space, "?", one space, ":", one space, "$z". The
499difference is that in the latter, with the S code, those spaces
3e666715 500are not "normal" spaces, but instead are non-breaking spaces.
8a93676d 501
502=back
503
504
505If a Pod processor sees any formatting code other than the ones
506listed above (as in "NE<lt>...>", or "QE<lt>...>", etc.), that
507processor must by default treat this as an error.
508A Pod parser may allow a way for particular
509applications to add to the above list of known formatting codes;
510a Pod parser might even allow a way to stipulate, for each additional
511command, whether it requires some form of special processing, as
512LE<lt>...> does.
513
514Future versions of this specification may add additional
515formatting codes.
516
517Historical note: A few older Pod processors would not see a ">" as
518closing a "CE<lt>" code, if the ">" was immediately preceded by
519a "-". This was so that this:
520
521 C<$foo->bar>
522
523would parse as equivalent to this:
524
75f15e9f 525 C<$foo-E<gt>bar>
8a93676d 526
527instead of as equivalent to a "C" formatting code containing
528only "$foo-", and then a "bar>" outside the "C" formatting code. This
529problem has since been solved by the addition of syntaxes like this:
530
531 C<< $foo->bar >>
532
533Compliant parsers must not treat "->" as special.
534
535Formatting codes absolutely cannot span paragraphs. If a code is
536opened in one paragraph, and no closing code is found by the end of
537that paragraph, the Pod parser must close that formatting code,
538and should complain (as in "Unterminated I code in the paragraph
539starting at line 123: 'Time objects are not...'"). So these
540two paragraphs:
541
542 I<I told you not to do this!
210b36aa 543
8a93676d 544 Don't make me say it again!>
545
546...must I<not> be parsed as two paragraphs in italics (with the I
547code starting in one paragraph and starting in another.) Instead,
548the first paragraph should generate a warning, but that aside, the
549above code must parse as if it were:
550
551 I<I told you not to do this!>
210b36aa 552
8a93676d 553 Don't make me say it again!E<gt>
554
555(In SGMLish jargon, all Pod commands are like block-level
556elements, whereas all Pod formatting codes are like inline-level
557elements.)
558
559
560
561=head1 Notes on Implementing Pod Processors
562
563The following is a long section of miscellaneous requirements
564and suggestions to do with Pod processing.
565
566=over
567
568=item *
569
570Pod formatters should tolerate lines in verbatim blocks that are of
571any length, even if that means having to break them (possibly several
572times, for very long lines) to avoid text running off the side of the
573page. Pod formatters may warn of such line-breaking. Such warnings
574are particularly appropriate for lines are over 100 characters long, which
575are usually not intentional.
576
577=item *
578
579Pod parsers must recognize I<all> of the three well-known newline
580formats: CR, LF, and CRLF. See L<perlport|perlport>.
581
582=item *
583
584Pod parsers should accept input lines that are of any length.
585
586=item *
587
588Since Perl recognizes a Unicode Byte Order Mark at the start of files
589as signaling that the file is Unicode encoded as in UTF-16 (whether
590big-endian or little-endian) or UTF-8, Pod parsers should do the
591same. Otherwise, the character encoding should be understood as
592being UTF-8 if the first highbit byte sequence in the file seems
593valid as a UTF-8 sequence, or otherwise as Latin-1.
594
595Future versions of this specification may specify
596how Pod can accept other encodings. Presumably treatment of other
597encodings in Pod parsing would be as in XML parsing: whatever the
598encoding declared by a particular Pod file, content is to be
599stored in memory as Unicode characters.
600
601=item *
602
603The well known Unicode Byte Order Marks are as follows: if the
604file begins with the two literal byte values 0xFE 0xFF, this is
605the BOM for big-endian UTF-16. If the file begins with the two
606literal byte value 0xFF 0xFE, this is the BOM for little-endian
607UTF-16. If the file begins with the three literal byte values
6080xEF 0xBB 0xBF, this is the BOM for UTF-8.
609
610=for comment
611 use bytes; print map sprintf(" 0x%02X", ord $_), split '', "\x{feff}";
612 0xEF 0xBB 0xBF
613
614=for comment
1e54db1a 615 If toke.c is modified to support UTF-32, add mention of those here.
8a93676d 616
617=item *
618
619A naive but sufficient heuristic for testing the first highbit
620byte-sequence in a BOM-less file (whether in code or in Pod!), to see
621whether that sequence is valid as UTF-8 (RFC 2279) is to check whether
622that the first byte in the sequence is in the range 0xC0 - 0xFD
623I<and> whether the next byte is in the range
6240x80 - 0xBF. If so, the parser may conclude that this file is in
625UTF-8, and all highbit sequences in the file should be assumed to
626be UTF-8. Otherwise the parser should treat the file as being
627in Latin-1. In the unlikely circumstance that the first highbit
628sequence in a truly non-UTF-8 file happens to appear to be UTF-8, one
629can cater to our heuristic (as well as any more intelligent heuristic)
630by prefacing that line with a comment line containing a highbit
631sequence that is clearly I<not> valid as UTF-8. A line consisting
632of simply "#", an e-acute, and any non-highbit byte,
633is sufficient to establish this file's encoding.
634
635=for comment
636 If/WHEN some brave soul makes these heuristics into a generic
fae2c0fb 637 text-file class (or PerlIO layer?), we can presumably delete
8a93676d 638 mention of these icky details from this file, and can instead
fae2c0fb 639 tell people to just use appropriate class/layer.
8a93676d 640 Auto-recognition of newline sequences would be another desirable
fae2c0fb 641 feature of such a class/layer.
8a93676d 642 HINT HINT HINT.
643
644=for comment
645 "The probability that a string of characters
646 in any other encoding appears as valid UTF-8 is low" - RFC2279
647
648=item *
649
650This document's requirements and suggestions about encodings
651do not apply to Pod processors running on non-ASCII platforms,
652notably EBCDIC platforms.
653
654=item *
655
656Pod processors must treat a "=for [label] [content...]" paragraph as
657meaning the same thing as a "=begin [label]" paragraph, content, and
658an "=end [label]" paragraph. (The parser may conflate these two
659constructs, or may leave them distinct, in the expectation that the
660formatter will nevertheless treat them the same.)
661
662=item *
663
664When rendering Pod to a format that allows comments (i.e., to nearly
665any format other than plaintext), a Pod formatter must insert comment
666text identifying its name and version number, and the name and
667version numbers of any modules it might be using to process the Pod.
668Minimal examples:
669
670 %% POD::Pod2PS v3.14159, using POD::Parser v1.92
210b36aa 671
8a93676d 672 <!-- Pod::HTML v3.14159, using POD::Parser v1.92 -->
210b36aa 673
8a93676d 674 {\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08}
210b36aa 675
8a93676d 676 .\" Pod::Man version 3.14159, using POD::Parser version 1.92
677
678Formatters may also insert additional comments, including: the
679release date of the Pod formatter program, the contact address for
680the author(s) of the formatter, the current time, the name of input
681file, the formatting options in effect, version of Perl used, etc.
682
683Formatters may also choose to note errors/warnings as comments,
684besides or instead of emitting them otherwise (as in messages to
685STDERR, or C<die>ing).
686
687=item *
688
689Pod parsers I<may> emit warnings or error messages ("Unknown E code
690EE<lt>zslig>!") to STDERR (whether through printing to STDERR, or
691C<warn>ing/C<carp>ing, or C<die>ing/C<croak>ing), but I<must> allow
692suppressing all such STDERR output, and instead allow an option for
693reporting errors/warnings
694in some other way, whether by triggering a callback, or noting errors
695in some attribute of the document object, or some similarly unobtrusive
696mechanism -- or even by appending a "Pod Errors" section to the end of
697the parsed form of the document.
698
699=item *
700
701In cases of exceptionally aberrant documents, Pod parsers may abort the
702parse. Even then, using C<die>ing/C<croak>ing is to be avoided; where
703possible, the parser library may simply close the input file
704and add text like "*** Formatting Aborted ***" to the end of the
705(partial) in-memory document.
706
707=item *
708
709In paragraphs where formatting codes (like EE<lt>...>, BE<lt>...>)
710are understood (i.e., I<not> verbatim paragraphs, but I<including>
711ordinary paragraphs, and command paragraphs that produce renderable
712text, like "=head1"), literal whitespace should generally be considered
713"insignificant", in that one literal space has the same meaning as any
714(nonzero) number of literal spaces, literal newlines, and literal tabs
715(as long as this produces no blank lines, since those would terminate
716the paragraph). Pod parsers should compact literal whitespace in each
717processed paragraph, but may provide an option for overriding this
718(since some processing tasks do not require it), or may follow
719additional special rules (for example, specially treating
720period-space-space or period-newline sequences).
721
722=item *
723
724Pod parsers should not, by default, try to coerce apostrophe (') and
725quote (") into smart quotes (little 9's, 66's, 99's, etc), nor try to
726turn backtick (`) into anything else but a single backtick character
727(distinct from an openquote character!), nor "--" into anything but
728two minus signs. They I<must never> do any of those things to text
729in CE<lt>...> formatting codes, and never I<ever> to text in verbatim
730paragraphs.
731
732=item *
733
734When rendering Pod to a format that has two kinds of hyphens (-), one
3e666715 735that's a non-breaking hyphen, and another that's a breakable hyphen
8a93676d 736(as in "object-oriented", which can be split across lines as
737"object-", newline, "oriented"), formatters are encouraged to
3e666715 738generally translate "-" to non-breaking hyphen, but may apply
8a93676d 739heuristics to convert some of these to breaking hyphens.
740
741=item *
742
743Pod formatters should make reasonable efforts to keep words of Perl
744code from being broken across lines. For example, "Foo::Bar" in some
745formatting systems is seen as eligible for being broken across lines
746as "Foo::" newline "Bar" or even "Foo::-" newline "Bar". This should
747be avoided where possible, either by disabling all line-breaking in
748mid-word, or by wrapping particular words with internal punctuation
749in "don't break this across lines" codes (which in some formats may
750not be a single code, but might be a matter of inserting non-breaking
751zero-width spaces between every pair of characters in a word.)
752
753=item *
754
755Pod parsers should, by default, expand tabs in verbatim paragraphs as
756they are processed, before passing them to the formatter or other
757processor. Parsers may also allow an option for overriding this.
758
759=item *
760
761Pod parsers should, by default, remove newlines from the end of
762ordinary and verbatim paragraphs before passing them to the
763formatter. For example, while the paragraph you're reading now
764could be considered, in Pod source, to end with (and contain)
765the newline(s) that end it, it should be processed as ending with
766(and containing) the period character that ends this sentence.
767
768=item *
769
770Pod parsers, when reporting errors, should make some effort to report
771an approximate line number ("Nested EE<lt>>'s in Paragraph #52, near
772line 633 of Thing/Foo.pm!"), instead of merely noting the paragraph
773number ("Nested EE<lt>>'s in Paragraph #52 of Thing/Foo.pm!"). Where
774this is problematic, the paragraph number should at least be
775accompanied by an excerpt from the paragraph ("Nested EE<lt>>'s in
776Paragraph #52 of Thing/Foo.pm, which begins 'Read/write accessor for
777the CE<lt>interest rate> attribute...'").
778
779=item *
780
781Pod parsers, when processing a series of verbatim paragraphs one
782after another, should consider them to be one large verbatim
783paragraph that happens to contain blank lines. I.e., these two
d1be9408 784lines, which have a blank line between them:
8a93676d 785
786 use Foo;
787
788 print Foo->VERSION
789
790should be unified into one paragraph ("\tuse Foo;\n\n\tprint
791Foo->VERSION") before being passed to the formatter or other
792processor. Parsers may also allow an option for overriding this.
793
794While this might be too cumbersome to implement in event-based Pod
795parsers, it is straightforward for parsers that return parse trees.
796
797=item *
798
799Pod formatters, where feasible, are advised to avoid splitting short
800verbatim paragraphs (under twelve lines, say) across pages.
801
802=item *
803
804Pod parsers must treat a line with only spaces and/or tabs on it as a
805"blank line" such as separates paragraphs. (Some older parsers
806recognized only two adjacent newlines as a "blank line" but would not
807recognize a newline, a space, and a newline, as a blank line. This
808is noncompliant behavior.)
809
810=item *
811
812Authors of Pod formatters/processors should make every effort to
813avoid writing their own Pod parser. There are already several in
814CPAN, with a wide range of interface styles -- and one of them,
815Pod::Parser, comes with modern versions of Perl.
816
817=item *
818
819Characters in Pod documents may be conveyed either as literals, or by
820number in EE<lt>n> codes, or by an equivalent mnemonic, as in
821EE<lt>eacute> which is exactly equivalent to EE<lt>233>.
822
823Characters in the range 32-126 refer to those well known US-ASCII
824characters (also defined there by Unicode, with the same meaning),
825which all Pod formatters must render faithfully. Characters
826in the ranges 0-31 and 127-159 should not be used (neither as
827literals, nor as EE<lt>number> codes), except for the
210b36aa 828literal byte-sequences for newline (13, 13 10, or 10), and tab (9).
8a93676d 829
830Characters in the range 160-255 refer to Latin-1 characters (also
831defined there by Unicode, with the same meaning). Characters above
832255 should be understood to refer to Unicode characters.
833
834=item *
835
836Be warned
837that some formatters cannot reliably render characters outside 32-126;
838and many are able to handle 32-126 and 160-255, but nothing above
839255.
840
841=item *
842
843Besides the well-known "EE<lt>lt>" and "EE<lt>gt>" codes for
844less-than and greater-than, Pod parsers must understand "EE<lt>sol>"
845for "/" (solidus, slash), and "EE<lt>verbar>" for "|" (vertical bar,
846pipe). Pod parsers should also understand "EE<lt>lchevron>" and
847"EE<lt>rchevron>" as legacy codes for characters 171 and 187, i.e.,
848"left-pointing double angle quotation mark" = "left pointing
849guillemet" and "right-pointing double angle quotation mark" = "right
850pointing guillemet". (These look like little "<<" and ">>", and they
851are now preferably expressed with the HTML/XHTML codes "EE<lt>laquo>"
852and "EE<lt>raquo>".)
853
854=item *
855
856Pod parsers should understand all "EE<lt>html>" codes as defined
857in the entity declarations in the most recent XHTML specification at
858C<www.W3.org>. Pod parsers must understand at least the entities
859that define characters in the range 160-255 (Latin-1). Pod parsers,
860when faced with some unknown "EE<lt>I<identifier>>" code,
861shouldn't simply replace it with nullstring (by default, at least),
862but may pass it through as a string consisting of the literal characters
863E, less-than, I<identifier>, greater-than. Or Pod parsers may offer the
864alternative option of processing such unknown
865"EE<lt>I<identifier>>" codes by firing an event especially
866for such codes, or by adding a special node-type to the in-memory
867document tree. Such "EE<lt>I<identifier>>" may have special meaning
868to some processors, or some processors may choose to add them to
869a special error report.
870
871=item *
872
873Pod parsers must also support the XHTML codes "EE<lt>quot>" for
874character 34 (doublequote, "), "EE<lt>amp>" for character 38
875(ampersand, &), and "EE<lt>apos>" for character 39 (apostrophe, ').
876
877=item *
878
879Note that in all cases of "EE<lt>whatever>", I<whatever> (whether
880an htmlname, or a number in any base) must consist only of
881alphanumeric characters -- that is, I<whatever> must watch
882C<m/\A\w+\z/>. So "EE<lt> 0 1 2 3 >" is invalid, because
883it contains spaces, which aren't alphanumeric characters. This
884presumably does not I<need> special treatment by a Pod processor;
885" 0 1 2 3 " doesn't look like a number in any base, so it would
886presumably be looked up in the table of HTML-like names. Since
210b36aa 887there isn't (and cannot be) an HTML-like entity called " 0 1 2 3 ",
8a93676d 888this will be treated as an error. However, Pod processors may
889treat "EE<lt> 0 1 2 3 >" or "EE<lt>e-acute>" as I<syntactically>
890invalid, potentially earning a different error message than the
891error message (or warning, or event) generated by a merely unknown
892(but theoretically valid) htmlname, as in "EE<lt>qacute>"
893[sic]. However, Pod parsers are not required to make this
894distinction.
895
896=item *
897
898Note that EE<lt>number> I<must not> be interpreted as simply
899"codepoint I<number> in the current/native character set". It always
900means only "the character represented by codepoint I<number> in
901Unicode." (This is identical to the semantics of &#I<number>; in XML.)
902
903This will likely require many formatters to have tables mapping from
904treatable Unicode codepoints (such as the "\xE9" for the e-acute
905character) to the escape sequences or codes necessary for conveying
906such sequences in the target output format. A converter to *roff
907would, for example know that "\xE9" (whether conveyed literally, or via
908a EE<lt>...> sequence) is to be conveyed as "e\\*'".
8939ba94 909Similarly, a program rendering Pod in a Mac OS application window, would
8a93676d 910presumably need to know that "\xE9" maps to codepoint 142 in MacRoman
8939ba94 911encoding that (at time of writing) is native for Mac OS. Such
8a93676d 912Unicode2whatever mappings are presumably already widely available for
913common output formats. (Such mappings may be incomplete! Implementers
914are not expected to bend over backwards in an attempt to render
915Cherokee syllabics, Etruscan runes, Byzantine musical symbols, or any
916of the other weird things that Unicode can encode.) And
917if a Pod document uses a character not found in such a mapping, the
918formatter should consider it an unrenderable character.
919
920=item *
921
922If, surprisingly, the implementor of a Pod formatter can't find a
923satisfactory pre-existing table mapping from Unicode characters to
924escapes in the target format (e.g., a decent table of Unicode
925characters to *roff escapes), it will be necessary to build such a
926table. If you are in this circumstance, you should begin with the
927characters in the range 0x00A0 - 0x00FF, which is mostly the heavily
928used accented characters. Then proceed (as patience permits and
929fastidiousness compels) through the characters that the (X)HTML
930standards groups judged important enough to merit mnemonics
931for. These are declared in the (X)HTML specifications at the
932www.W3.org site. At time of writing (September 2001), the most recent
933entity declaration files are:
934
935 http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
936 http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
937 http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent
938
939Then you can progress through any remaining notable Unicode characters
940in the range 0x2000-0x204D (consult the character tables at
941www.unicode.org), and whatever else strikes your fancy. For example,
942in F<xhtml-symbol.ent>, there is the entry:
943
944 <!ENTITY infin "&#8734;"> <!-- infinity, U+221E ISOtech -->
945
946While the mapping "infin" to the character "\x{221E}" will (hopefully)
947have been already handled by the Pod parser, the presence of the
948character in this file means that it's reasonably important enough to
949include in a formatter's table that maps from notable Unicode characters
950to the codes necessary for rendering them. So for a Unicode-to-*roff
951mapping, for example, this would merit the entry:
952
953 "\x{221E}" => '\(in',
954
955It is eagerly hoped that in the future, increasing numbers of formats
956(and formatters) will support Unicode characters directly (as (X)HTML
957does with C<&infin;>, C<&#8734;>, or C<&#x221E;>), reducing the need
958for idiosyncratic mappings of Unicode-to-I<my_escapes>.
959
960=item *
961
962It is up to individual Pod formatter to display good judgment when
963confronted with an unrenderable character (which is distinct from an
964unknown EE<lt>thing> sequence that the parser couldn't resolve to
965anything, renderable or not). It is good practice to map Latin letters
966with diacritics (like "EE<lt>eacute>"/"EE<lt>233>") to the corresponding
967unaccented US-ASCII letters (like a simple character 101, "e"), but
210b36aa 968clearly this is often not feasible, and an unrenderable character may
8a93676d 969be represented as "?", or the like. In attempting a sane fallback
970(as from EE<lt>233> to "e"), Pod formatters may use the
971%Latin1Code_to_fallback table in L<Pod::Escapes|Pod::Escapes>, or
972L<Text::Unidecode|Text::Unidecode>, if available.
973
974For example, this Pod text:
975
976 magic is enabled if you set C<$Currency> to 'E<euro>'.
977
978may be rendered as:
979"magic is enabled if you set C<$Currency> to 'I<?>'" or as
980"magic is enabled if you set C<$Currency> to 'B<[euro]>'", or as
981"magic is enabled if you set C<$Currency> to '[x20AC]', etc.
982
983A Pod formatter may also note, in a comment or warning, a list of what
984unrenderable characters were encountered.
985
986=item *
987
988EE<lt>...> may freely appear in any formatting code (other than
989in another EE<lt>...> or in an ZE<lt>>). That is, "XE<lt>The
990EE<lt>euro>1,000,000 Solution>" is valid, as is "LE<lt>The
991EE<lt>euro>1,000,000 Solution|Million::Euros>".
992
993=item *
994
3e666715 995Some Pod formatters output to formats that implement non-breaking
8a93676d 996spaces as an individual character (which I'll call "NBSP"), and
3e666715 997others output to formats that implement non-breaking spaces just as
8a93676d 998spaces wrapped in a "don't break this across lines" code. Note that
999at the level of Pod, both sorts of codes can occur: Pod can contain a
1000NBSP character (whether as a literal, or as a "EE<lt>160>" or
1001"EE<lt>nbsp>" code); and Pod can contain "SE<lt>foo
1002IE<lt>barE<gt> baz>" codes, where "mere spaces" (character 32) in
3e666715 1003such codes are taken to represent non-breaking spaces. Pod
8a93676d 1004parsers should consider supporting the optional parsing of "SE<lt>foo
1005IE<lt>barE<gt> baz>" as if it were
1006"fooI<NBSP>IE<lt>barE<gt>I<NBSP>baz", and, going the other way, the
1007optional parsing of groups of words joined by NBSP's as if each group
1008were in a SE<lt>...> code, so that formatters may use the
1009representation that maps best to what the output format demands.
1010
1011=item *
1012
210b36aa 1013Some processors may find that the C<SE<lt>...E<gt>> code is easiest to
8a93676d 1014implement by replacing each space in the parse tree under the content
1015of the S, with an NBSP. But note: the replacement should apply I<not> to
1016spaces in I<all> text, but I<only> to spaces in I<printable> text. (This
1017distinction may or may not be evident in the particular tree/event
1018model implemented by the Pod parser.) For example, consider this
1019unusual case:
1020
1021 S<L</Autoloaded Functions>>
1022
1023This means that the space in the middle of the visible link text must
1024not be broken across lines. In other words, it's the same as this:
1025
1026 L<"AutoloadedE<160>Functions"/Autoloaded Functions>
1027
1028However, a misapplied space-to-NBSP replacement could (wrongly)
1029produce something equivalent to this:
1030
1031 L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions>
1032
1033...which is almost definitely not going to work as a hyperlink (assuming
1034this formatter outputs a format supporting hypertext).
1035
1036Formatters may choose to just not support the S format code,
1037especially in cases where the output format simply has no NBSP
1038character/code and no code for "don't break this stuff across lines".
1039
1040=item *
1041
1042Besides the NBSP character discussed above, implementors are reminded
1043of the existence of the other "special" character in Latin-1, the
210b36aa 1044"soft hyphen" character, also known as "discretionary hyphen",
8a93676d 1045i.e. C<EE<lt>173E<gt>> = C<EE<lt>0xADE<gt>> =
1046C<EE<lt>shyE<gt>>). This character expresses an optional hyphenation
1047point. That is, it normally renders as nothing, but may render as a
1048"-" if a formatter breaks the word at that point. Pod formatters
1049should, as appropriate, do one of the following: 1) render this with
1050a code with the same meaning (e.g., "\-" in RTF), 2) pass it through
1051in the expectation that the formatter understands this character as
1052such, or 3) delete it.
1053
1054For example:
1055
1056 sigE<shy>action
1057 manuE<shy>script
1058 JarkE<shy>ko HieE<shy>taE<shy>nieE<shy>mi
1059
1060These signal to a formatter that if it is to hyphenate "sigaction"
1061or "manuscript", then it should be done as
1062"sig-I<[linebreak]>action" or "manu-I<[linebreak]>script"
1063(and if it doesn't hyphenate it, then the C<EE<lt>shyE<gt>> doesn't
1064show up at all). And if it is
1065to hyphenate "Jarkko" and/or "Hietaniemi", it can do
1066so only at the points where there is a C<EE<lt>shyE<gt>> code.
1067
1068In practice, it is anticipated that this character will not be used
1069often, but formatters should either support it, or delete it.
1070
1071=item *
1072
1073If you think that you want to add a new command to Pod (like, say, a
1074"=biblio" command), consider whether you could get the same
1075effect with a for or begin/end sequence: "=for biblio ..." or "=begin
1076biblio" ... "=end biblio". Pod processors that don't understand
1077"=for biblio", etc, will simply ignore it, whereas they may complain
1078loudly if they see "=biblio".
1079
1080=item *
1081
1082Throughout this document, "Pod" has been the preferred spelling for
1083the name of the documentation format. One may also use "POD" or
da75cd15 1084"pod". For the documentation that is (typically) in the Pod
8a93676d 1085format, you may use "pod", or "Pod", or "POD". Understanding these
1086distinctions is useful; but obsessing over how to spell them, usually
1087is not.
1088
1089=back
1090
1091
1092
1093
1094
1095=head1 About LE<lt>...E<gt> Codes
1096
1097As you can tell from a glance at L<perlpod|perlpod>, the LE<lt>...>
1098code is the most complex of the Pod formatting codes. The points below
1099will hopefully clarify what it means and how processors should deal
1100with it.
1101
1102=over
1103
1104=item *
1105
1106In parsing an LE<lt>...> code, Pod parsers must distinguish at least
1107four attributes:
1108
1109=over
1110
1111=item First:
1112
1113The link-text. If there is none, this must be undef. (E.g., in
1114"LE<lt>Perl Functions|perlfunc>", the link-text is "Perl Functions".
1115In "LE<lt>Time::HiRes>" and even "LE<lt>|Time::HiRes>", there is no
1116link text. Note that link text may contain formatting.)
1117
1118=item Second:
1119
1120The possibly inferred link-text -- i.e., if there was no real link
1121text, then this is the text that we'll infer in its place. (E.g., for
1122"LE<lt>Getopt::Std>", the inferred link text is "Getopt::Std".)
1123
1124=item Third:
1125
1126The name or URL, or undef if none. (E.g., in "LE<lt>Perl
1127Functions|perlfunc>", the name -- also sometimes called the page --
1128is "perlfunc". In "LE<lt>/CAVEATS>", the name is undef.)
1129
1130=item Fourth:
1131
1132The section (AKA "item" in older perlpods), or undef if none. E.g.,
1133in L<Getopt::Std/DESCRIPTION>, "DESCRIPTION" is the section. (Note
1134that this is not the same as a manpage section like the "5" in "man 5
1135crontab". "Section Foo" in the Pod sense means the part of the text
6edf2346 1136that's introduced by the heading or item whose text is "Foo".)
8a93676d 1137
1138=back
1139
1140Pod parsers may also note additional attributes including:
1141
1142=over
1143
1144=item Fifth:
1145
1146A flag for whether item 3 (if present) is a URL (like
1147"http://lists.perl.org" is), in which case there should be no section
1148attribute; a Pod name (like "perldoc" and "Getopt::Std" are); or
1149possibly a man page name (like "crontab(5)" is).
1150
1151=item Sixth:
1152
1153The raw original LE<lt>...> content, before text is split on
1154"|", "/", etc, and before EE<lt>...> codes are expanded.
1155
1156=back
1157
1158(The above were numbered only for concise reference below. It is not
1159a requirement that these be passed as an actual list or array.)
1160
1161For example:
1162
1163 L<Foo::Bar>
1164 => undef, # link text
1165 "Foo::Bar", # possibly inferred link text
1166 "Foo::Bar", # name
1167 undef, # section
1168 'pod', # what sort of link
1169 "Foo::Bar" # original content
1170
1171 L<Perlport's section on NL's|perlport/Newlines>
1172 => "Perlport's section on NL's", # link text
1173 "Perlport's section on NL's", # possibly inferred link text
1174 "perlport", # name
1175 "Newlines", # section
1176 'pod', # what sort of link
1177 "Perlport's section on NL's|perlport/Newlines" # orig. content
1178
1179 L<perlport/Newlines>
1180 => undef, # link text
1181 '"Newlines" in perlport', # possibly inferred link text
1182 "perlport", # name
1183 "Newlines", # section
1184 'pod', # what sort of link
1185 "perlport/Newlines" # original content
1186
1187 L<crontab(5)/"DESCRIPTION">
1188 => undef, # link text
1189 '"DESCRIPTION" in crontab(5)', # possibly inferred link text
1190 "crontab(5)", # name
1191 "DESCRIPTION", # section
1192 'man', # what sort of link
1193 'crontab(5)/"DESCRIPTION"' # original content
1194
1195 L</Object Attributes>
1196 => undef, # link text
1197 '"Object Attributes"', # possibly inferred link text
1198 undef, # name
1199 "Object Attributes", # section
1200 'pod', # what sort of link
1201 "/Object Attributes" # original content
1202
1203 L<http://www.perl.org/>
1204 => undef, # link text
1205 "http://www.perl.org/", # possibly inferred link text
1206 "http://www.perl.org/", # name
1207 undef, # section
1208 'url', # what sort of link
1209 "http://www.perl.org/" # original content
1210
1211Note that you can distinguish URL-links from anything else by the
1212fact that they match C<m/\A\w+:[^:\s]\S*\z/>. So
1213C<LE<lt>http://www.perl.comE<gt>> is a URL, but
1214C<LE<lt>HTTP::ResponseE<gt>> isn't.
1215
1216=item *
1217
1218In case of LE<lt>...> codes with no "text|" part in them,
1219older formatters have exhibited great variation in actually displaying
1220the link or cross reference. For example, LE<lt>crontab(5)> would render
1221as "the C<crontab(5)> manpage", or "in the C<crontab(5)> manpage"
1222or just "C<crontab(5)>".
1223
1224Pod processors must now treat "text|"-less links as follows:
1225
1226 L<name> => L<name|name>
1227 L</section> => L<"section"|/section>
1228 L<name/section> => L<"section" in name|name/section>
1229
1230=item *
1231
1232Note that section names might contain markup. I.e., if a section
1233starts with:
1234
1235 =head2 About the C<-M> Operator
1236
1237or with:
1238
1239 =item About the C<-M> Operator
1240
1241then a link to it would look like this:
1242
1243 L<somedoc/About the C<-M> Operator>
1244
1245Formatters may choose to ignore the markup for purposes of resolving
1246the link and use only the renderable characters in the section name,
1247as in:
1248
1249 <h1><a name="About_the_-M_Operator">About the <code>-M</code>
1250 Operator</h1>
210b36aa 1251
8a93676d 1252 ...
210b36aa 1253
8a93676d 1254 <a href="somedoc#About_the_-M_Operator">About the <code>-M</code>
1255 Operator" in somedoc</a>
1256
1257=item *
1258
1259Previous versions of perlpod distinguished C<LE<lt>name/"section"E<gt>>
1260links from C<LE<lt>name/itemE<gt>> links (and their targets). These
1261have been merged syntactically and semantically in the current
1262specification, and I<section> can refer either to a "=headI<n> Heading
1263Content" command or to a "=item Item Content" command. This
1264specification does not specify what behavior should be in the case
1265of a given document having several things all seeming to produce the
1266same I<section> identifier (e.g., in HTML, several things all producing
1267the same I<anchorname> in <a name="I<anchorname>">...</a>
1268elements). Where Pod processors can control this behavior, they should
1269use the first such anchor. That is, C<LE<lt>Foo/BarE<gt>> refers to the
1270I<first> "Bar" section in Foo.
1271
1272But for some processors/formats this cannot be easily controlled; as
1273with the HTML example, the behavior of multiple ambiguous
1274<a name="I<anchorname>">...</a> is most easily just left up to
1275browsers to decide.
1276
1277=item *
1278
1279Authors wanting to link to a particular (absolute) URL, must do so
1280only with "LE<lt>scheme:...>" codes (like
1281LE<lt>http://www.perl.org>), and must not attempt "LE<lt>Some Site
1282Name|scheme:...>" codes. This restriction avoids many problems
1283in parsing and rendering LE<lt>...> codes.
1284
1285=item *
1286
1287In a C<LE<lt>text|...E<gt>> code, text may contain formatting codes
1288for formatting or for EE<lt>...> escapes, as in:
1289
1290 L<B<ummE<234>stuff>|...>
1291
1292For C<LE<lt>...E<gt>> codes without a "name|" part, only
1293C<EE<lt>...E<gt>> and C<ZE<lt>E<gt>> codes may occur -- no
1294other formatting codes. That is, authors should not use
1295"C<LE<lt>BE<lt>Foo::BarE<gt>E<gt>>".
1296
1297Note, however, that formatting codes and ZE<lt>>'s can occur in any
1298and all parts of an LE<lt>...> (i.e., in I<name>, I<section>, I<text>,
1299and I<url>).
1300
1301Authors must not nest LE<lt>...> codes. For example, "LE<lt>The
1302LE<lt>Foo::Bar> man page>" should be treated as an error.
1303
1304=item *
1305
1306Note that Pod authors may use formatting codes inside the "text"
1307part of "LE<lt>text|name>" (and so on for LE<lt>text|/"sec">).
1308
1309In other words, this is valid:
1310
1311 Go read L<the docs on C<$.>|perlvar/"$.">
1312
1313Some output formats that do allow rendering "LE<lt>...>" codes as
1314hypertext, might not allow the link-text to be formatted; in
1315that case, formatters will have to just ignore that formatting.
1316
1317=item *
1318
1319At time of writing, C<LE<lt>nameE<gt>> values are of two types:
1320either the name of a Pod page like C<LE<lt>Foo::BarE<gt>> (which
1321might be a real Perl module or program in an @INC / PATH
1322directory, or a .pod file in those places); or the name of a UNIX
1323man page, like C<LE<lt>crontab(5)E<gt>>. In theory, C<LE<lt>chmodE<gt>>
1324in ambiguous between a Pod page called "chmod", or the Unix man page
1325"chmod" (in whatever man-section). However, the presence of a string
1326in parens, as in "crontab(5)", is sufficient to signal that what
1327is being discussed is not a Pod page, and so is presumably a
1328UNIX man page. The distinction is of no importance to many
1329Pod processors, but some processors that render to hypertext formats
1330may need to distinguish them in order to know how to render a
1331given C<LE<lt>fooE<gt>> code.
1332
1333=item *
1334
1335Previous versions of perlpod allowed for a C<LE<lt>sectionE<gt>> syntax
1336(as in "C<LE<lt>Object AttributesE<gt>>"), which was not easily distinguishable
1337from C<LE<lt>nameE<gt>> syntax. This syntax is no longer in the
1338specification, and has been replaced by the C<LE<lt>"section"E<gt>> syntax
1339(where the quotes were formerly optional). Pod parsers should tolerate
1340the C<LE<lt>sectionE<gt>> syntax, for a while at least. The suggested
1341heuristic for distinguishing C<LE<lt>sectionE<gt>> from C<LE<lt>nameE<gt>>
1342is that if it contains any whitespace, it's a I<section>. Pod processors
1343may warn about this being deprecated syntax.
1344
1345=back
1346
1347=head1 About =over...=back Regions
1348
1349"=over"..."=back" regions are used for various kinds of list-like
1350structures. (I use the term "region" here simply as a collective
1351term for everything from the "=over" to the matching "=back".)
1352
1353=over
1354
1355=item *
1356
1357The non-zero numeric I<indentlevel> in "=over I<indentlevel>" ...
1358"=back" is used for giving the formatter a clue as to how many
1359"spaces" (ems, or roughly equivalent units) it should tab over,
1360although many formatters will have to convert this to an absolute
1361measurement that may not exactly match with the size of spaces (or M's)
1362in the document's base font. Other formatters may have to completely
1363ignore the number. The lack of any explicit I<indentlevel> parameter is
1364equivalent to an I<indentlevel> value of 4. Pod processors may
1365complain if I<indentlevel> is present but is not a positive number
1366matching C<m/\A(\d*\.)?\d+\z/>.
1367
1368=item *
1369
1370Authors of Pod formatters are reminded that "=over" ... "=back" may
1371map to several different constructs in your output format. For
1372example, in converting Pod to (X)HTML, it can map to any of
1373<ul>...</ul>, <ol>...</ol>, <dl>...</dl>, or
1374<blockquote>...</blockquote>. Similarly, "=item" can map to <li> or
1375<dt>.
1376
1377=item *
1378
1379Each "=over" ... "=back" region should be one of the following:
1380
1381=over
1382
1383=item *
1384
1385An "=over" ... "=back" region containing only "=item *" commands,
1386each followed by some number of ordinary/verbatim paragraphs, other
1387nested "=over" ... "=back" regions, "=for..." paragraphs, and
1388"=begin"..."=end" regions.
1389
1390(Pod processors must tolerate a bare "=item" as if it were "=item
1391*".) Whether "*" is rendered as a literal asterisk, an "o", or as
1392some kind of real bullet character, is left up to the Pod formatter,
1393and may depend on the level of nesting.
1394
1395=item *
1396
1397An "=over" ... "=back" region containing only
1398C<m/\A=item\s+\d+\.?\s*\z/> paragraphs, each one (or each group of them)
1399followed by some number of ordinary/verbatim paragraphs, other nested
1400"=over" ... "=back" regions, "=for..." paragraphs, and/or
1401"=begin"..."=end" codes. Note that the numbers must start at 1
1402in each section, and must proceed in order and without skipping
1403numbers.
1404
1405(Pod processors must tolerate lines like "=item 1" as if they were
1406"=item 1.", with the period.)
1407
1408=item *
1409
1410An "=over" ... "=back" region containing only "=item [text]"
1411commands, each one (or each group of them) followed by some number of
1412ordinary/verbatim paragraphs, other nested "=over" ... "=back"
1413regions, or "=for..." paragraphs, and "=begin"..."=end" regions.
1414
1415The "=item [text]" paragraph should not match
1416C<m/\A=item\s+\d+\.?\s*\z/> or C<m/\A=item\s+\*\s*\z/>, nor should it
1417match just C<m/\A=item\s*\z/>.
1418
1419=item *
1420
1421An "=over" ... "=back" region containing no "=item" paragraphs at
1422all, and containing only some number of
1423ordinary/verbatim paragraphs, and possibly also some nested "=over"
1424... "=back" regions, "=for..." paragraphs, and "=begin"..."=end"
1425regions. Such an itemless "=over" ... "=back" region in Pod is
1426equivalent in meaning to a "<blockquote>...</blockquote>" element in
1427HTML.
1428
1429=back
1430
1431Note that with all the above cases, you can determine which type of
1432"=over" ... "=back" you have, by examining the first (non-"=cut",
1433non-"=pod") Pod paragraph after the "=over" command.
1434
1435=item *
1436
1437Pod formatters I<must> tolerate arbitrarily large amounts of text
1438in the "=item I<text...>" paragraph. In practice, most such
1439paragraphs are short, as in:
1440
1441 =item For cutting off our trade with all parts of the world
1442
1443But they may be arbitrarily long:
1444
1445 =item For transporting us beyond seas to be tried for pretended
1446 offenses
1447
1448 =item He is at this time transporting large armies of foreign
1449 mercenaries to complete the works of death, desolation and
1450 tyranny, already begun with circumstances of cruelty and perfidy
1451 scarcely paralleled in the most barbarous ages, and totally
1452 unworthy the head of a civilized nation.
1453
1454=item *
1455
1456Pod processors should tolerate "=item *" / "=item I<number>" commands
1457with no accompanying paragraph. The middle item is an example:
1458
1459 =over
210b36aa 1460
8a93676d 1461 =item 1
210b36aa 1462
8a93676d 1463 Pick up dry cleaning.
210b36aa 1464
8a93676d 1465 =item 2
210b36aa 1466
8a93676d 1467 =item 3
210b36aa 1468
8a93676d 1469 Stop by the store. Get Abba Zabas, Stoli, and cheap lawn chairs.
210b36aa 1470
8a93676d 1471 =back
1472
1473=item *
1474
1475No "=over" ... "=back" region can contain headings. Processors may
1476treat such a heading as an error.
1477
1478=item *
1479
1480Note that an "=over" ... "=back" region should have some
1481content. That is, authors should not have an empty region like this:
1482
1483 =over
210b36aa 1484
8a93676d 1485 =back
1486
1487Pod processors seeing such a contentless "=over" ... "=back" region,
1488may ignore it, or may report it as an error.
1489
1490=item *
1491
1492Processors must tolerate an "=over" list that goes off the end of the
1493document (i.e., which has no matching "=back"), but they may warn
1494about such a list.
1495
1496=item *
1497
1498Authors of Pod formatters should note that this construct:
1499
1500 =item Neque
1501
1502 =item Porro
1503
1504 =item Quisquam Est
210b36aa 1505
8a93676d 1506 Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
1507 velit, sed quia non numquam eius modi tempora incidunt ut
1508 labore et dolore magnam aliquam quaerat voluptatem.
1509
1510 =item Ut Enim
1511
1512is semantically ambiguous, in a way that makes formatting decisions
1513a bit difficult. On the one hand, it could be mention of an item
1514"Neque", mention of another item "Porro", and mention of another
1515item "Quisquam Est", with just the last one requiring the explanatory
1516paragraph "Qui dolorem ipsum quia dolor..."; and then an item
1517"Ut Enim". In that case, you'd want to format it like so:
1518
1519 Neque
210b36aa 1520
8a93676d 1521 Porro
210b36aa 1522
8a93676d 1523 Quisquam Est
1524 Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
1525 velit, sed quia non numquam eius modi tempora incidunt ut
1526 labore et dolore magnam aliquam quaerat voluptatem.
1527
1528 Ut Enim
1529
1530But it could equally well be a discussion of three (related or equivalent)
1531items, "Neque", "Porro", and "Quisquam Est", followed by a paragraph
1532explaining them all, and then a new item "Ut Enim". In that case, you'd
1533probably want to format it like so:
1534
1535 Neque
1536 Porro
1537 Quisquam Est
1538 Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
1539 velit, sed quia non numquam eius modi tempora incidunt ut
1540 labore et dolore magnam aliquam quaerat voluptatem.
1541
1542 Ut Enim
1543
1544But (for the forseeable future), Pod does not provide any way for Pod
1545authors to distinguish which grouping is meant by the above
1546"=item"-cluster structure. So formatters should format it like so:
1547
1548 Neque
1549
1550 Porro
1551
1552 Quisquam Est
1553
1554 Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
1555 velit, sed quia non numquam eius modi tempora incidunt ut
1556 labore et dolore magnam aliquam quaerat voluptatem.
1557
1558 Ut Enim
1559
210b36aa 1560That is, there should be (at least roughly) equal spacing between
8a93676d 1561items as between paragraphs (although that spacing may well be less
1562than the full height of a line of text). This leaves it to the reader
1563to use (con)textual cues to figure out whether the "Qui dolorem
1564ipsum..." paragraph applies to the "Quisquam Est" item or to all three
1565items "Neque", "Porro", and "Quisquam Est". While not an ideal
1566situation, this is preferable to providing formatting cues that may
1567be actually contrary to the author's intent.
1568
1569=back
1570
1571
1572
1573=head1 About Data Paragraphs and "=begin/=end" Regions
1574
1575Data paragraphs are typically used for inlining non-Pod data that is
1576to be used (typically passed through) when rendering the document to
1577a specific format:
1578
1579 =begin rtf
210b36aa 1580
8a93676d 1581 \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}
210b36aa 1582
8a93676d 1583 =end rtf
1584
1585The exact same effect could, incidentally, be achieved with a single
1586"=for" paragraph:
1587
1588 =for rtf \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}
1589
1590(Although that is not formally a data paragraph, it has the same
1591meaning as one, and Pod parsers may parse it as one.)
1592
1593Another example of a data paragraph:
1594
1595 =begin html
210b36aa 1596
8a93676d 1597 I like <em>PIE</em>!
210b36aa 1598
8a93676d 1599 <hr>Especially pecan pie!
210b36aa 1600
8a93676d 1601 =end html
1602
1603If these were ordinary paragraphs, the Pod parser would try to
1604expand the "EE<lt>/em>" (in the first paragraph) as a formatting
1605code, just like "EE<lt>lt>" or "EE<lt>eacute>". But since this
1606is in a "=begin I<identifier>"..."=end I<identifier>" region I<and>
1607the identifier "html" doesn't begin have a ":" prefix, the contents
1608of this region are stored as data paragraphs, instead of being
1609processed as ordinary paragraphs (or if they began with a spaces
1610and/or tabs, as verbatim paragraphs).
1611
1612As a further example: At time of writing, no "biblio" identifier is
1613supported, but suppose some processor were written to recognize it as
1614a way of (say) denoting a bibliographic reference (necessarily
1615containing formatting codes in ordinary paragraphs). The fact that
1616"biblio" paragraphs were meant for ordinary processing would be
1617indicated by prefacing each "biblio" identifier with a colon:
1618
1619 =begin :biblio
1620
1621 Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
1622 Programs.> Prentice-Hall, Englewood Cliffs, NJ.
1623
1624 =end :biblio
1625
1626This would signal to the parser that paragraphs in this begin...end
1627region are subject to normal handling as ordinary/verbatim paragraphs
1628(while still tagged as meant only for processors that understand the
1629"biblio" identifier). The same effect could be had with:
1630
1631 =for :biblio
1632 Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
1633 Programs.> Prentice-Hall, Englewood Cliffs, NJ.
1634
1635The ":" on these identifiers means simply "process this stuff
1636normally, even though the result will be for some special target".
1637I suggest that parser APIs report "biblio" as the target identifier,
1638but also report that it had a ":" prefix. (And similarly, with the
1639above "html", report "html" as the target identifier, and note the
1640I<lack> of a ":" prefix.)
1641
1642Note that a "=begin I<identifier>"..."=end I<identifier>" region where
1643I<identifier> begins with a colon, I<can> contain commands. For example:
1644
1645 =begin :biblio
210b36aa 1646
8a93676d 1647 Wirth's classic is available in several editions, including:
210b36aa 1648
8a93676d 1649 =for comment
1650 hm, check abebooks.com for how much used copies cost.
210b36aa 1651
8a93676d 1652 =over
210b36aa 1653
8a93676d 1654 =item
210b36aa 1655
8a93676d 1656 Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.>
1657 Teubner, Stuttgart. [Yes, it's in German.]
210b36aa 1658
8a93676d 1659 =item
210b36aa 1660
8a93676d 1661 Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
1662 Programs.> Prentice-Hall, Englewood Cliffs, NJ.
210b36aa 1663
8a93676d 1664 =back
210b36aa 1665
8a93676d 1666 =end :biblio
1667
1668Note, however, a "=begin I<identifier>"..."=end I<identifier>"
1669region where I<identifier> does I<not> begin with a colon, should not
1670directly contain "=head1" ... "=head4" commands, nor "=over", nor "=back",
1671nor "=item". For example, this may be considered invalid:
1672
1673 =begin somedata
210b36aa 1674
8a93676d 1675 This is a data paragraph.
210b36aa 1676
8a93676d 1677 =head1 Don't do this!
210b36aa 1678
8a93676d 1679 This is a data paragraph too.
210b36aa 1680
8a93676d 1681 =end somedata
1682
1683A Pod processor may signal that the above (specifically the "=head1"
1684paragraph) is an error. Note, however, that the following should
1685I<not> be treated as an error:
1686
1687 =begin somedata
210b36aa 1688
8a93676d 1689 This is a data paragraph.
210b36aa 1690
8a93676d 1691 =cut
210b36aa 1692
8a93676d 1693 # Yup, this isn't Pod anymore.
1694 sub excl { (rand() > .5) ? "hoo!" : "hah!" }
210b36aa 1695
8a93676d 1696 =pod
210b36aa 1697
8a93676d 1698 This is a data paragraph too.
210b36aa 1699
8a93676d 1700 =end somedata
1701
1702And this too is valid:
1703
1704 =begin someformat
210b36aa 1705
8a93676d 1706 This is a data paragraph.
210b36aa 1707
8a93676d 1708 And this is a data paragraph.
210b36aa 1709
8a93676d 1710 =begin someotherformat
210b36aa 1711
8a93676d 1712 This is a data paragraph too.
210b36aa 1713
8a93676d 1714 And this is a data paragraph too.
210b36aa 1715
8a93676d 1716 =begin :yetanotherformat
1717
1718 =head2 This is a command paragraph!
1719
1720 This is an ordinary paragraph!
210b36aa 1721
8a93676d 1722 And this is a verbatim paragraph!
210b36aa 1723
8a93676d 1724 =end :yetanotherformat
210b36aa 1725
8a93676d 1726 =end someotherformat
210b36aa 1727
8a93676d 1728 Another data paragraph!
210b36aa 1729
8a93676d 1730 =end someformat
1731
1732The contents of the above "=begin :yetanotherformat" ...
1733"=end :yetanotherformat" region I<aren't> data paragraphs, because
1734the immediately containing region's identifier (":yetanotherformat")
1735begins with a colon. In practice, most regions that contain
1736data paragraphs will contain I<only> data paragraphs; however,
1737the above nesting is syntactically valid as Pod, even if it is
1738rare. However, the handlers for some formats, like "html",
1739will accept only data paragraphs, not nested regions; and they may
1740complain if they see (targeted for them) nested regions, or commands,
1741other than "=end", "=pod", and "=cut".
1742
1743Also consider this valid structure:
1744
1745 =begin :biblio
210b36aa 1746
8a93676d 1747 Wirth's classic is available in several editions, including:
210b36aa 1748
8a93676d 1749 =over
210b36aa 1750
8a93676d 1751 =item
210b36aa 1752
8a93676d 1753 Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.>
1754 Teubner, Stuttgart. [Yes, it's in German.]
210b36aa 1755
8a93676d 1756 =item
210b36aa 1757
8a93676d 1758 Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
1759 Programs.> Prentice-Hall, Englewood Cliffs, NJ.
1760
1761 =back
210b36aa 1762
8a93676d 1763 Buy buy buy!
210b36aa 1764
8a93676d 1765 =begin html
210b36aa 1766
8a93676d 1767 <img src='wirth_spokesmodeling_book.png'>
210b36aa 1768
8a93676d 1769 <hr>
210b36aa 1770
8a93676d 1771 =end html
210b36aa 1772
8a93676d 1773 Now now now!
210b36aa 1774
8a93676d 1775 =end :biblio
1776
1777There, the "=begin html"..."=end html" region is nested inside
1778the larger "=begin :biblio"..."=end :biblio" region. Note that the
1779content of the "=begin html"..."=end html" region is data
1780paragraph(s), because the immediately containing region's identifier
1781("html") I<doesn't> begin with a colon.
1782
1783Pod parsers, when processing a series of data paragraphs one
1784after another (within a single region), should consider them to
1785be one large data paragraph that happens to contain blank lines. So
1786the content of the above "=begin html"..."=end html" I<may> be stored
1787as two data paragraphs (one consisting of
1788"<img src='wirth_spokesmodeling_book.png'>\n"
1789and another consisting of "<hr>\n"), but I<should> be stored as
1790a single data paragraph (consisting of
1791"<img src='wirth_spokesmodeling_book.png'>\n\n<hr>\n").
1792
1793Pod processors should tolerate empty
1794"=begin I<something>"..."=end I<something>" regions,
1795empty "=begin :I<something>"..."=end :I<something>" regions, and
1796contentless "=for I<something>" and "=for :I<something>"
1797paragraphs. I.e., these should be tolerated:
1798
1799 =for html
210b36aa 1800
8a93676d 1801 =begin html
210b36aa 1802
8a93676d 1803 =end html
210b36aa 1804
8a93676d 1805 =begin :biblio
210b36aa 1806
8a93676d 1807 =end :biblio
1808
1809Incidentally, note that there's no easy way to express a data
1810paragraph starting with something that looks like a command. Consider:
1811
1812 =begin stuff
210b36aa 1813
8a93676d 1814 =shazbot
210b36aa 1815
8a93676d 1816 =end stuff
1817
1818There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data
1819paragraph "=shazbot\n". However, you can express a data paragraph consisting
1820of "=shazbot\n" using this code:
1821
1822 =for stuff =shazbot
1823
1824The situation where this is necessary, is presumably quite rare.
1825
1826Note that =end commands must match the currently open =begin command. That
1827is, they must properly nest. For example, this is valid:
1828
1829 =begin outer
210b36aa 1830
8a93676d 1831 X
210b36aa 1832
8a93676d 1833 =begin inner
210b36aa 1834
8a93676d 1835 Y
210b36aa 1836
8a93676d 1837 =end inner
210b36aa 1838
8a93676d 1839 Z
210b36aa 1840
8a93676d 1841 =end outer
1842
1843while this is invalid:
1844
1845 =begin outer
210b36aa 1846
8a93676d 1847 X
210b36aa 1848
8a93676d 1849 =begin inner
210b36aa 1850
8a93676d 1851 Y
210b36aa 1852
8a93676d 1853 =end outer
210b36aa 1854
8a93676d 1855 Z
210b36aa 1856
8a93676d 1857 =end inner
210b36aa 1858
8a93676d 1859This latter is improper because when the "=end outer" command is seen, the
1860currently open region has the formatname "inner", not "outer". (It just
1861happens that "outer" is the format name of a higher-up region.) This is
1862an error. Processors must by default report this as an error, and may halt
210b36aa 1863processing the document containing that error. A corollary of this is that
8a93676d 1864regions cannot "overlap" -- i.e., the latter block above does not represent
1865a region called "outer" which contains X and Y, overlapping a region called
1866"inner" which contains Y and Z. But because it is invalid (as all
1867apparently overlapping regions would be), it doesn't represent that, or
1868anything at all.
1869
1870Similarly, this is invalid:
1871
1872 =begin thing
210b36aa 1873
8a93676d 1874 =end hting
1875
1876This is an error because the region is opened by "thing", and the "=end"
1877tries to close "hting" [sic].
1878
1879This is also invalid:
1880
1881 =begin thing
210b36aa 1882
8a93676d 1883 =end
1884
1885This is invalid because every "=end" command must have a formatname
1886parameter.
1887
1888=head1 SEE ALSO
1889
1890L<perlpod>, L<perlsyn/"PODs: Embedded Documentation">,
1891L<podchecker>
1892
1893=head1 AUTHOR
1894
1895Sean M. Burke
1896
1897=cut
1898
1899