On Fri, Mar 03, 2000 at 05:04:33PM -0500, Gregor N. Purdy wrote: > My understanding came from working with POD::Parser and discussing with > Brad Appleton the ways in which it didn't do what I expected. Correct. Pod::Parser's job is not to do any text-munging (in fact it must not do that because the thing invoking it must be able to exactly reproduce the PODs that were input to it without having to guess where to add newlines whether or not I'm at the beginning or end of a file). Pod::Parser's job is to parse things into paragraphs, not to munge them. Paragraphs are things that are separated by blank lines. They might be preceded by a blank line or they might end with a blank line. They have to have at least one of those two conditions, and unless they are the first/last thing in a file they have to have both. But if they are the first/last thing they only have to have one of them. > So, e.g., I have a level one section named "hello\n\n", > not "hello". Incorrect. Pod::Parser knows nothing of "level 1 sections" or levelled sections of any kind. It knows it saw a paragraph of "=head1 hello\n\n" that happens to be some kind of pod command/paragraph. Whether or not that paragraph is interpreted as level 1 section or anything else is entirely up to the caller. If your module chooses to interpret it as the name of a level one section whose name-text is "hello" than it is the responsibility of your module to know what cames ofter "=head1" is some kind of name and to extract the name portion from the paragraph. It is not the responsibility of Pod::Parser. It gave you the correct token including its terminating character (unless it was the last paragraph in the file, in which case there will be no extra "\n"). Pod::Parser knows POD syntax, it does not know POD semantics - it doesn't know and doesn't care. It Tokenizes the input for you, as something might do for a program (without removing the semi-colons). Early on I had actually suggested the name Pod::Lexer be used instead but Pod::Parser seemed to be the preferred name. Please don't expect Pod::Parser to *know* POD, only to *parse* it. It's the caller that has to know what to do with the result. -- Brad Appleton <[EMAIL PROTECTED]> http://www.enteract.com/~bradapp/ "And miles to go before I sleep." -- Robert Frost
