Hi all As many of you know I was accepted into the "Google Summer of Code" program and was supposed to work on Livedocs during the summer.
After sometime poking around in Livedocs and trying to add "module/theme/format" support to it (making it possible to render not only phpweb, but also pdf/chm/manpages/whatever) I simply gave up. The design of Livedocs is simply not what phpdoc needs, not to mention the fact that phpdoc has a lot of "gold" in its sources (XML files containing two root elements, XML files containing nothing but "include entities" and a lot of other wacky things) which Livedocs is simply incapable of rendering. I did my very best to refactor the source and dirty-workaround its design limitation but failed, miserably. It became very clear to me that Livedocs was simply yet another rendering system to maintain on top of docbook-xsl and docbook-dsssssl. It wouldn't even work properly, ever. Just something to have for the fun of it. What did I do? Created a "one-ring-rules-them-all" rendering system, PhD. PhD ([PH]P based [D]ocbook rendering system) currently is capable of producing phpweb, chunked html and bightml - all in one run - in less than 3minutes, using ~20mb ram (peaks at 22mb). I'm not kidding. It takes *less* than 3minutes (2min 40sec average (while using my laptop)) to generate all three on my Dell Precision M70 Laptop. The current Docbook-XSL system takes 60-90minutes rendering single format (taking over 500mb ram). 3hours versus 3minutes! Livedocs takes somewhere around the hour, too, but is only capable of building phpweb (chunked html can be done with minor changes, but not in the same run). Furthermore, PhD is a generic Docbook renderer and can be used on any Docbook sources. With a minor work you can create a customized theme to overwrite (or extending) the default output. For those who ever worked with Livedocs "almost XPath" formatting rules will find the "notXPath" rules very familiar (lets face it, Livedocs "almost XPath" was brilliant) and shouldn't be in any troubles adding new rules. Those who ever worked with Docbook-XSL will also find some things familiar. PhD is the future. PhD is the promised land! :P The source can be found in the `phd` cvs module on cvs.php.net. Currently you need to patch PHP to be able to run it (see: http://news.php.net/php.internals/31583) but that requirement will (of course) be removed if the patch doesn't make it into the next PHP release. My build config can be found at http://home.oslo.nith.no/~maghan/phpdoc/phd/config.phps Put it into PhDs root dir (same directory as build.php) as config.php. You'll need to change the 'xml_root' to point to your phpdoc XML root. To run it, execute `php build.php` and fetch a cup of coffee. It'll be done by the time you get back. Using my config you'll get a "php" directory (phpweb output), "html" directory (chunked html output) and bightml.html file (the fatass whole manual in single file). There are still bunch of elements unimplemented but the most used, and important, ones are there. The thousands of "No mapper found for format_xx" warnings can be ignored, they are just there to let you know that particular element hasn't been implemented yet. If you don't want them then either comment out line 152 in formats/xhtml.php (trigger_error("No mapper found for '{$func}'", E_USER_WARNING);) or change your error reporting level accordingly. http://docs.php.net is running PhD so you can have a look at the current output if you don't want to build it yourself. (Yes. The downloadable docs on http://docs.php.net/download-docs.php were generated by PhD - even the CHM file (still highly experimental and not really implemented yet)). Apparently you read the whole post, I appreciate it :D With love, Hannes :P
