Below is the message that inspired this.
How about adding an C<=also> POD tag? It would have three syntaxes:
=also for ...
=also begin
=also end
These would be much like the existing three tags but "normal" POD
converters would completely ignore them. Then we could have:
------------8<-----------8<-----------
=begin example preamble
... setup code ...
=end example preamble
=also begin example
... example code ...
=also end example
=begin example postamble
... cleanup code && print use Test style results ...
=end example postamble
------------8<-----------8<-----------
- Barrie
Barrie Slaymaker wrote:
>
> Michael G Schwern wrote:
> >
> > Using the =for POD tag we can do this.
> >
> > =pod
> >
> > Here is a nice example of how to add one and one in Perl.
> >
> > =for example
> >
> > print 2 + 2;
> >
> > The existing POD utilities would have to be modified to consider "=for
> > example" as Perl code which is to be displayed with an implied C<> around it.
>
> I'd let the normal "leading whitespace" trigger the presentation formatting,
> but you would need to teach Pod::Parser to know about it.
>
> >
> > A little POD::Example module could be written which will find these bits of
> > code and run them through "perl -cw" and maybe a few other simple syntax
> > tests.
> >
> > Problems
> > --------
> >
> > Modifying all the POD utilities so they know to display "=for example" might
> > be a pain.
>
> Modify Pod::Parser and think of it as encouragement for people to use it.
>
> > There are backwards compatibility issues. Running a POD document with "=for
> > example" on older POD utilities will mean the examples will disappear. This
> > is a problem for which I have no solution. Maybe "=for example" isn't the
> > best syntax choice.
>
> =begin example
>
> =end example
>
> Work the same as =for example, but have the same problem.
>
> One way I can see to work around your dilema would be kludgy:
>
> =begin example_preamble
>
> #!perl -w
> use LWP::Simple
> use Test ;
>
> =end example_preamble
>
> $page = get("http://www.perl.org");
>
> =begin example_postamble
>
> ok( $page, qr/foo/ ) ;
>
> =end example_postamble
>
> Anything that is indented between =begin example_preamble and =end example_postamble
> would be the test script, anything with no leading spaces would have '# ' prepended.
>
> > Exactly how strict our testing of code examples should be is up in the air.
> > Should we just perl -c? What about warnings? strict? B::Lint? This can be
> > partially solved by providing tiers of testing. First tier might be perl -c.
> > Second might be perl -cw, etc...
>
> I snuck a #! line in there to let the coder determine it.
>
> - Barrie
