Hello Pod People,
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?
I think the general understanding is that the content of an =item extends
until the next =item command. (I found nothing in perlpodspec stating this,
but I have always known it to be this way.) This supports the latter
interpretation.
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 can be seen that the item-bullet was empty, followed by a verbatim
paragraph. Contrast that with a *non-verbatim* paragraph immediately
following an =item command (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"
> * "a non-verbatim paragraph"
> --item-bullet*
> --over-bullet
> --Document
>
Note that the "a non-verbatim paragraph" text is present within the
item-bullet, unlike the previous example.
The Pod::Simple::Subclassing documentation states:
> When an "=over ... =back" block is parsed where the items are a bulleted
> list, it will produce this event structure:
>
> <over-bullet indent="4" start_line="543">
> <item-bullet start_line="545">
> ...Stuff...
> </item-bullet>
> ...more item-bullets...
> </over-bullet fake-closer="1">
>
> Note that it states there should only be item-bullet events, and nothing
else in between, before, or after.
This is a contradiction, and I am not sure which should be correct: the
code or the docs.
Experimenting more, it looks like Pod::Simple only considers the *first*
normal paragraph as the item's contents, with following paragraphs
remaining outside the item-bullet event (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"
> * "first paragraph"
> --item-bullet
> ++Para
> \ "start_line" => "7"
> * "second paragraph"
> --Para*
> --over-bullet
> --Document
>
Thoughts on this behavior? I feel that the content's of an =item should be
contained within that =item's item-bullet event, instead of partially in,
partially out.
Thank you,
Marc
