On 02/18/2012 11:26 PM, Russ Allbery wrote:
Marc Green<pongu...@gmail.com> writes:
A simple (yet lengthy) question on verbatim paragraphs that immediately
follow an =item command, and how Pod::Simple treats them:
Given the following POD,
=over
=item *
verbatim code snippet
=back
Should the =item be considered empty, followed by a verbatim paragraph,
or should the =item's contents include the verbatim paragraph?
Semantically, I think the =item's contents should include the verbatim
paragraph. Otherwise, there's no way to have verbatim information inside
an item, such as an example of usage of a method that's documented via
=over/=item/=back.
+1
What brought this technicality to my attention is that Pod::Simple
interprets it as the former (emphasis added):
$ perl -MPod::Simple::DumpAsText -E'exit
Pod::Simple::DumpAsText->filter(shift)->any_errata_seen' test_verb.pod
++Document
\ "start_line" => "1"
++over-bullet
\ "indent" => "4"
\ "start_line" => "1"
* ++item-bullet
\ "start_line" => "3"
--item-bullet
++VerbatimFormatted
\ "xml:space" => "preserve"
\ "start_line" => "5"
* " verbatim code snippet"
--VerbatimFormatted*
--over-bullet
--Document
It looks like I work around this in Pod::Man and Pod::Text by accident,
and in a way that might actually break if this were fixed. Hrm. I can't
tell for sure. I *think* it would be okay anyway, but I'm not positive.
I'm not sure how the method calls would change if this behavior were
changed.
Basically, at present, I'm assuming that all the paragraphs are inside the
item until I see another item, whether they're passed in as the text of
the item or not.
