Different View on Documentation
The actual intention behind perlybook.org was to make module documentation from CPAN more portable. Ebook-Readers today are designed for reading-pleasure everywhere - in your garden at daylight or in your bed at night... and this works so far.
But recently I noticed an effect which could also be of interest for "normal" Perl programmers who just work at a the computer and also prefer reading the docs there.
I always found it a bit complicated to read documentation on CPAN. If the author does not give a lot of love to the documentation it's even complicate to browse through all the docs of each module, since there is no auto-generated TOC over the complete distribution (only on inside each modules doc).
But there are even more issues.
See how the documentation of EBook::MOBI looks like on my screen (1920x1080):
This is what you see first. It is a horrible layout, isn't it? You have so much unused space and the TOC is so big that you don't see what you are probably most interested in... a small description and the example in the SYNOPSIS.
MetaCPAN, which is great and always used by me, has basically the same problem. The markup is more colorful but the two issues mentioned stay the same:
Now see how this looks like when you go to perlybook.org and download the docs in the EPUB format. (You should have the Firefox plugin "EPUBReader" installed to have the same view as posted here)
I think there is a great advantage here. First of all you see links (ebook internal) for all the modules containing documentation listed at the left side. Like that you know at the first glance what else there is to read, even if the author did not take care of it. Secondly, the layout is much more efficient. You can see the example directly and scan much more text at once.
There are still downsides... e.g. the POD links point to CPAN instead inside the ebook. Also long lines of code get wrapped, which might confuse. But I thought it might be interesting for some of you guys. Maybe it is already useful now as is or somebody gets inspired by the issues mentioned.
---
Boris Däppen
This is about perlybook, a webservice that lets you create Perl module documentation in ebook formats.
This is fantastic work that I'm really happy to come across right now. I too share your frustrations with documentation on both CPAN and Metacpan (not to mention perldoc) and perlybook shocked me with how incredibly useful it is. Thanks for your work on it. I'm a big advocate now. :)