Then there are the myriad variations of POD formatter behavior. A quick survey leads me to believe most aren't valid (just write some POD inside a string literal or heredoc, and see what your favorite formatter does).
My pet peeve is the lame link tag that can't seem to deal with matching text up with a URL. WTF ? HTML has been doing that for over a decade!
POD's weakness is its simplicity. Its a formatting discipline, not a content discipline. The result is random adherence to somewhat arbitrary de jure standards.
About 18 months ago I was in a bit of a quandry as to how to provide usable docs to a paying customer for a fairly large project with lots of packages, and complex concurrency issues. Part of that exersize led to some upgrades for UML::Sequence. Another part was development of a little formatter for a javadoc-ish embedded docs solution. The customer was very pleased with the resulting docs.
Thanks to PPI and Pod;:ProjectDocs, plus a few helper modules, I've managed to get the formatter into CPANable shape, in the form of Pod::Classdoc. The resulting toolset includes
- HTML::ListToTree for easily converting HTML nested list hierarchies into AJAXy Javascripted navigation trees.
- PPI::HTML::CodeFolder for compressed and codefolded versions of PPI::HTML output, along with some anchors at package and method definitions.
- Pod;:Classdoc to format the aforementioned classdoc POD from within a source tree
- Pod;:Classdoc::Project to merge all the above, along with the output of Pod::ProjectDocs, into a single set of project documentation.
Here's an example of the result. It was generated using just the following command:
(Well, yes, I did have to write the embedded classdocs... but thats sortof the point)mkprojdocs -f -o ./classdocs -t "Pod::Classdoc" -d "Generate merged pr +oject documentation" -D Pod-Classdoc-1.01.tar.gz
So if you're looking for a better content discpline for those large Perl projects, and POD just ain't cuttin' it, Pod::Classdoc might fit the bill.
Perl Contrarian & SQL fanboy
|
---|
Replies are listed 'Best First'. | |
---|---|
Re: Perl for Perl's Sake: Yet Another Perl Doc Tool
by EvanCarroll (Chaplain) on Aug 20, 2007 at 00:18 UTC | |
Re: Perl for Perl's Sake: Yet Another Perl Doc Tool
by MidLifeXis (Monsignor) on Aug 22, 2007 at 17:42 UTC | |
by renodino (Curate) on Aug 22, 2007 at 18:45 UTC |