Hi, Not sure if I should be replying to the list or to the author. Sorry if I made the wrong choice. :-) For the record, I am really enjoying your RFC's :-) > 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. Sounds good. > > =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. The Perl Data Language (PDL) comes with support for =for example but only uses it for online documentation support. They have private versions of Pod::Parser that recognises the 'example' tag (as well as 'usage' and others). > Modifying all the POD utilities so they know to display "=for example" might > be a pain. I think there needs to be a pod pre-processor (before it hits Pod::Parser) to convert the =for example into the correct pod display format (or removing it). This would then also do the method() to C<method()> translation independently of the translator. > 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. As above. Automatically remove the =for example and replace with =head2 example before Pod::Parser gets it. -- Tim Jenness JCMT software engineer/Support scientist http://www.jach.hawaii.edu/~timj
