Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

jdavidb (1361)

jdavidb
  (email not shown publicly)
http://voiceofjohn.blogspot.com/

J. David Blackstone has a Bachelor of Science in Computer Science and Engineering and nine years of experience at a wireless telecommunications company, where he learned Perl and never looked back. J. David has an advantage in that he works really hard, he has a passion for writing good software, and he knows many of the world's best Perl programmers.

Journal of jdavidb (1361)

Friday November 21, 2003
12:46 AM

Three cheers

[ #15917 ]

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.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • 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=