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:pongu...@gmail.com] Gesendet: Sonntag, 19. Februar 2012 06:33 An: pod-people@perl.org 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
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/
