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
