On Thu, Mar 01, 2001 at 10:39:07PM -0500, Michael G Schwern wrote:
>
> > > (why is Filter required... just to read the test POD?
> >
> > It made the implementation of SelfTest trivial: about 120 lines of code
> > that mostly just throws away everything not =for testing. I like the
> > semantic that self testing is a special mode of running the file through
> > perl, just like perl -cw lib/Foo.pm is.
>
> This is irrelevant to using a Filter.
Using a Filter makes implementing the semantic I was after really easy
is what I was trying to say.
> > It's also probably faster than loading Pod::Tests and having it re-open
> > the source module, though, again, I'm not sure speed counts here.
>
> Anyway, what do you think Filter does???
Filter intercepts lines as Perl sees them, not reopens the file. Relax.
> > If Pod::Tests had a push style interface 'twould be extremely trivial.
>
> So you can parse multiple files and keep adding tests to the stack? I
> can make it do that. I don't quite see why you need it, since you're
> only testing one module/file at a time, right?
I wanted it so SelfTest's filter handler could feed source code to
Pod::Tests chunk by chunk and let it do the extraction.
> Anyhow, I really want to see the finding of the testing code merged.
Not sure what you mean. Do you mean that you want all utilities that
find testing code to use Pod::Tests? That would be nice, but POD, and
the trivial subset that marks test code, is so simple I doubt all people
will feel the need to require Pod::Tests. Getting it into the standard
dist would help a lot there, though.
> I'm not suggesting =for example.
Beg pardon, I thought you were since Pod::Tests implements it.
> I don't have any good way to include
> example code and have it work with existing POD viewers.
I've no good ones, only hacks you don't want to hear about :-).
> Just be
> aware that most POD viewers, including perldoc, will die if they see
> an unknown POD tag. This means =also and =alsofor.
See L<RFC11/Backwards Compatibility> :-).
> This is Very Bad for getting this working under Perl 5. Even if we
> modified the POD tools, people who haven't upgraded wouldn't be able
> to read the docs. That's Bad.
We're agreeing. I was pointing out that silent failure is worse than
loud failure and (IIRC) that =for example is cute but adds hidden
complexity to the semantics of =for and =begin..=end. =alsofor and
brethrin are blatant about behaving differently than =for & co.
Anyway, it seems like MakeMaker's PREREQ_PM can address some of this by
allowing module authors to require up-to-date podlators using
Pod::Parser's version number. Then we'd just need to make sure that
Pod::Parser and it's clients are backwards compatible with older perls.
I don't see that this is very different from requiring an up-to-date
Foo::Bar module.
Even if it's not something you'd want to ship your modules with, it's
nice to allow people to use self-testing examples in private code where
they can use up to date podlators.
- Barrie
