Pod::POM::Web

ChrisDolan on 2007-04-21T06:35:40

I saw Chris Laco's post about Pod::POM::Web this evening and decided to try it out. Pod::POM::Web is a handy web app that converts POD to HTML on the fly for any Perl module installed in @INC on your machine. POM is short for POD Object Model[1], in analogy to a DOM.

The preferred mode of operation seems to be mod_perl 2, which is a no-go on my Mac which ships with Apache 1.3 and mod_perl 1. So I decided to try the standalone mode. I captured a PNG screenshot in Firefox. It's POD rendering/css is not nearly as pretty as search.cpan.org but wow is it fast and useful! I'm in love already.

The standalone mode has a few bugs that I wrote patches to fix. Furthermore, I wrote a quick CGI program that launches the standalone server if it isn't already running:

#!/usr/bin/perl -w                                                                                        

use strict;
use CGI;
use LWP::Simple qw(get);

my $podurl = 'http://localhost:8080/';
if (!get($podurl)) {
   require Net::Server::Daemonize;
   require Pod::POM::Web;
   if (!Net::Server::Daemonize::safe_fork()) {
      Net::Server::Daemonize::daemonize('www', 'www');
      open STDOUT, '>>', '/var/log/pod-pom-web.log';
      open STDERR, '>&STDOUT';
      Pod::POM::Web->server;
      exit 0;
   }
   sleep 2;
}
print CGI->redirect($podurl);

A few notes on that code:

1. It checks if the Pod::POM::Web server is up by fetching a page
2. It's quite Unix-specific: the user "www" that Apache runs under on Mac is hard-coded, as is the log path
3. It uses Net::Daemon::Daemonize to fork and detach the child process. Otherwise, Apache waits around for that child to quit and be reaped (IIUC).
4. daemonize chdirs to '/', so make sure you don't have any relative paths in your @INC (I got bitten by that while working on Pod::POM::Web patch in ./lib and had my require after the call to daemonize)
5. The parent sleeps for a couple seconds to give the child process time to bootstrap

[1] That makes Pod::POM::Web expand out to "Plain old documentation :: Plain old documentation object model :: Web". So, if you are the type that hates to hear "PIN number" then Pod::POM will make you itch.