2011 twenty-four merry days of Perl Feed

All Your Documentation, Even Offline

Perldoc::Server - 2011-12-16


A few years ago, Jon Allen set up perldoc.perl.org, a site where you could browse the core Perl 5 documentation. A few sites existed for this kind of thing, including search.cpan.org, but Jon's site blew the doors off of them. It had good search, nice styling, syntax highlighting, and lots of other little details that made it fantastic. It kept getting better, but the big question people kept asking was, "When can I run my own?" (Some people prefer to read all their documentation in the terminal, but these people are weirdos and can use different tools for that.)

Even with the Internet available almost anywhere, being able to work offline is a huge win. If your key reference materials – like the documentation of your programming language itself – go from being nicely available offline (via cpandoc) to only being available when you can access web pages, you're in line for some hard times. Having the man pages available as HTML is really tempting, though. Not only do they look quite nice, but their interlinking becomes very useful. Pod is a format with decent facilities for linking to other documents, but the perldoc makes those links pretty worthless. In HTML, they become an asset.

Fortunately for everyone who was desperate to get hooked on the perldoc server, Jon soon released Perldoc::Server. Not only did it let you run your own copy of perldoc.perl.org, but it went even further. It serves up nicely formatted web pages for all the documentation of all modules you've got installed in your Perl environment.

It's easy to see how it all works:

$ eval `perl -Mlocal::lib=~/local/perldoc`
$ cpanm Perldoc::Server

29 distributions installed
$ perldoc-server

Now listening on http://localhost:7375/

...and you can fire up your web browser, hit that URL, and see all the docs in your @INC presented in glorious HTML.

See Also

Gravatar Image This article contributed by: Ricardo Signes <rjbs@cpan.org>