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.
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.
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?
Pod::POM::Web has few requirements, but the installation
wasn’t as clean as I had hoped. For some reason, though the CPAN shell
and built it, it didn’t install correctly. I used the command
Alien::GvaScript to rebuild, re-test, and install the
That worked, and subsequently
correctly. (I couldn’t figure out what went wrong, so it may have just been
a quirk of my environment.)
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:
I have NoScript active, so I changed the URL:
This worked better. It produces a three-pane view, with a search box in
the upper left (to search
modules, or fulltext). The lower left contains a list of pragmas, core
documents, and installed modules.
The module list shows only top level namespace components. That is,
Test::More, but there is
confused me; I expected to click on
Test to see a tree
waterwheel and tried again. No luck.
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.
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.