Re: moving peardoc to PhD

On Nov 27, 2007 2:21 AM, Greg Beaver <[email protected]> wrote:
> Hi Hannes and pear doc peoples,
>
> Now that PhD is powering php.net's docs, I thought it might be a good
> time to ask what we need to do to ready PEAR's outdated doc system for a
> move to PhD?  On IRC we had spoken and you mentioned you might be
> interested in writing the initial template for peardoc, but we won't
> hold you to it unless you say so officially :).
>
> PEAR is about to make a major transition for PEAR2, and so it would be
> great to get this change in the works for moving to books for each
> package as you had described.

Without having checked, I suspect a PEAR template to PhD would be very
similar to the phpdoc templates - and therefore extremely easy to do.
However, there is a catch: PhD only works with Docbook5.

Upgrading to DB5 is in itself very easy to do, pretty much the only
difference is that DB5 elements are now namespaced - and few elements
have been removed/renamed[1].

To spice things up a bit:
phpdoc is currently experimenting with a set/book structure[2][3],
which means every extension is independent and can be
built/distributed separately - yet still being able to link between
extensions. The new structure also makes it easier to add additional
content, such as advanced examples[4], tutorials, best practice
chapters and detailed information about the extension[5].
Furthermore we have drafted new skeletons[6] for object orianted
extensions[7] which is definitely something PEAR should consider
adhering too.

So, the bottom line: We could probably get peardoc built using PhD
within a week after upgrading to DB5 - but I really recommend that
peardoc follows in its sisters, phpdoc, footsteps and upgrade the
markup to a set/book structure using real OO markup for all the
classes.
Its gonna be sweat & blood upgrading all the docs, but if lots of
hands help out...

-Hannes

[1] http://www.docbook.org/docs/howto/#changes-renamed
[2] http://docs.php.net/manual/en/index.php
[3] http://doc.php.net/wiki/skeletons
[4] http://docs.php.net/manual/en/objaggregation.examples.php
[5] http://docs.php.net/manual/en/regexp.reference.php
[6] http://doc.php.net/wiki/skeletons/oo
[7] http://docs.php.net/manual/en/class.arrayiterator.php