On Wed, Oct 17, 2001 at 03:02:40AM -0600, Sean M. Burke wrote:
> 1) a =cut can start a pod block, and it takes another one later to end it.
>
> 2) a =cut can start a pod block, but it simultaneously ends it.
>
> 3) It's an error to start a pod block with a =cut. Why? Because "=cut"
> means "end the pod block that's open".
> Any pod parser MUST consider it a horrible error to start a pod block with
> a =cut, and MUST scream like a banshee about it, and should abort the parse
> of the document.
A few years back, I noticed that the "then" version of Perl5
had what was later considered to be a bug (including by Larry
if memory serves), such that the following would be parsed by
perl as a valid pod-block and hence ignored:
=cut
sub some_function {
...
}
=cut
I ran into it totally by accident, because I had a spurious
'=cut' in my code I was debugging at the time and the effect
was it essentially "commented out" the entire subroutine between
it and the next cut. (which is why I never was able to get the
debugger to set the breakpoint where I wanted, much less actually
stop there :-)
I posted it to p5p (pod-people didn't exist yet) and it was
ruled a bug, and someone (I think it was Chip or maybe Kenneth)
posted a patch to the Perl5 codebase to the mailing list.
In terms of Pod::Parser, it was decided that a leading '=cut'
should never be interpreted to mean "here there be PODs" and
should always mean "thus endeth a POD section" (even if it
wasn't already in the middle of one).
So I made sure Pod::Parser would treat it that way - but it
does _not_ complain about it. I don't know if Pod::Checker
complains about it at present.
--
Brad Appleton <[EMAIL PROTECTED]> http://www.bradapp.net/
"And miles to go before I sleep." -- Robert Frost
