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/index

This 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.