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

On 02/18/2012 11:26 PM, Russ Allbery wrote:
> Marc Green<[email protected]>  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.
>