[[CCed back to perl-qa]] Marek Rouchal DAT CAD HW Tel 25849 wrote: > > I don't understand the benefit of =also in this context. Could you please > elaborate some more on this? The goal is to be able to extract snippets of example code from the POD and test them. The =also solution is kind of a literate programming approach: the =also sections would show up in the documentation generated by the Pod2HumanFoo converters, and they would "also" be included in test scripts generated by C<make pure_all> in t/example/*.t, probably using a module named like Pod::ExampleTests. Here's an example I'd like to be able to write in IPC::Run (http://search.cpan.org/doc/RBS/IPC-Run-0.4/Run.pm): /--------8<------------8<------------8<------------8<---------8<--------\ =item run =begin example_init run.t #!perl -w use strict ; use IPC::Run qw( run ) ; use Test ; my $cmd = $^X ; my @args = '-le', 'print "Hello World"' ; my $stdout ; plan test => 1 ; =end example_init =also for example run( [ $cmd, @args ], \undef, \$stdout ) ; =for example_wrapup ok( $stdout, "Hello World\n" ) ; Run takes a harness or harness specification and runs it, pumping all input to the child(ren), blah, blah, blah... =cut sub run { my IPC::Run $self = start( @_ ) ; $self->{clear_ins} = 0 ; $self->finish ; } \--------8<------------8<------------8<------------8<---------8<--------/ pod2text would generate this, which I got by merely deleting the =also line: /--------8<------------8<------------8<------------8<---------8<--------\ run run( [ $cmd, @args ], \undef, \$stdout ) ; Run takes a harness or harness specification and runs it, pumping all input to the child(ren), blah, blah, blah... \--------8<------------8<------------8<------------8<---------8<--------/ And the gleam-in-my-eye pod2examples would generate this in t/examples/IPC-Run-run.t: /--------8<------------8<------------8<------------8<---------8<--------\ #!perl -w use strict ; use IPC::Run qw( run ) ; use Test ; my $cmd = $^X ; my @args = ( '-le', 'print "Hello World"' ) ; my $stdout ; plan test => 1 ; #=end example_init #=also for example run( [ $cmd, @args ], \undef, \$stdout ) ; #=for example_wrapup ok( $stdout, "Hello World\n" ) ; \--------8<------------8<------------8<------------8<---------8<--------/ > Thinking of "=for example": > Sounds nice to me, but keep these issues in mind: > > * one would have to use =begin example ... =end But of course :-). Sorry my message didn't make that clear enough. > * Pod::Parser currently leaves processing of =for and =begin ... =end > completely up to the calling code. Basically I like this, but introducing > special pre-defined =for directives might make it necessary to extend > Pod::Parser. I don't want to mess with =for, =begin, or =end semantics. I do want to add "=also for", "=also begin" and "=also end" to Pod::Parser, though. I'm not worried about how we spell them, since "=also_for" probably eases processing. > Then however you would give up control over the POD, > e.g. when a "=for example" paragraph is automatically turned into a > verbatim one. How would a "Pod::Example" then extract such example > paragraphs using Pod::Parser? Pod::Parser would (by default) completely ignore "=also for" and would ignore "=also begin" and "=also end" and all blank lines after them. I *think* this means treating them like "=pod", but I'm not 100% sure. Pod::Examples would then override the handling of the /=also.*/ and /=(for|begin|end)/ commands and handle the "example_init", "example", and "example_wrapup" arguments. There's at least one this I'd want to add to Pod::ExampleTests (or whatever) to make the example_init sections less verbose, but you get the idea. > Therefore I'd suggest to keep Pod::Parser as is and to add code to > e.g. Pod::ParseUtils to deal with predefined paragraphs. Still this > requires to change the existing formatters in order to display such code. Whatever makes sense. > Another issue: Should all "example" paragraphs from one POD be accumulated > into one script or do we need the possibility to have several different > example code snippets? Oh, we'd definitely need the option to have different snippets. There's no way you could do everything in one file all the time without generating heinously eval code. And even that would have limitations if the examples play with namespaces too much. By the same token, you should be able to have all examples in one test script, or map many-to-many. I think the above example shows a syntax that enables that. > Just some thoughts... Thanks. - Barrie
