Local POD browsing: using Pod::POM::Web via the CLI

Posted in: Technical Track

Half the time I want to peek at the doc of a module, I hit perldoc.  The rest of the time I type cpan Some::Module[1] in Firefox and read the POD straight out of CPAN.  And while it’s pretty and handy, it also feels kinda silly to go on a remote server to read documentation that is also sitting on my computer. Surely, I tell myself, there must be a better way.

Cue in the several Perl modules that act as local POD web servers.  After giving a few of them a quick test-run, I decided to give Pod::POM::Web a try. Being a CLI jockey, I wanted to be able to open the POD of a module from the command line.  Not a problem, I just had to create the script ‘pod’:

[bash] #!/bin/bash


perl -MPod::POM::Web -e"Pod::POM::Web->server($POD_PORT)" 2> /dev/null &

PAGE=`perl -e’s(::)(/)g for @ARGV; print @ARGV’ $1`


kfmclient openURL "https://${HOSTNAME}:$POD_PORT/$PAGE";

There is not even a need to fire up the Pod::POM::Web server beforehand: the script will do it for us (if the server is already running, subsequent calls to pod will harmlessly try to start a new server on the same port and fail).  It should be noted that ‘kfmclient’ is KDE-specific — for any other desktop environment, you might want to change that to a direct call to firefox.

It’s already not too shabby, but wouldn’t it be even better with a little bit of auto-completeness magic?  To do that, we need a short script, pod_complete:

[perl] #!/usr/bin/perl

use 5.010;

use List::MoreUtils qw/ uniq /;

my ( $sofar ) = reverse split ‘ ‘, $ENV{COMP_LINE};

$sofar =~ s(::)(/)g;

my ( $path, $file ) = $sofar =~ m!^(.*/)?(.*)?$!;

my @dirs = map { $_.’/’.$path } @INC;

my @candidates;

for ( @dirs ) {
opendir my $dir, $_;
push @candidates, grep { /^\Q$file/ } grep { !/^\.\.?$/ } readdir $dir;

if ( $path ) {
$_ = $path.’/’.$_ for @candidates;

s/\.pm$// for @candidates;
s(/+)(/)g for @candidates;

say for uniq @candidates;

All that is left is to add . . .

complete -C pod_complete pod

. . . to our bashrc, and it should all work (with the caveat that the modules must be entered as Some/Module instead of Some::Module).

$ pod XML/XPath
XML/XPath        XML/XPathScript

[1] If you don’t already know the trick: create a bookmark with keyword ‘cpan’ and location https://search.cpan.org/search?query=%s.

Want to talk with an expert? Schedule a call with our team to get the conversation started.

3 Comments. Leave new

For info, I just released a new version of Pod::POM::Web (v1.13), with a number of bug fixes and improvements. It also depends on a new version of Alien::GvaScript.

Yanick Champoux
January 18, 2010 12:48 pm

Excellent timing! Thanks.

So far, the only functionality that I’m missing from PPW is a regexp search on modules — e.g., give me all modules matching /CSV/. Having that last piece would really be the bee’s knee. :-)

Yanick Champoux
February 15, 2010 12:05 pm

UPDATE: Aristotle took a shine for my completion script and ran away with it. The result is a much, much cleaner and portable codebase.

Details at https://blogs.perl.org/users/aristotle/2010/02/a-bash-completion-helper-for-perldoc.html and https://blogs.perl.org/users/aristotle/2010/02/more-bash-completion-help-for-perldoc.html, and the code itself is at https://github.com/ap/perldoc-complete


Leave a Reply

Your email address will not be published. Required fields are marked *