|
"=over"..."=back" regions are used for various kinds of list-like
structures. (I use the term "region" here simply as a collective term for everything
from the "=over" to the matching "=back".)
- The non-zero numeric indentlevel in "=over indentlevel" ...
"=back" is used for giving the formatter a clue as to how many "spaces"
(ems, or roughly equivalent units) it should tab over, although many formatters will have to
convert this to an absolute measurement that may not exactly match with the size of spaces
(or M's) in the document's base font. Other formatters may have to completely ignore the
number. The lack of any explicit indentlevel parameter is equivalent to an indentlevel
value of 4. Pod processors may complain if indentlevel is present but is not a
positive number matching
m/\A(\d*\.)?\d+\z/.
- Authors of Pod formatters are reminded that "=over" ... "=back" may
map to several different constructs in your output format. For example, in converting Pod to
(X)HTML, it can map to any of <ul>...</ul>, <ol>...</ol>,
<dl>...</dl>, or <blockquote>...</blockquote>. Similarly,
"=item" can map to <li> or <dt>.
-
Each "=over" ... "=back" region should be one of the following:
-
An "=over" ... "=back" region containing only "=item *"
commands, each followed by some number of ordinary/verbatim paragraphs, other nested
"=over" ... "=back" regions, "=for..." paragraphs, and
"=begin"..."=end" regions.
(Pod processors must tolerate a bare "=item" as if it were "=item
*".) Whether "*" is rendered as a literal asterisk, an "o", or
as some kind of real bullet character, is left up to the Pod formatter, and may depend
on the level of nesting.
-
An "=over" ... "=back" region containing only m/\A=item\s+\d+\.?\s*\z/
paragraphs, each one (or each group of them) followed by some number of
ordinary/verbatim paragraphs, other nested "=over" ... "=back"
regions, "=for..." paragraphs, and/or "=begin"..."=end"
codes. Note that the numbers must start at 1 in each section, and must proceed in order
and without skipping numbers.
(Pod processors must tolerate lines like "=item 1" as if they were
"=item 1.", with the period.)
-
An "=over" ... "=back" region containing only "=item
[text]" commands, each one (or each group of them) followed by some number of
ordinary/verbatim paragraphs, other nested "=over" ... "=back"
regions, or "=for..." paragraphs, and "=begin"..."=end"
regions.
The "=item [text]" paragraph should not match m/\A=item\s+\d+\.?\s*\z/
or m/\A=item\s+\*\s*\z/, nor should it match just m/\A=item\s*\z/.
- An "=over" ... "=back" region containing no "=item"
paragraphs at all, and containing only some number of ordinary/verbatim paragraphs, and
possibly also some nested "=over" ... "=back" regions,
"=for..." paragraphs, and "=begin"..."=end" regions. Such
an itemless "=over" ... "=back" region in Pod is equivalent in
meaning to a "<blockquote>...</blockquote>" element in HTML.
Note that with all the above cases, you can determine which type of "=over" ...
"=back" you have, by examining the first (non-"=cut",
non-"=pod") Pod paragraph after the "=over" command.
-
Pod formatters must tolerate arbitrarily large amounts of text in the "=item text..."
paragraph. In practice, most such paragraphs are short, as in:
=item For cutting off our trade with all parts of the world
|
|
But they may be arbitrarily long:
=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
scarcely paralleled in the most barbarous ages, and totally
unworthy the head of a civilized nation.
|
|
-
Pod processors should tolerate "=item *" / "=item number"
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
|
|
- No "=over" ... "=back" region can contain headings. Processors may
treat such a heading as an error.
-
Note that an "=over" ... "=back" region should have some content.
That is, authors should not have an empty region like this:
Pod processors seeing such a contentless "=over" ... "=back" region,
may ignore it, or may report it as an error.
- Processors must tolerate an "=over" list that goes off the end of the document
(i.e., which has no matching "=back"), but they may warn about such a list.
-
Authors of Pod formatters should note that this construct:
=item Neque
=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.
=item Ut Enim
|
|
is semantically ambiguous, in a way that makes formatting decisions a bit difficult. On
the one hand, it could be mention of an item "Neque", mention of another item
"Porro", and mention of another item "Quisquam Est", with just the last
one requiring the explanatory 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
labore et dolore magnam aliquam quaerat voluptatem.
Ut Enim
|
|
But it could equally well be a discussion of three (related or equivalent) items, "Neque",
"Porro", and "Quisquam Est", followed by a paragraph explaining them
all, and then a new item "Ut Enim". In that case, you'd probably 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
labore et dolore magnam aliquam quaerat voluptatem.
Ut Enim
|
|
But (for the forseeable 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:
Neque
Porro
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.
Ut Enim
|
|
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 ipsum..." paragraph applies to the "Quisquam Est" item or to all
three items "Neque", "Porro", and "Quisquam Est". While not an
ideal situation, this is preferable to providing formatting cues that may be actually
contrary to the author's intent.
|
|
