X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/d1be9408a3c14848d30728674452e191ba5fffaa..41c407bcf550c4e19a5b20e9ac26ad65a405d4e2:/pod/perlpodspec.pod diff --git a/pod/perlpodspec.pod b/pod/perlpodspec.pod index 46d3ec8..67f74b6 100644 --- a/pod/perlpodspec.pod +++ b/pod/perlpodspec.pod @@ -1,3 +1,4 @@ +=encoding utf8 =head1 NAME @@ -30,7 +31,7 @@ it implicates that such an option I be provided. =head1 Pod Definitions -Pod is embedded in files, typically Perl source files -- although you +Pod is embedded in files, typically Perl source files, although you can write a file that's nothing but Pod. A B in a file consists of zero or more non-newline characters, @@ -49,7 +50,7 @@ A B is a line containing one or more characters other than space or tab (and terminated by a newline or end-of-file). (I Many older Pod parsers did not accept a line consisting of -spaces/tabs and then a newline as a blank line -- the only lines they +spaces/tabs and then a newline as a blank line. The only lines they considered blank were lines consisting of I, terminated by a newline.) @@ -65,12 +66,12 @@ directly formatting it). A B (or B) is a module or program that converts Pod to some other format (HTML, plaintext, TeX, PostScript, RTF). A B might be a formatter or translator, or might be a program that does something -else with the Pod (like wordcounting it, scanning for index points, +else with the Pod (like counting words, scanning for index points, etc.). Pod content is contained in B. A Pod block starts with a line that matches , and continues up to the next line -that matches C -- or up to the end of the file, if there is +that matches C or up to the end of the file if there is no C line. =for comment @@ -121,7 +122,7 @@ But they may span several (non-blank) lines: =for comment Hm, I wonder what it would look like if you tried to write a BNF for Pod from this. - + =head3 Dr. Strangelove, or: How I Learned to Stop Worrying and Love the Bomb @@ -132,7 +133,7 @@ I command paragraphs allow formatting codes in their content In other words, the Pod processing handler for "head1" will apply the same processing to "Did You Remember to CEuse strict;>?" that it -would to an ordinary paragraph -- i.e., formatting codes (like +would to an ordinary paragraph (i.e., formatting codes like "CE...>") are parsed and presumably formatted appropriately, and whitespace in the form of literal spaces and/or tabs is not significant. @@ -176,11 +177,11 @@ For example: consider the following paragraphs: # <- that's the 0th column =head1 Foo - + Stuff - + $foo->bar - + =cut Here, "=head1 Foo" and "=cut" are command paragraphs because the first @@ -189,7 +190,7 @@ is a verbatim paragraph, because its first line starts with a literal whitespace character (and there's no "=begin"..."=end" region around). The "=begin I" ... "=end I" commands stop -paragraphs that they surround from being parsed as data or verbatim +paragraphs that they surround from being parsed as ordinary or verbatim paragraphs, if I doesn't begin with a colon. This is discussed in detail in the section L=end" Regions>. @@ -208,7 +209,7 @@ This command indicates that the text in the remainder of the paragraph is a heading. That text may contain formatting codes. Examples: =head1 Object Attributes - + =head3 What B to Do! =item "=pod" @@ -219,9 +220,9 @@ all.) If there is any text in this command paragraph after "=pod", it must be ignored. Examples: =pod - + This is a plain Pod paragraph. - + =pod This text is ignored. =item "=cut" @@ -238,7 +239,7 @@ ignored. Examples: # This is the first line of program text. sub foo { # This is the second. -It is an error to try to I a Pod black with a "=cut" command. In +It is an error to try to I a Pod block with a "=cut" command. In that case, the Pod processor must halt parsing of the input file, and must by default emit a warning. @@ -251,9 +252,9 @@ explained in the L section, further below. Formatting codes are not expanded. Examples: =over 3 - + =over 3.5 - + =over =item "=item" @@ -265,20 +266,20 @@ explained in the L section, further below. Examples: =item - + =item * - + =item * - + =item 14 - + =item 3. - + =item C<< $thing->stuff(I) >> - + =item For transporting us beyond seas to be tried for pretended offenses - + =item He is at this time transporting large armies of foreign mercenaries to complete the works of death, desolation and tyranny, already begun with circumstances of cruelty and perfidy @@ -293,6 +294,8 @@ by the most recent "=over" command. It permits no text after the =item "=begin formatname" +=item "=begin formatname parameter" + This marks the following paragraphs (until the matching "=end formatname") as being for some special kind of processing. Unless "formatname" begins with a colon, the contained non-command @@ -302,9 +305,11 @@ or data paragraphs. This is discussed in detail in the section L=end" Regions>. It is advised that formatnames match the regexp -C. Implementors should anticipate future -expansion in the semantics and syntax of the first parameter -to "=begin"/"=end"/"=for". +C. Everything following whitespace after the +formatname is a parameter that may be used by the formatter when dealing +with this region. This parameter must not be repeated in the "=end" +paragraph. Implementors should anticipate future expansion in the +semantics and syntax of the first parameter to "=begin"/"=end"/"=for". =item "=end formatname" @@ -320,9 +325,9 @@ L=end" Regions>. This is synonymous with: =begin formatname - + text... - + =end formatname That is, it creates a region consisting of a single paragraph; that @@ -332,6 +337,29 @@ then "text..." will constitute a data paragraph. There is no way to use "=for formatname text..." to express "text..." as a verbatim paragraph. +=item "=encoding encodingname" + +This command, which should occur early in the document (at least +before any non-US-ASCII data!), declares that this document is +encoded in the encoding I, which must be +an encoding name that L recognizes. (Encode's list +of supported encodings, in L, is useful here.) +If the Pod parser cannot decode the declared encoding, it +should emit a warning and may abort parsing the document +altogether. + +A document having more than one "=encoding" line should be +considered an error. Pod processors may silently tolerate this if +the not-first "=encoding" lines are just duplicates of the +first one (e.g., if there's a "=encoding utf8" line, and later on +another "=encoding utf8" line). But Pod processors should complain if +there are contradictory "=encoding" lines in the same document +(e.g., if there is a "=encoding utf8" early in the document and +"=encoding big5" later). Pod processors that recognize BOMs +may also complain if they see an "=encoding" line +that contradicts the BOM (e.g., if a document with a UTF-16LE +BOM has an "=encoding shiftjis" line). + =back If a Pod processor sees any command other than the ones listed @@ -388,7 +416,7 @@ formatting code. Examples: B<< $foo->bar(); >> With this syntax, the whitespace character(s) after the "CE<<" -and before the ">>" (or whatever letter) are I renderable -- they +and before the ">>" (or whatever letter) are I renderable. They do not signify whitespace, are merely part of the formatting codes themselves. That is, these are all synonymous: @@ -402,6 +430,18 @@ themselves. That is, these are all synonymous: and so on. +Finally, the multiple-angle-bracket form does I alter the interpretation +of nested formatting codes, meaning that the following four example lines are +identical in meaning: + + B=E $b>> + + B $b >>> + + B=E $b >>> + + B<<< example: C<< $a E=E $b >> >>> + =back In parsing Pod, a notably tricky part is the correct parsing of @@ -463,7 +503,7 @@ L. This formatting code is syntactically simple, but semantically complex. What it means is that each space in the printable -content of this code signifies a nonbreaking space. +content of this code signifies a non-breaking space. Consider: @@ -474,7 +514,7 @@ Consider: Both signify the monospace (c[ode] style) text consisting of "$x", one space, "?", one space, ":", one space, "$z". The difference is that in the latter, with the S code, those spaces -are not "normal" spaces, but instead are nonbreaking spaces. +are not "normal" spaces, but instead are non-breaking spaces. =back @@ -499,7 +539,7 @@ a "-". This was so that this: would parse as equivalent to this: - C<$foo-Ebar> + C<$foo-Ebar> instead of as equivalent to a "C" formatting code containing only "$foo-", and then a "bar>" outside the "C" formatting code. This @@ -517,7 +557,7 @@ starting at line 123: 'Time objects are not...'"). So these two paragraphs: I ...must I be parsed as two paragraphs in italics (with the I @@ -526,7 +566,7 @@ the first paragraph should generate a warning, but that aside, the above code must parse as if it were: I - + Don't make me say it again!E (In SGMLish jargon, all Pod commands are like block-level @@ -589,7 +629,7 @@ UTF-16. If the file begins with the three literal byte values 0xEF 0xBB 0xBF =for comment - If toke.c is modified to support UTF32, add mention of those here. + If toke.c is modified to support UTF-32, add mention of those here. =item * @@ -611,11 +651,11 @@ is sufficient to establish this file's encoding. =for comment If/WHEN some brave soul makes these heuristics into a generic - text-file class (or file discipline?), we can presumably delete + text-file class (or PerlIO layer?), we can presumably delete mention of these icky details from this file, and can instead - tell people to just use appropriate class/discipline. + tell people to just use appropriate class/layer. Auto-recognition of newline sequences would be another desirable - feature of such a class/discipline. + feature of such a class/layer. HINT HINT HINT. =for comment @@ -644,13 +684,13 @@ text identifying its name and version number, and the name and version numbers of any modules it might be using to process the Pod. Minimal examples: - %% POD::Pod2PS v3.14159, using POD::Parser v1.92 - - - - {\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08} - - .\" Pod::Man version 3.14159, using POD::Parser version 1.92 + %% POD::Pod2PS v3.14159, using POD::Parser v1.92 + + + + {\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08} + + .\" Pod::Man version 3.14159, using POD::Parser version 1.92 Formatters may also insert additional comments, including: the release date of the Pod formatter program, the contact address for @@ -701,7 +741,7 @@ period-space-space or period-newline sequences). Pod parsers should not, by default, try to coerce apostrophe (') and quote (") into smart quotes (little 9's, 66's, 99's, etc), nor try to turn backtick (`) into anything else but a single backtick character -(distinct from an openquote character!), nor "--" into anything but +(distinct from an open quote character!), nor "--" into anything but two minus signs. They I do any of those things to text in CE...> formatting codes, and never I to text in verbatim paragraphs. @@ -709,10 +749,10 @@ paragraphs. =item * When rendering Pod to a format that has two kinds of hyphens (-), one -that's a nonbreaking hyphen, and another that's a breakable hyphen +that's a non-breaking hyphen, and another that's a breakable hyphen (as in "object-oriented", which can be split across lines as "object-", newline, "oriented"), formatters are encouraged to -generally translate "-" to nonbreaking hyphen, but may apply +generally translate "-" to non-breaking hyphen, but may apply heuristics to convert some of these to breaking hyphens. =item * @@ -802,7 +842,7 @@ characters (also defined there by Unicode, with the same meaning), which all Pod formatters must render faithfully. Characters in the ranges 0-31 and 127-159 should not be used (neither as literals, nor as EEnumber> codes), except for the -literal byte-sequences for newline (13, 13 10, or 13), and tab (9). +literal byte-sequences for newline (13, 13 10, or 10), and tab (9). Characters in the range 160-255 refer to Latin-1 characters (also defined there by Unicode, with the same meaning). Characters above @@ -861,7 +901,7 @@ it contains spaces, which aren't alphanumeric characters. This presumably does not I special treatment by a Pod processor; " 0 1 2 3 " doesn't look like a number in any base, so it would presumably be looked up in the table of HTML-like names. Since -there is (and cannot be) an HTML-like entity called " 0 1 2 3 ", +there isn't (and cannot be) an HTML-like entity called " 0 1 2 3 ", this will be treated as an error. However, Pod processors may treat "EE 0 1 2 3 >" or "EEe-acute>" as I invalid, potentially earning a different error message than the @@ -883,9 +923,9 @@ character) to the escape sequences or codes necessary for conveying such sequences in the target output format. A converter to *roff would, for example know that "\xE9" (whether conveyed literally, or via a EE...> sequence) is to be conveyed as "e\\*'". -Similarly, a program rendering Pod in a MacOS application window, would +Similarly, a program rendering Pod in a Mac OS application window, would presumably need to know that "\xE9" maps to codepoint 142 in MacRoman -encoding that (at time of writing) is native for MacOS. Such +encoding that (at time of writing) is native for Mac OS. Such Unicode2whatever mappings are presumably already widely available for common output formats. (Such mappings may be incomplete! Implementers are not expected to bend over backwards in an attempt to render @@ -936,13 +976,13 @@ for idiosyncratic mappings of Unicode-to-I. =item * -It is up to individual Pod formatter to display good judgment when +It is up to individual Pod formatter to display good judgement when confronted with an unrenderable character (which is distinct from an unknown EEthing> sequence that the parser couldn't resolve to anything, renderable or not). It is good practice to map Latin letters with diacritics (like "EEeacute>"/"EE233>") to the corresponding unaccented US-ASCII letters (like a simple character 101, "e"), but -clearly this is often not feasable, and an unrenderable character may +clearly this is often not feasible, and an unrenderable character may be represented as "?", or the like. In attempting a sane fallback (as from EE233> to "e"), Pod formatters may use the %Latin1Code_to_fallback table in L, or @@ -969,15 +1009,15 @@ EEeuro>1,000,000 Solution|Million::Euros>". =item * -Some Pod formatters output to formats that implement nonbreaking +Some Pod formatters output to formats that implement non-breaking spaces as an individual character (which I'll call "NBSP"), and -others output to formats that implement nonbreaking spaces just as +others output to formats that implement non-breaking spaces just as spaces wrapped in a "don't break this across lines" code. Note that at the level of Pod, both sorts of codes can occur: Pod can contain a NBSP character (whether as a literal, or as a "EE160>" or "EEnbsp>" code); and Pod can contain "SEfoo IEbarE baz>" codes, where "mere spaces" (character 32) in -such codes are taken to represent nonbreaking spaces. Pod +such codes are taken to represent non-breaking spaces. Pod parsers should consider supporting the optional parsing of "SEfoo IEbarE baz>" as if it were "fooIIEbarEIbaz", and, going the other way, the @@ -987,7 +1027,7 @@ representation that maps best to what the output format demands. =item * -Some processors may find it the C...E> code easiest to +Some processors may find that the C...E> code is easiest to implement by replacing each space in the parse tree under the content of the S, with an NBSP. But note: the replacement should apply I to spaces in I text, but I to spaces in I text. (This @@ -1018,7 +1058,7 @@ character/code and no code for "don't break this stuff across lines". Besides the NBSP character discussed above, implementors are reminded of the existence of the other "special" character in Latin-1, the -"soft hyphen" chararacter, also known as "discretionary hyphen", +"soft hyphen" character, also known as "discretionary hyphen", i.e. C173E> = C0xADE> = CshyE>). This character expresses an optional hyphenation point. That is, it normally renders as nothing, but may render as a @@ -1094,20 +1134,20 @@ link text. Note that link text may contain formatting.) =item Second: -The possibly inferred link-text -- i.e., if there was no real link +The possibly inferred link-text; i.e., if there was no real link text, then this is the text that we'll infer in its place. (E.g., for "LEGetopt::Std>", the inferred link text is "Getopt::Std".) =item Third: The name or URL, or undef if none. (E.g., in "LEPerl -Functions|perlfunc>", the name -- also sometimes called the page -- +Functions|perlfunc>", the name (also sometimes called the page) is "perlfunc". In "LE/CAVEATS>", the name is undef.) =item Fourth: The section (AKA "item" in older perlpods), or undef if none. E.g., -in L, "DESCRIPTION" is the section. (Note +in "LEGetopt::Std/DESCRIPTIONE", "DESCRIPTION" is the section. (Note that this is not the same as a manpage section like the "5" in "man 5 crontab". "Section Foo" in the Pod sense means the part of the text that's introduced by the heading or item whose text is "Foo".) @@ -1138,52 +1178,61 @@ a requirement that these be passed as an actual list or array.) For example: L - => undef, # link text - "Foo::Bar", # possibly inferred link text - "Foo::Bar", # name - undef, # section - 'pod', # what sort of link - "Foo::Bar" # original content + => undef, # link text + "Foo::Bar", # possibly inferred link text + "Foo::Bar", # name + undef, # section + 'pod', # what sort of link + "Foo::Bar" # original content L - => "Perlport's section on NL's", # link text - "Perlport's section on NL's", # possibly inferred link text - "perlport", # name - "Newlines", # section - 'pod', # what sort of link - "Perlport's section on NL's|perlport/Newlines" # orig. content + => "Perlport's section on NL's", # link text + "Perlport's section on NL's", # possibly inferred link text + "perlport", # name + "Newlines", # section + 'pod', # what sort of link + "Perlport's section on NL's|perlport/Newlines" + # original content L - => undef, # link text - '"Newlines" in perlport', # possibly inferred link text - "perlport", # name - "Newlines", # section - 'pod', # what sort of link - "perlport/Newlines" # original content + => undef, # link text + '"Newlines" in perlport', # possibly inferred link text + "perlport", # name + "Newlines", # section + 'pod', # what sort of link + "perlport/Newlines" # original content L - => undef, # link text - '"DESCRIPTION" in crontab(5)', # possibly inferred link text - "crontab(5)", # name - "DESCRIPTION", # section - 'man', # what sort of link - 'crontab(5)/"DESCRIPTION"' # original content + => undef, # link text + '"DESCRIPTION" in crontab(5)', # possibly inferred link text + "crontab(5)", # name + "DESCRIPTION", # section + 'man', # what sort of link + 'crontab(5)/"DESCRIPTION"' # original content L - => undef, # link text - '"Object Attributes"', # possibly inferred link text - undef, # name - "Object Attributes", # section - 'pod', # what sort of link - "/Object Attributes" # original content + => undef, # link text + '"Object Attributes"', # possibly inferred link text + undef, # name + "Object Attributes", # section + 'pod', # what sort of link + "/Object Attributes" # original content L - => undef, # link text - "http://www.perl.org/", # possibly inferred link text - "http://www.perl.org/", # name - undef, # section - 'url', # what sort of link - "http://www.perl.org/" # original content + => undef, # link text + "http://www.perl.org/", # possibly inferred link text + "http://www.perl.org/", # name + undef, # section + 'url', # what sort of link + "http://www.perl.org/" # original content + + L + => "Perl.org", # link text + "http://www.perl.org/", # possibly inferred link text + "http://www.perl.org/", # name + undef, # section + 'url', # what sort of link + "Perl.org|http://www.perl.org/" # original content Note that you can distinguish URL-links from anything else by the fact that they match C. So @@ -1225,9 +1274,9 @@ as in:

About the -M Operator

- + ... - + About the -M Operator" in somedoc @@ -1253,23 +1302,14 @@ browsers to decide. =item * -Authors wanting to link to a particular (absolute) URL, must do so -only with "LEscheme:...>" codes (like -LEhttp://www.perl.org>), and must not attempt "LESome Site -Name|scheme:...>" codes. This restriction avoids many problems -in parsing and rendering LE...> codes. - -=item * - In a Ctext|...E> code, text may contain formatting codes for formatting or for EE...> escapes, as in: Lstuff>|...> For C...E> codes without a "name|" part, only -C...E> and CE> codes may occur -- no -other formatting codes. That is, authors should not use -"CBEFoo::BarEE>". +C...E> and CE> codes may occur. That is, +authors should not use "CBEFoo::BarEE>". Note, however, that formatting codes and ZE>'s can occur in any and all parts of an LE...> (i.e., in I, I
, I, @@ -1296,28 +1336,29 @@ that case, formatters will have to just ignore that formatting. At time of writing, CnameE> values are of two types: either the name of a Pod page like CFoo::BarE> (which might be a real Perl module or program in an @INC / PATH -directory, or a .pod file in those places); or the name of a UNIX +directory, or a .pod file in those places); or the name of a Unix man page, like Ccrontab(5)E>. In theory, CchmodE> in ambiguous between a Pod page called "chmod", or the Unix man page "chmod" (in whatever man-section). However, the presence of a string in parens, as in "crontab(5)", is sufficient to signal that what is being discussed is not a Pod page, and so is presumably a -UNIX man page. The distinction is of no importance to many +Unix man page. The distinction is of no importance to many Pod processors, but some processors that render to hypertext formats may need to distinguish them in order to know how to render a given CfooE> code. =item * -Previous versions of perlpod allowed for a CsectionE> syntax -(as in "CObject AttributesE>"), which was not easily distinguishable -from CnameE> syntax. This syntax is no longer in the -specification, and has been replaced by the C"section"E> syntax -(where the quotes were formerly optional). Pod parsers should tolerate -the CsectionE> syntax, for a while at least. The suggested -heuristic for distinguishing CsectionE> from CnameE> -is that if it contains any whitespace, it's a I
. Pod processors -may warn about this being deprecated syntax. +Previous versions of perlpod allowed for a CsectionE> syntax (as in +CObject AttributesE>), which was not easily distinguishable from +CnameE> syntax and for C"section"E> which was only +slightly less ambiguous. This syntax is no longer in the specification, and +has been replaced by the C/sectionE> syntax (where the slash was +formerly optional). Pod parsers should tolerate the C"section"E> +syntax, for a while at least. The suggested heuristic for distinguishing +CsectionE> from CnameE> is that if it contains any +whitespace, it's a I
. Pod processors should warn about this being +deprecated syntax. =back @@ -1434,17 +1475,17 @@ Pod processors should tolerate "=item *" / "=item I" commands with no accompanying paragraph. The middle item is an example: =over - + =item 1 - + Pick up dry cleaning. - + =item 2 - + =item 3 - + Stop by the store. Get Abba Zabas, Stoli, and cheap lawn chairs. - + =back =item * @@ -1458,7 +1499,7 @@ Note that an "=over" ... "=back" region should have some content. That is, authors should not have an empty region like this: =over - + =back Pod processors seeing such a contentless "=over" ... "=back" region, @@ -1479,7 +1520,7 @@ Authors of Pod formatters should note that this construct: =item Porro =item Quisquam Est - + Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. @@ -1494,9 +1535,9 @@ paragraph "Qui dolorem ipsum quia dolor..."; and then an item "Ut Enim". In that case, you'd want to format it like so: Neque - + Porro - + Quisquam Est Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut @@ -1518,7 +1559,7 @@ probably want to format it like so: Ut Enim -But (for the forseeable future), Pod does not provide any way for Pod +But (for the foreseeable future), Pod does not provide any way for Pod authors to distinguish which grouping is meant by the above "=item"-cluster structure. So formatters should format it like so: @@ -1534,7 +1575,7 @@ authors to distinguish which grouping is meant by the above Ut Enim -That is, there should be (at least roughtly) equal spacing between +That is, there should be (at least roughly) equal spacing between items as between paragraphs (although that spacing may well be less than the full height of a line of text). This leaves it to the reader to use (con)textual cues to figure out whether the "Qui dolorem @@ -1554,9 +1595,9 @@ to be used (typically passed through) when rendering the document to a specific format: =begin rtf - + \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par} - + =end rtf The exact same effect could, incidentally, be achieved with a single @@ -1570,11 +1611,11 @@ meaning as one, and Pod parsers may parse it as one.) Another example of a data paragraph: =begin html - + I like PIE! - +
Especially pecan pie! - + =end html If these were ordinary paragraphs, the Pod parser would try to @@ -1620,26 +1661,26 @@ Note that a "=begin I"..."=end I" region where I begins with a colon, I contain commands. For example: =begin :biblio - + Wirth's classic is available in several editions, including: - + =for comment hm, check abebooks.com for how much used copies cost. - + =over - + =item - + Wirth, Niklaus. 1975. I Teubner, Stuttgart. [Yes, it's in German.] - + =item - + Wirth, Niklaus. 1976. I Prentice-Hall, Englewood Cliffs, NJ. - + =back - + =end :biblio Note, however, a "=begin I"..."=end I" @@ -1648,13 +1689,13 @@ directly contain "=head1" ... "=head4" commands, nor "=over", nor "=back", nor "=item". For example, this may be considered invalid: =begin somedata - + This is a data paragraph. - + =head1 Don't do this! - + This is a data paragraph too. - + =end somedata A Pod processor may signal that the above (specifically the "=head1" @@ -1662,48 +1703,48 @@ paragraph) is an error. Note, however, that the following should I be treated as an error: =begin somedata - + This is a data paragraph. - + =cut - + # Yup, this isn't Pod anymore. sub excl { (rand() > .5) ? "hoo!" : "hah!" } - + =pod - + This is a data paragraph too. - + =end somedata And this too is valid: =begin someformat - + This is a data paragraph. - + And this is a data paragraph. - + =begin someotherformat - + This is a data paragraph too. - + And this is a data paragraph too. - + =begin :yetanotherformat =head2 This is a command paragraph! This is an ordinary paragraph! - + And this is a verbatim paragraph! - + =end :yetanotherformat - + =end someotherformat - + Another data paragraph! - + =end someformat The contents of the above "=begin :yetanotherformat" ... @@ -1720,35 +1761,35 @@ other than "=end", "=pod", and "=cut". Also consider this valid structure: =begin :biblio - + Wirth's classic is available in several editions, including: - + =over - + =item - + Wirth, Niklaus. 1975. I Teubner, Stuttgart. [Yes, it's in German.] - + =item - + Wirth, Niklaus. 1976. I Prentice-Hall, Englewood Cliffs, NJ. =back - + Buy buy buy! - + =begin html - + - +
- + =end html - + Now now now! - + =end :biblio There, the "=begin html"..."=end html" region is nested inside @@ -1774,22 +1815,22 @@ contentless "=for I" and "=for :I" paragraphs. I.e., these should be tolerated: =for html - + =begin html - + =end html - + =begin :biblio - + =end :biblio Incidentally, note that there's no easy way to express a data paragraph starting with something that looks like a command. Consider: =begin stuff - + =shazbot - + =end stuff There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data @@ -1804,41 +1845,41 @@ Note that =end commands must match the currently open =begin command. That is, they must properly nest. For example, this is valid: =begin outer - + X - + =begin inner - + Y - + =end inner - + Z - + =end outer while this is invalid: =begin outer - + X - + =begin inner - + Y - + =end outer - + Z - + =end inner - + This latter is improper because when the "=end outer" command is seen, the currently open region has the formatname "inner", not "outer". (It just happens that "outer" is the format name of a higher-up region.) This is an error. Processors must by default report this as an error, and may halt -processing the document containing that error. A corrolary of this is that -regions cannot "overlap" -- i.e., the latter block above does not represent +processing the document containing that error. A corollary of this is that +regions cannot "overlap". That is, the latter block above does not represent a region called "outer" which contains X and Y, overlapping a region called "inner" which contains Y and Z. But because it is invalid (as all apparently overlapping regions would be), it doesn't represent that, or @@ -1847,7 +1888,7 @@ anything at all. Similarly, this is invalid: =begin thing - + =end hting This is an error because the region is opened by "thing", and the "=end" @@ -1856,7 +1897,7 @@ tries to close "hting" [sic]. This is also invalid: =begin thing - + =end This is invalid because every "=end" command must have a formatname