AW: On verbatim paragraphs immediately following an =item command; and Pod::Simple

"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