"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."
+1 -Marek Von: Marc Green [mailto:[email protected]] Gesendet: Sonntag, 19. Februar 2012 06:33 An: [email protected] Betreff: On verbatim paragraphs immediately following an =item command; and Pod::Simple 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
