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. > 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. -- Russ Allbery (r...@stanford.edu) <http://www.eyrie.org/~eagle/>
