At 04:48 AM 2001-08-23 +0200, Philip Newton wrote:
>: that's the way perl works currently (if I understand toke.c): a line
>: matching m/^\w/ means go into pod mode, and subsequent m/^=cut/ line
>: means go out of pod mode. I'm merely mandating that pod parsers agree
>: with perl on this.
>
>And I'm still concerned about this, because it sort-of means that pod parsers
>have to understand Perl.
It means nothing of the sort. It just means that perl and POD parsers must
agree sanely on what a pod block is, because there is no benefit to their
current disagreement.
(Put another way: if I'm talking to Jarkko, and another Finn comes up, and
he and Jarkko converse briefly in Finnish, I can competently recognize that
this isn't English speech being directed at me. That doesn't mean I can
parse Finnish, even "sort of".)
I think it's okay if perl had a /narrower/ idea than POD parsers do of what
pod blocks are, but the current current behavior is the other way around
(perl having a broader view), and it's untenable. The current behavior
means you could (and sometimes do, erroneously) write a pod block not
bounded by whitespace, have it be dutifully skipped by perl, but also
silently ignored by a pod processor. It's easy to miss that case, where a
chunk of POD is just silently absent from the docs.
Now, we could change perl to conform to current POD parsers' behavior
(i.e., requiring blank lines before and after the pod block), but that
would mean that modules with currently "dormant" pod sections (i.e., with
pod blocks that have no leading/tailing whitespace, and I assume there's
many such modules out there, as I've made this mistake myself many times)
would start throwing errors when you try compiling them under a new 'fixed'
version of perl.
So if you go the other way and make POD parsers conform to perl's current
behavior, then those dormant sections just merrily start appearing in the
docs -- which is what people intended anyway! Nothing breaks, things start
fixing themselves, DWIM, and all that.
Now, it's not a question of which way is a good idea -- they're both good
ideas. It's a question of which has the most acceptable costs, and best
benifits.
One problem is, as you point out, a "=cut" in the middle of a paragraph
that gets wrapped to start a line, does end the section. But: I would be
surprised if this ever actually came up. The average but of documentation
doesn't go around /discussing/ "=cut" commands. It's certainly going to be
rarer than cases where people forget whitespace around pod blocks. And I
think it's going to be easier to catch: if the "=cut" drops you back into
perl, then perl will be complaining about weird English text trying to be
passed off as Perl cods. And even in cases (say, after an __END__) where
perl would never be looking at the text in question, people will be able to
more easily spot a paragraph/section that stops in the middle, than (in the
current situation) spotting when a whole section is missing. Because it's
easier to look at formatted output and see something that is THERE and
WRONG (truncated mid-sentence), than to realize a section is missing.
>I agree with you. I also think that a pod command that *ends* a pod section
>should be preceeded by a blank line, in perl and pod parsers.
Yes, it /should/, and I recall saying as much in the docs. However, I
don't want to say that it /must/.
I think a new podchecker could/should warn about cases where pod blocks are
not bounded by whitespace. Podchecker (and not in normal parsers!) is
exactly where I want helpful warnings along the lines of "you COULD do it
that way, but you shouldn't!" and "are you sure you meant to do that?" --
assuming I'm entirely free to ignore its warnings in cases where they're
overzealous.
I'm tempted to make this even easier for parsers/checkers to catch by
saying that the "=pod" and "=cut" commands must take no parameters -- i.e.,
this line:
=cut is what you use to end a pod blocks, so that perl picks up.
...would make pod processors scream an error. HOWEVER, some people have
said that not only do they want nothing of the sort, but in fact they want
perlpodspec to clarify/specify that "=pod" and "=cut" paragraphs CAN take
parameters (of a sort), but that they MUST be ignored. This is so that
stuff like this can be guaranteed valid:
=pod Here's some docs!
Hooboy!
=cut Back to perl...
Apparently this isn't just some wild nonsense that people came up with on
their own, but something that was suggested (or at least alluded to?)
somewhere in the Perl docs. I can't find a good example, but I do see
"=secret stuff" and some lines and then "=cut back", in the part of perlsyn
that I suggested striking, in draft 1 of perlpodspec. That makes me think
that it's suggested/demonstrated elsewhere too, so I shouldn't go breaking
that.
--
Sean M. Burke [EMAIL PROTECTED] http://www.spinn.net/~sburke/
