Russ Allbery wrote:
>
> I can sort of see the point, although I'd personally use a considerably
> simpler approach for extracting code excerpts for testing, probably more
> ad hoc. That may be a mistake on my part, and I can see why people would
> want to do this in some more formal way.
That's the main starting point for all of the other debate about factoring
out functionality. Brad doesn't want it to go in to the main Pod::Parser,
I don't want to have every POD translator maintainer/author have to implement
=also functionality.
Having read your other messages, I realize that implementing most of the
other things useful in each translator is a few handfuls of lines of code.
It would be nice to factor what we can. But not necessary. I
haven't got a good read on if there is a need for such a class outside
of the normal perl std dist pod processing. I suspect not. I'd be Ok with
us putting C<=also>, or something like it in each of the standard translators.
My original proposal was to hack Pod::Parser so we (you :-) wouldn't have to.
I do think having a standard, recommended, easy way to test examples is
worth doing (obviously), and I like the C<=also> syntax, but I'm not
wed to it: other suggestions welcome.
> I dislike the syntax; there shouldn't be a need to introduce a new
> primitive. I'd much rather see this handled by increasing the power of
> C<=for> and C<=begin> in some fashion, possibly as simple as teaching
> translators to accept C<=for code> and C<=begin code> blocks as verbatim
> blocks and having the POD munger that generates test code only grab stuff
> bounded by either those markers or C<=for test>/C<=begin test> for the
> setup code that shouldn't be in the documentation.
If we document C<=for code>/C<=begin code> to do this, and tweak all the
translators, I don't can live with it (I just want to use whatever syntax we
cook up), but those do look like new two-word primitives to me, and strike
me as being less clear to the person reading the code than C<=also for
test foo.t>, especially given the C<=for test foo.t> likely to be hanging
around nearby.
It would save typing, but I personally don't give that a high priority (YMMV).
Here's examples of C<=for code> and C<=also for test>:
--------8<-----------8<----------
=for test run.t
#!perl -w
$cmd = $^X ;
print "1..1\n" ;
=for code run.t
run( [$cmd, @args] ) or die "$!: $cmd" ;
=for test run.t
print "ok 1\n" ;
--------8<-----------8<----------
=for test run.t
#!perl -w
$cmd = $^X ;
print "1..1\n" ;
=also for test run.t
run( [$cmd, @args] ) or die "$!: $cmd" ;
=for test run.t
print "ok 1\n" ;
--------8<-----------8<----------
I could also see, instead of C<=also>, providing an C<=for documentation_too>
escape mechanism (better spellings welcome) within =begin/=end that exposes
otherwise hidden code to translators that otherwise ignore the stuff between
a normal C<=begin>..C<=end> sequence:
--------8<-----------8<----------
=begin test run.t
#!perl -w
$cmd = $^X ;
print "1..1\n" ;
=for documentation_too
run( [$cmd, @args] ) or die "$!: $cmd" ;
print "ok 1\n" ;
=end test run.t
--------8<-----------8<----------
There we begin to get in to nesting issues (we'd want to nest
C<=begin documentation_too>...C<=end documentation_too> inside of other
C<=begin>...C<=end>s.
--------8<-----------8<----------
=begin test run.t
#!perl -w
$cmd = $^X ;
print "1..1\n" ;
=begin documentation_too
run( [$cmd, @args] )
or die "$!: $cmd" ;
=end documentation_too
print "ok 1\n" ;
=end test run.t
--------8<-----------8<----------
- Barrie
