Thursday, March 18, 2010

POD is not literate programming

I frequently come across assertions that POD, Perl's documentation system, is an example of `Literate Programming'. [...] But POD is not literate programming.

Why is this important? POD is a really good idea. But literate programming is an even better idea. Perl has a long history of borrowing good ideas from elsewhere. If we go around thinking that POD is literate programming when it isn't, that'll lead us to disregard literate programming when we hear about it. ``Oh, I already know what that is,'' we'll say. But we don't know what it is, and since it's such an excellent idea, it would be a shame if we missed out on it just because we thought we already knew what it was.

--Mark-Jason Dominus, March 20, 2000.

MJD wrote this quick article for perl.com ten(10) years ago this week. Where have we come since?

We have some slightly more flexible POD systems. I'm using Pod::Weaver with Dist::Zilla (via Dist::Zilla::Plugin::PodWeaver )to post-process my modules to move the POD around.

This lets me write in pseudo POD with tags like =method which will then be gathered and turned into appropriate sorted =over, =item entries and all the POD put together after the __END__ block. Pod::Loom looks like a similar system, which also has a Dist::Zilla plugin.

This is a much more fun and interesting way to write my POD, but this is still not literate programming. I want a weaver that will stitch together a nice TeX output suitable for a journal. That would be HOT.

2 comments:

Anonymous said...

I'm working on TELPS (The Extensible Literate Programming System) that will do what you want. TELPS rhymes with helps. To subscribe to the very light traffic mailing list go to (the web address below should all be on one line)

http://lists.sharpresearch.com/mailman/listinfo/telps-announce

Mark Senn

Andrew Grangaard said...

Mark that sounds pretty interesting, thanks for the comment and pointer.

What stage are you at in the project:
idea, research, discussion, documentation, prototype, implementation, complete, maintenance or nirvana?

This page is currently the top result (of 3) on google for [TELPS (The Extensible Literate Programming System)]! :)

Can you give a comparison to other literate systems, e.g. noweb?