Three cheers

jdavidb on 2003-11-21T05:46:45

Just now I was browsing the docs for File::Find::Rule on search.cpan.org. There was a link to the documentation for -X in perlfunc. I clicked the link, and it just worked[tm].

Then I sat back and marvelled at what had happened. Wasn't so long ago that the HTML perl documentation online on CPAN had apologies all over the place for the broken links. Wasn't so long ago that building the HTML documentation yourself generated more errors and warnings than you could read in a lifetime. Wasn't so long ago that the HTML documentation you built, if it worked at all, was barely readable because of the formatting. Wasn't so long ago pod "links" were a joke and were little better than just telling you to go find that page of documentation yourself.

Now it all just works. Links from module docs go straight to an anchor in the standard perl doc. Everything's readable; code examples are nicely highlighted in grey boxes with monospaced font. It's all built automatically by programs, although I sure don't know how much of the programming comes with perl and how much is custom wizardry on the part of the search.perl.org folks. I do know that perldoc.com has an equally reliable and wonderful interface to the docs; we live in good times indeed.

Think how much work had to be done to get all this to work. Someone painstakingly fixed all that POD conversion code. Someone painstakingly figured out all the issues that had to be done to make those links work. And all that work doesn't even hold a candle to all the work that had to be done to make search.cpan.org work, or even to keep CPAN itself running.

I couldn't even begin to track down all the people I should thank for this, but if you're reading this and you played a part, no matter how small, know that I'm grateful. And if you're reading this and you didn't play a part, think how grateful you should be, too.


Not so easy...

lbt on 2003-12-08T22:18:49

Don't kid yourself :)

Coming back to perl after a loooong break I wanted to get myself some local html of my pod - I know, I know, I'm just a crazy dude who wants to use this latest greatest fad (surely that's all html is to the perldoc folk!)

perldoc perldoc /html -> nothing useful
perldoc -q html - nothing useful

perldoc perl2html -> aha!!

perldoc perlpod ->
  "Translators are available for converting Pod to various formats like plain text, HTML"

$pod2html --recurse --htmlroot=/perl --infile=/usr/lib/perl5/ --outfile=/www/perl/
/usr/bin/pod2html: cannot open /www/perl/ file for output: Is a directory

$ pod2html --recurse --htmlroot=/perl --infile=/usr/lib/perl5/ --outfile=/www/perl/index.html
/usr/bin/pod2html: no title for /usr/lib/perl5/.

perldoc perl2html
says "Converts files from pod format (see perlpod) to HTML format."

No shit - ONE AT A TIME??? !!!!

CPAN may be OK - but perldoc sure ain't !!!

(feeling pretty pissed after wasting *far* too much time trying to read the bloody docs!)