Perl Hacks

Hack #3. Browse Perl Docs Online

Host your own HTML documentation.

perldoc is a fine way to view the documentation for Perl and all your installed modules and to output them in the file format of your choice ("Put Perldoc to Work" [Hack #2]). perldoc's little brother, podwebserver, is an even handier way to browse documentation—and bookmark it, and search it, and sometimes even hardcopy it, all through whatever web browser you're using this week.

The Hack

podwebserver provides basically perldoc-as-HTML over HTTP. Sure, you could always just browse the documentation at http://search.cpan.org/—but using podwebserver means that you'll be seeing the documentation for exactly your system's Perl version and module versions.

podwebserver's HTML is compatible with fancy browsers as well as with more lightweight tools such as lynx, elinks, or even the w3m browser in Emacs. In fact, there have been persistent rumors of some users adventurously accessing podwebserver via cell phones, or even using something called "the Micro-Soft Internet Explorer." O'Reilly Media, Inc. can neither confirm nor deny these rumors.

If podwebserver isn't on your system, install the Pod::Webserver module from CPAN.

Running the Hack

To run podwebserver, just start it from the command line. You don't need root access:

$ podwebserver
            

Then start a web browser and browse to http://localhost:8020/. You'll see the index of the installed documentation (Figure 1-2).

Figure 1-2. An index of your Perl documentation

If you don't want to bind the web server to localhost, or if you have something already running on port 8020, use the -H and -p arguments to change the host and port.

$ podwebserver -H windwheel -p 8080
            

Hacking the Hack

Running a program and switching to your web browser to view a bookmark is too much work when you just want to check some documentation. Make your life easier with a little shell script ("Make the Most of Shell Aliases" [Hack #4]):

#!/bin/sh

podwebserver &
sleep 2
firefox -remote 'openurl( http://localhost:8020/, new-tab)'

Save the program as ~/bin/podweb, make it executable (chmod +x ~/bin/podweb), make sure ~/bin/podweb is in your $PATH, then run it:

$ podweb
            

If you have Mozilla Firefox open, this will pop up the index page in a new tab. Other web browsers have similar invocation schemes.