I really like Pod-Webserver. Sean Burke wrote it and it's an excellent
development too. It starts up a stand-alone HTTP webserver that does
nothing but show you documentation. Using it is simple. On the command
line just run one quick command.
podwebserver &
Run it from cron if you always want your pod webserver to be running.
The cheap way to do this is to understand that running 'podwebserver'
will fail if it can't bind to a port. So you could run something in cron
like this.
*/10 * * * * podwebserver 2>&1 > /dev/null
This allows me to read documentation that is pretty. The documentation
has working links from within documents and even among them. This is
great. I don't have to tie up terminals running perldoc.
Except that I do.
One thing I really use perldoc for is viewing the source of a module
that I have installed. You know how it is when you're tracking down
improper usage or are just interested in "How'd they do that?". And you
always want line numbers, which means I often find myself running some
command like this.
perldoc -m Parse::RecDecent | cat -n | less
Most sane shells will even let you write a quick script to make this
easier. The 'perlsource' program could look like this.
#!/usr/local/bin/bash
perldoc -m $1 | cat -n | less
The other option is to use http://search.cpan.org. It has support for
viewing the source, but only as plain text.
I decided to build an addition to Pod-Webserver, Pod-Webserver-Source.
It uses Perl::Tidy to reformat source code (and will honor your
~/.perltidyrc file) and display it in HTML format. It's really quite
sexy. A link is added to the top of the documentation output, it's
called Source. It looks like this.
And the source code produced looks like this by default (again, your own
settings may change the output).
And there you have it. I had to alter the 'podwebserver' program, so
now it looks like this.
#!/usr/local/bin/perl
eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
if 0; # not running under some shell
require 5;
use Pod::Webserver;
Pod::Webserver::httpd();
use Pod::Webserver::Source;
Posted from caseywest.com, comment here.
