On 23 Aug 01, at 18:02, Sean M. Burke wrote:
> 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.
Ah, sorry. I had misunderstood your sentence "I'm merely mandating that
pod parsers agree with perl on this" to mean "Perl does it this way,
now we have to make all pod parsers do it that way, too".
> 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.
This I agree with. Thanks for restating your idea.
> 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.
Well, so they don't agree with perlpodspec. So make them fix it if they
want it to run under current perls. (You call it a "mistake" yourself.)
> 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.
I disagree with the "nothing breaks" because it means, for example,
that a line in a filled paragraph that happens to start with "=cut"
will cause POD parsers to stop parsing. I think that's bad, and the
workaround "Z<>=cut" is ugly (and the fact that a workaround is needed
is IMO a bug -- like the fact that some people feel compelled to write
L<Foo::Bar|Foo::Bar> rather than simply L<Foo::Bar>).
Easiest just to mandate blank lines before and after.
> 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.
Hm, maybe. (And =over and other things that might be misinterpreted.)
> It's certainly going to be rarer than cases where people forget
> whitespace around pod blocks.
Cheers,
Philip
--
Philip Newton <[EMAIL PROTECTED]>
