OK, I took the bait! Attached is a source filter called Plod.pm and an example file that uses it. (You'll need to have Filter::Simple installed to use it.) It's not the most elegant thing in the world, but it shows how you can do some fun stuff to intermix pod and code in a way that is fairly legible when run through a POD renderer. For example, visit http://search.cpan.org/pod2html and upload test.plod, and give it a read. Then run "perl test.plod" to see what the program does.
It kinda sucks that you have to end any "=for code" blocks with a "=pod" directive, but that could be addressed with a more sophisticated source filter. It's not super awesome rich-text or anything, but it's not too bad and hopefully it can serve as inspiration for somebody. :-) David On Tue, Dec 18, 2012 at 7:09 AM, Timothy Pickering <[email protected]>wrote: > > The chief reason is that Perl's documentation format, POD, is actually > really good, unlike Python's documentation format, for example. As such, > Perl programmers have bent their expectations and mode of expression into > using the tool at hand (POD) rather than creating the more expressive > notebook style of documenting things. > > you can compare POD to python docstring/doctest, but comparing it to > ipython notebooks is completely apples to oranges. notebooks aren't for > documenting python code, but rather to document work done using python. > you want to use something like POD to document the final, production > scripts/code, but something like a notebook is very, very handy for > figuring out, documenting, and sharing the steps taken to get there. > > tim > > -- > +-------------------------------------------------------------------+ > | T. E. Pickering, Ph.D. | Southern African Large Telescope | > | SALT Astronomer | SAAO | > | [email protected] (520) 305-9823 | Observatory Road | > | [email protected] +27(0)214606284 | 7925 Observatory, South Africa | > +-------------------------------------------------------------------+ > overflow error in /dev/null > > > > _______________________________________________ > Perldl mailing list > [email protected] > http://mailman.jach.hawaii.edu/mailman/listinfo/perldl > -- "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it." -- Brian Kernighan
Plod.pm
Description: Binary data
test.plod
Description: Binary data
_______________________________________________ Perldl mailing list [email protected] http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
