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