2009Q1 Grant Proposal: Pod Mangling Utility Improvements

Category: Grants

Comments (8)

I hate writing (or copy & pasting) POD boilerplate. I've loved using Dist::Zilla's tools for eliminating the need for such boilerplate, and I'd love to see those tools made more robust.

This I think has the biggest bang for the buck to the current Perl(5) community. Developing more tools to make documentation easier can only help things improve in the long run, and Ricardo has a proven track record of developing useful and well build modules. If he's crazy enough to step into the world of POD, I say all we can do is say "Go forth brave warrior, we'll tell your children stories of your heroisim."

This definitely has potential, and I trust rjbs to write something sane. I think there's a lot to be said for funding people whose previous work is well-known to the community (but I would say that, wouldn't I?)

POD looks deceptively simple, but is really kind of strange when you dig down into it. It'd be nice to have better tools for POD munging (not just to make pretty docs, but for detailed manipulation). A DOM or SAX style interface would be nice if that's not too much trouble :)

And I agree with Chris Prather that Ricardo is good for crazy details.

There are many modules on CPAN to do with POD. How would this compare to Pod-POM "POD Object Model", for example?

There are a few key differences, at least. The most important, for me, is the fact that POM is more tied to "standard" POD commands and a single set of nesting rules. Pod::Elemental makes fewer hard and fast assumptions: you start with a stream of elements rather than a tree, and your rules for nesting them are mostly up to you. After all, while it might seem sensible that a "=over" after a "=head2" should be inside it, you might disagree. This becomes much more important when you extend the commands available to add things like "=method" or "=dialect"

Pod::POM's handling of unknown commands is, at least to me, confusing, though I didn't spent too long trying to understand it exactly. The tying together of views and parsing is where I started to feel this wasn't right for my work.

It's also built atop Pod::Eventual for getting the event streams from which the element streams are built, making it easier to replace that component as well.

One shortcoming (or, rather, one feature I've excluded as unneeded for my applications) is support for embedded sequences like B>. I may eventually add them with another layer, but I don't see a need for it, and it would certainly not be done as part of this grant work.

Finally, Pod::Weaver, which sits atop ::Elemental, is an entirely different animal. It is meant to slice up and rearrange or add to POD trees. It needed a flexible tree builder to be written to perform its goals, especially command types.

Sounds interesting, but I thing we need a simple example(with apples) of what are you intended to do).

I recommend perl community to see the slides


and form your own opinion.

Sign in to add comment