More gifts
November 29th 2007 01:09 am
All that work I was doing to add parallel updating and building to kdesvn-build gave me a great appreciation for one thing that Perl does right: copious documentation, even if you need to use a special program to view it (perldoc, which man-page-ifies it).
What I really wanted was a KIOSlave interface to perldoc that way I could view the documentation nicely hyperlinked in Konqueror. The KDevelop guys already had a kio_perldoc, but it wasn’t really too great. It simply dumped the output of perldoc more or less straight to konqueror, which misrendered it since it wasn’t HTML. It could also output plain text but that was HTML-ified using blockquote instead of pre which caused it to still look weird.
It was that way mainly because there’s no good way to export HTML from a perldoc file. Perl includes a pod2html but let’s just say it hasn’t kept up with the times too well. Plus it’s very hard to convert the hyperlinks produced by pod2html into something that perldoc would be able to redirect to itself, which defeated the purpose of having hyperlinks in the first place.
I eventually decided to do a little Perl magic to handle the conversion from .pod (which perldoc would output) to html that wasn’t crap. It took a bit of searching on CPAN to weed out the POD->HTML converters which either had way too many dependencies or didn’t produce suitable output. I eventually settled on Pod::HtmlEasy, a useful and customizable Pod->HTML converter that didn’t have too many dependencies and was suitable for standalone use.
Some merging of files and removal of unnecessary dependencies later, and I had a script which would run perldoc for me and automatically convert its output to HTML. All my KIOSlave had to do was call the script and dump its output straight to the receiving end.
The actual handling of that is probably more complicated than necessary. I think I will use popen() in the future just like every other similar KIOSlave instead of handling the children myself. But, it works pretty well:
It handles URIs of the form perldoc:/Net::HTTP to get module information, perldoc:/functions/select to look up documentation on Perl functions (like perldoc -f) and perldoc:/faq/search_terms to looks for your search terms in the perlfaqs (like perldoc -q). These URIs were all pioneered by the KDevelop KIOSlave.
The next step would probably be to port this to KDE 4 and coordinate with the KDevelop developers to either integrate this back into KDevelop or (my preference) get this into kdesdk since this is useful for many more developers than just KDevelop users. Also the generated HTML looks very similar to perl.org’s perldoc resources, I need to get it looking more like the kde.org website family (CSS help appreciated :)
You can grab it from my dumping ground. Although it is for KDE 3, you still need CMake to build it, as there’s no way I’m wasting bandwidth on autotools. :)
Thanks for this. It works great and was easy to install.
Hi, as one of the KDevelop developers I’d say bring the KDE4 version straight into kdesdk when its ready. KDevelop4 won’t have any perl support out of the box, so there’s no reason to keep a perldoc ioslave in kdevelop.
The following patch was sent in by Bruce Eckel to fix formatting of some bulleted lists which had ‘*’ everywhere. It will be in the next kio_perldoc, or you can apply it to your pod2html.pl in the source directory and then reinstall.
kde-svn $ ~/projects/kio_perldoc $ svn diff -r4:5 Index: pod2html.pl =================================================================== --- pod2html.pl (revision 4) +++ pod2html.pl (revision 5) @@ -1450,6 +1450,7 @@ sub evt_on_item { my $this = shift; my ( $txt, $a_name ) = @_; + return qq{<li>$NL} if $txt eq '*'; return qq{<li><a name='$a_name'></a><b>$txt</b></li>$NL}; }You rule, very very hard. I almost did this myself months ago, but libtool made me stop… Too annoying developing extensions for kde when you have to have stuff registered with libtool and stuff.
It works great, thank you.