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>