CPAN Module Review: Pod::POM::Web

by chromatic

Perl has a long history of copious documentation through the Plain Old Documentation format. This applies to much of CPAN, not just the core modules and documentation.

The perldoc utility is the main way to view this documentation. It has more features than people imagine (it was worthy of Hack #2 in Perl Hacks), but it's a command-line tool only. Even for a CLI fan like me, sometimes hyperlinks are nice.

Pod::POM::Web is a CPAN distribution which turns all of the POD on your system into browsable, linked HTML. I use perldoc all the time; could anything displace it in whole or in part?


Sean M. Burke
2007-05-25 15:50:06
Also, Pod::Webserver.
2007-05-25 16:00:17
Oh yes, I like Pod::Webserver. It's Hack #4 in Perl Hacks for a good reason!
Ivan Wills
2007-05-26 06:07:12
Personally I'm all for DocPerl which has just had version 1.0 released 4 days ago. Though I could be because I wrote it :-)
Ken Williams
2007-05-26 20:57:05
The main difficulty I see with Pod::Webserver is that it won't notice when new versions of modules get installed. Not sure the best way to do that for the index page, since indexing seems to take at least a few seconds. Maybe a touchfile whose timestamp could be checked whenever the index page is loaded, or every 5 minutes of daemon inactivity, or something.
2007-05-27 23:01:14
"Pod::POM::Web-server"> <-- There is a misspelling. :-)
2007-05-28 08:53:57

Hi chromatic, I'm the author of Pod::POM::Web

Thanks for reviewing it ... but if you try to run an application advertised as DHTML/Ajax without Javascript enabled, no surprise you don't get very satisfying results!

It is on purpose that only top-level namespace components are displayed in the browsing panel. Then you open/close nodes as in a file explorer tool or like folders in a mail application, and node contents gets loaded dynamically through Ajax calls


I guess you didn't see either the other DHML features, like autocompletion of module names or function names in perlfunc, or dynamic opening/closing of sections while reading documentation, or the fulltext index

So give it another try!

Best regards, laurent

PS and please open a bug in RT about the Alien::GvaScript installation problem. I'm a bit surprised, because there is no code, just file copies -- but anyway I'll be happy to fix the problem if I can understand it.

Chris Dolan
2007-05-29 20:08:45
I quickly became a big fan of Pod::POM::Web. One feature I contributed to it is inlining AnnoCPAN comments via the AnnoCPAN::Perldoc package. Instructions for how to enable that mode are in the Pod::POM::Web docs under "optional features"
2007-05-30 12:44:38

Chromatic ... sorry for my previous comment.

I just understood,thanks to RT bug
#27344, that there was a stupid regression bug in Pod::POM::Web v1.05 on Firefox.
So you reviewed a buggy version, hence my misunderstanding.

Who would have guessed
that a Content-type: text/css with charset=ascii would be rejected by
Firefox ?

So grab version 1.06, just uploaded to CPAN ... you will see something very different!

2007-06-11 20:25:25
Wow, Pod::POM::Web is an awesome work...It even has the code snippets in Pod syntax-highlighted with various colors...And the AJAX stuff works fine in my ubuntu build of firefox. :)

The only problem I've met so far is that one of its dependency, Alien::GvaScript 1.03, failed its own pod coverage tests and I had to install it with force.

2007-06-13 12:25:05
Here is my adventure:
installing via CPAN shell.
get & install Pod::POM::Web exited with some error (;-)
had to
install Module::Build
look Alien::GvaScript
perl Build.PL
./Build test
./Build install

(make test & install didn't work..)

now whow!
Really cool tool.