Front page | perl.bootstrap |
Postings from July 2000
In One Sentence
---------------
All code examples in the Perl docs can be at a minimum tested for syntax
errors in an automated fashion.
Synopsis
--------
Its common enough to put code examples into the Perl documentation, and its
also common enough for this example code to not work. Usually its just a
silly typo or other such simple thing. It would be great if there was a way
to automate some simple compilation tests of examples.
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.
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.
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.
Example code is often incomplete and inherently won't compile or will have
warnings. We can allow POD authors to put in prefix and suffix code bits to
flesh out their examples. POD utilities would not display this text but it
would use it for testing purposes.
=for example prefix
use LWP::Simple;
=for example
$page = get("http://www.perl.org");
(Its a weak example, but you get the idea).
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...
Spin-offs
---------
Some people use POD as their primary formatting language. "Programming Perl"
is written in a mutated form of POD. I write most of my papers in POD.
Allowing automated tests of example code will make it even more useful in this
role.
Things to do NOW
----------------
- Examine the feasibility of modifying all the core POD utilities to display
=for example.
- Write POD::Example.
- Examine the feasibility of modifiying all the core documentation to use this
new tag for example code.
- Run the tests and be appalled.
Blame
-----
All blame for this RFC can be transfered to Michael G Schwern
<schwern@pobox.com>
--
Michael G Schwern http://www.pobox.com/~schwern/ schwern@pobox.com
Just Another Stupid Consultant Perl6 Kwalitee Ashuranse
Plus I remember being impressed with Ada because you could write an
infinite loop without a faked up condition. The idea being that in Ada
the typical infinite loop would be normally be terminated by detonation.
-- Larry Wall in <199911192212.OAA23621@kiev.wall.org>