All the Perl that's Practical to Extract and Report

Pod sucks! Long live Pod!

Matts on 2006-09-07T01:16:44

I got sick and tired of so much vertical whitespace when writing Pod lists. So I wrote, and uploaded to CPAN, XML::Filter::EzPod. It takes any text in an ordinary paragraph and turns lines that start with 

/^\*+\s/
into bullet points of the appropriate level, and the same for hashes/pounds (turns them into ordered lists).

It plugs into Pod::SAX, which makes this kind of filter approach really easy.

Incompatible formats

SuperCruncher on 2006-09-07T08:05:20

I agree that is a much more convenient syntax than =item *, but I'm getting a bit concerned about having multiple different POD dialects around, like PseudoPod, SPOD5 (not a separate POD syntax as such though), forthcoming Perl 6 POD (any news on it, anyone?), pod2pdf and so on.

Surely a =version command should be introduced so that POD parsers can reliably tell if they can process the document? I discussed this with Allison Randal at YAPC::Europe, and apparently the plan is to allow POD documents to specify extra modular pieces of functionality or syntax that they use, which is an interesting approach. (Seems a bit like 'roles' for POD.)

Re:Incompatible formats

dagolden on 2006-09-07T09:43:14

My approach to this with Pod::WikiDoc was to explicitly define a Pod format to write in then and pre-process that format into a "canonical" .pod file that is distributed with my modules.

See my Pod::WikiDoc lightning talk for examples.

Re:Incompatible formats

Matts on 2006-09-07T10:55:04

Enforcing use of an =ezpod tag would be easy. I don't mind doing that.

I probably should have waited for a definitive format, but since it doesn't break anything if you don't pre-process it I didn't see it as a huge issue, and I needed this now.

(FWIW I modelled the design after Spod5 - but mine allows multiple levels).

Re:Incompatible formats

Matts on 2006-09-07T11:00:33

BTW: There's no new "syntax" in PseudoPod - it seems to me that it behaves like any decent Pod parser should (well, it parses Pod in exactly the same way Pod::SAX does). Not sure why O'Reilly needed to write a new parser for it. Could have done all that with a couple of Pod::SAX plugins.