How Perl Documentation Could Look Like

Yes this is in a way my 5th grant report in a row, but even for Perl 5 people that might get insightful and even useful.

As I prepared a piece for the Perlzeitung which will not happen, i interviewed several people - some names you know for sure - about the current state of the core documents. Yes there slowly improving, the d did IMO good stuff, the new ooptut is good but there needs to be much more done. And instead of dropping here a blob of text, just have a look (Appendix A is really impressive). Its hardly started but I'm sure you get the idea (short but comprehencive explanation of everything + 7 different appendices giving alternative entry point to find what you need). Please just think about. The dream needs the hands of many.

Because the really exciting thing is... the tablets moved from socialtext wiki. They moved to their own URL (link above) they moved to a different format (markdown). The HTML you see on the site is generated by pandoc, which proofs python can be useful, because we can create a PDF or other ebook formats with a snap of a finger. And I can write the texts in Kephra which is by far superior to any HTML-widget.

Last night I converted several hunderts links and anchors, which lets me announce proudly that the conversion to that new format is done. This of course was only possible due to the idea, help and initial generator script done by (John M. Gabriele)++ and some admin work by (Moritz Lenz)++.

BTW they both also conspired to create a new Perl 6 wiki. Gitit is powered by (you guess it) and understands almost any modern markup language - no more pain by socialext!


Hi Herbert,
last time I use Kephra very often,
it's lite, easy and work, thanks,
yes is very well-looking documentation

and also questions, why you didn't put your project
to github ?

I really like it because it is easy to commit through a browser
and, therefore, it is easy to add something useful.


you mentioned generating a PDF (or other ebook format). I've looked @ the site but didn't find a link to such a doc. Is this something planned ?


I'd like to point out that pandoc is written in haskell, not python.. Unless you meant something else with that comment?

I've also written a patch to make it output POD (well PseudoPod anyways).. I should go ask the pandoc guys to pull it in..

So you are replacing POD by pandoc, that's what you are propagating?

How much support and confirmation do you find for your approach?

Pandoc is not a format, it's a parser - basically markdown to anything and back - written in Haskell. I guess it's as good as its test data.

Leave a comment

About lichtkind

user-pic Kephra, Articles, Books, Perl, Programming