PhD, the PHP Docbook Renderer, supports multiple output formats: XHTML, PDF and man pages. Yes, man pages. Simply install them via PEAR:
$ pear install doc.php.net/pman ... $ pman functionname ... $ pman classname.methodname
One thing missing in the man pages was syntax highlighted code, and yesterday while chatting with the #php.doc guys on EFnet, I decided to change that. I luckily found out that the troff format (base format used by man) supports color codes. Two minute later I had my own colored exemplary man page.
Now the smaller part of the problem was to get PhD generate syntax highlighted code in troff format. As mentioned earlier in this blog, PhD supports external syntax highlighters. My exemplary implementation was for GeSHi, so that was the first highlighter I looked at for troff code generation.
As I suspected does GeSHi support only HTML output. With the upcoming version 1.1.x (currently under heavy alpha-development in trunk), GeSHi supports renderers - just like PhD supports different output formats. So for starters I took the HTML renderer and began to modify it to become an ANSI color renderer that would display colored code to the shell.
Thanks to PEAR I was prepared to anything:
- HTML_CSS to parse the CSS code generated by the GeSHi language files back into useable structures and extract color information from it.
- Image_Color2 helped me to convert the different CSS color notations back into plain RGB.
- Console_Color does the dirty job of generating all the ANSI control codes.
The only thing left to do for me was writing a mapper from RGB values to the limited 9 colors supported by ANSI. It turned out that to be some simple bit-shifting operations did the job, and after an hour of hacking, I had my first colored code on the shell:
After showing my screenshot around #geshi on FreeNode, I got in contact with GeSHi's current maintainer, Benny Baumann. Shortly after, my renderer was in offical SVN!
Two more hours were spent in fine-tuning the code, making it support bold font-weights and improving the rendering speed by 300%.
Now seeing that GeSHi is actually capable of everything I need, the troff renderer will be the next step. Integration into PhD is a no-brainer, and thus we should soon have colored xml and php code in the php man pages.