|
Data paragraphs are typically used for inlining non-Pod data that is 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 "=for"
paragraph:
=for rtf \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}
|
|
(Although that is not formally a data paragraph, it has the same meaning as one, and Pod
parsers may parse it as one.)
Another example of a data paragraph:
=begin html
I like <em>PIE</em>!
<hr>Especially pecan pie!
=end html
|
|
If these were ordinary paragraphs, the Pod parser would try to expand the "E</em>"
(in the first paragraph) as a formatting code, just like "E<lt>" or "E<eacute>".
But since this is in a "=begin identifier"..."=end identifier"
region and the identifier "html" doesn't begin have a ":" prefix, the
contents of this region are stored as data paragraphs, instead of being processed as ordinary
paragraphs (or if they began with a spaces and/or tabs, as verbatim paragraphs).
As a further example: At time of writing, no "biblio" identifier is supported, but
suppose some processor were written to recognize it as a way of (say) denoting a bibliographic
reference (necessarily containing formatting codes in ordinary paragraphs). The fact that "biblio"
paragraphs were meant for ordinary processing would be indicated by prefacing each "biblio"
identifier with a colon:
=begin :biblio
Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
Programs.> Prentice-Hall, Englewood Cliffs, NJ.
=end :biblio
|
|
This would signal to the parser that paragraphs in this begin...end region are subject to
normal handling as ordinary/verbatim paragraphs (while still tagged as meant only for processors
that understand the "biblio" identifier). The same effect could be had with:
=for :biblio
Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
Programs.> Prentice-Hall, Englewood Cliffs, NJ.
|
|
The ":" on these identifiers means simply "process this stuff normally, even
though the result will be for some special target". I suggest that parser APIs report
"biblio" as the target identifier, but also report that it had a ":" prefix.
(And similarly, with the above "html", report "html" as the target
identifier, and note the lack of a ":" prefix.)
Note that a "=begin identifier"..."=end identifier" region
where identifier begins with a colon, can 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<Algorithmen und Datenstrukturen.>
Teubner, Stuttgart. [Yes, it's in German.]
=item
Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
Programs.> Prentice-Hall, Englewood Cliffs, NJ.
=back
=end :biblio
|
|
Note, however, a "=begin identifier"..."=end identifier"
region where identifier does not begin with a colon, should not 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" paragraph) is
an error. Note, however, that the following should not 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" ... "=end :yetanotherformat"
region aren't data paragraphs, because the immediately containing region's identifier
(":yetanotherformat") begins with a colon. In practice, most regions that contain data
paragraphs will contain only data paragraphs; however, the above nesting is syntactically
valid as Pod, even if it is rare. However, the handlers for some formats, like "html",
will accept only data paragraphs, not nested regions; and they may complain if they see
(targeted for them) nested regions, or commands, 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<Algorithmen und Datenstrukturen.>
Teubner, Stuttgart. [Yes, it's in German.]
=item
Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
Programs.> Prentice-Hall, Englewood Cliffs, NJ.
=back
Buy buy buy!
=begin html
<img src='wirth_spokesmodeling_book.png'>
<hr>
=end html
Now now now!
=end :biblio
|
|
There, the "=begin html"..."=end html" region is nested inside the larger
"=begin :biblio"..."=end :biblio" region. Note that the content of the
"=begin html"..."=end html" region is data paragraph(s), because the
immediately containing region's identifier ("html") doesn't begin with a colon.
Pod parsers, when processing a series of data paragraphs one after another (within a single
region), should consider them to be one large data paragraph that happens to contain blank
lines. So the content of the above "=begin html"..."=end html" may be
stored as two data paragraphs (one consisting of "<img src='wirth_spokesmodeling_book.png'>\n"
and another consisting of "<hr>\n"), but should be stored as a single
data paragraph (consisting of "<img src='wirth_spokesmodeling_book.png'>\n\n<hr>\n").
Pod processors should tolerate empty "=begin something"..."=end something"
regions, empty "=begin :something"..."=end :something"
regions, and contentless "=for something" and "=for :something"
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 paragraph "=shazbot\n". However, you can express a data paragraph consisting of
"=shazbot\n" using this code:
The situation where this is necessary, is presumably quite rare.
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 corollary of this is that regions cannot "overlap" -- i.e.,
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 anything
at all.
Similarly, this is invalid:
This is an error because the region is opened by "thing", and the "=end"
tries to close "hting" [sic].
This is also invalid:
This is invalid because every "=end" command must have a formatname parameter.
|
|
