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?
Installation
Pod::POM::Web has few requirements, but the installation
wasn’t as clean as I had hoped. For some reason, though the CPAN shell
downloaded Alien::GvaScript
and built it, it didn’t install correctly. I used the command look
Alien::GvaScript to rebuild, re-test, and install the
distribution.
That worked, and subsequently Pod::POM::Web installed
correctly. (I couldn’t figure out what went wrong, so it may have just been
a quirk of my environment.)
Usage
You can run the module in several ways. I declined to start up a full-blown Apache instance on my laptop for testing, so I opted for the standalone server. Running it is easy. The documentation suggests:
$ perl -MPod::POM::Web -e "Pod::POM::Web-server">In a terminal window, that said:
Please contact me at: <URL:http://waterwheel:8080/>Unfortunately, that gave me a blank page in Firefox. I looked at the HTML:
<script>location='/index'</script>I have NoScript active, so I changed the URL:
http://waterwheel:8080/indexThis worked better. It produces a three-pane view, with a search box in
the upper left (to search perlfunc, perlfaq,
modules, or fulltext). The lower left contains a list of pragmas, core
documents, and installed modules.
Navigation Trouble
The module list shows only top level namespace components. That is,
there’s no Test::More, but there is Test. This
confused me; I expected to click on Test to see a tree
expansion.
I enabled JavaScript for waterwheel and tried again. No luck.
Pod::POM::Web::Help
gives instructions, but they didn’t work for me.
The documentation for Test links to
Test::Harness; clicking that link brings up the documentation.
That part works so far.
I continued to fiddle with the keyboard shortcuts and mouse clicks and was able to get the tree list to expand somewhat… but it’s still confusing. Even so, I don’t browse looking for modules I have installed very often.
Positives
Typing module names in the search box works nicely. Even without the JavaScript this is still highly useful. There are links to show source code, AnnoCPAN notes, and CPAN Forum discussions. The documentation display also appears to use Module::CoreList , which shows when and if a module entered the Perl core.
Not only is this more featureful than the default view on search.cpan.org, it’s much faster; it’s on my local machine.
It is probably the work of a few minutes to write a little shell program
to launch the browser and a Firefox tab, given a module name. I might try
that instead of perldoc for a week or two at some point in the
future. This is a useful module, even for minimal personal use.
Also, Pod::Webserver.
Oh yes, I like Pod::Webserver. It's Hack #4 in Perl Hacks for a good reason!
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 :-)
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.
"Pod::POM::Web-server"> <-- There is a misspelling. :-)
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.
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"
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!
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.
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
./Build test
./Build install
(make test & install didn't work..)
now whow!
Really cool tool.
thanks!
:m)