Re: On verbatim paragraphs immediately following an =item command; and Pod::Simple
On 02/18/2012 11:26 PM, Russ Allbery wrote: Marc Greenpongu...@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. +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.
Re: On verbatim paragraphs immediately following an =item command; and Pod::Simple
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/
