====== Introduction ======
This is a scratchpad for developing our gameplan for moving PEARDoc to Docbook5. Although one person can do *much* of the raw conversion, developing a plan and communicating it so whomever is interested can jump in and help would be a good idea.

This is an extension of the discussion started on the [[http://www.nabble.com/moving-peardoc-to-PhD-tf4879158.html|PEAR-DOC mailing list]]

Please read the [[http://www.docbook.org/docs/howto/#convert4to5|docbook 4 to 5 conversion documentation]] to get an idea of what is involved.

Interested people: Arnaud, Brett, Christian, Hannes, Philip, Mark + YOU

===== TODO =====
Here is my best guess at a list of what needs to be done in detail (please help me correct this, and for action items, please give some idea of the actual commands we need to run and tools required):
  - <del>Move PECL SPPLUS docs to phpdoc ([http://news.php.net/php.doc/969378514])</del> - done, Brett/Hannes
  - <del>Build an apache redirect for the PECL docs to their correct place in the php manual</del> - done, helgi
  - <del>Remove PECL docs from peardoc</del> - done, Mark
  - <del>Convert peardoc to Docbook5 - see conversion script below</del> - done, cweiske
    - <del>Create a branch in peardoc to do the conversion, we can merge back to HEAD when complete</del> - done, cweiske
    - <del>Handling the translations needs to be taken into account in some way</del> - done, cweiske
    - <del>Cloak entities so we don't lose them [http://docbook.svn.sourceforge.net/viewvc/docbook/trunk/contrib/tools/cloak/cloak?view=markup]</del> - done, cweiske
    - <del>Convert files to Docbook5 using db4-upgrade.xsl</del> - done, cweiske
    - <del>Uncloak the files to get entities back in</del> - done, cweiske
  - <del>Validate all the docs</del> - done, cweiske
  - <del>Get [http://wiki.php.net/doc/phd PhD] running on the files</del> - done, cweiske


==== Items which I don't know where to place: ====
  - <del>Decide on a move to a set/book structure, and where the sets/books are separated at (categories/collectives, or individual packages)</del> - done, cweiske
    - <del>what, semantically is involved in this - docbook reference</del> - done, cweiske
  - Examine the OO Skeletons developed for phpdoc
    - Book structure [http://doc.php.net/wiki/skeletons]
    - OO Skeleton [http://doc.php.net/wiki/skeletons/oo]
  - <del>move PEARDoc to Book structure?</del> - done, cweiske
  - move relevant pages to an OO skeleton..?
  - bleed
  - sweat

===== Conversion Script =====
This is a start at a conversion script, which will handle almost all of step 4 above.

==== Execution examples ====


Convert all files
<code>./peardoc_conversion.sh</code>

Convert one file
<code>./peardoc_conversion.sh peardoc/en/chapters/installation/shared.xml</code>

Code can be found in http://cvs.php.net/viewvc.cgi/peardoc/phd-db5-conversion/

===== Conversion problems =====
When I ran the script above on peardoc/en/ I ran into some problems with the following files.

The majority of issues are <!DOCTYPE declarations which are not cloaked correctly...? And files that do not have a singular root node (xml requirement).
  * <del>peardoc/en/chapters/faq/documentation.xml</del> fixed, cdata
  * <del>peardoc/en/chapters/installation/shared.xml</del> move info on manually installing into separate file
  * <del>peardoc/en/guide/newmaint/first-package-tips.xml</del> removed, empty file
  * <del>peardoc/en/package/gtk2/gtk2-indexedcombobox/glade.xml</del> fixed, cdata
  * <del>peardoc/en/package/pear/pear-info/pear-info/getstylesheet.xml</del> fixed, cdata
  * <del>peardoc/en/package/php/phpunit/testcase.xml</del> remove entities to missing content, file isn't used anyways
  * <del>peardoc/en/package/system/system-procwatch/system-procwatch-config.xml</del> move entities to parent section
  * <del>peardoc/en/package/system/system-procwatch/system-procwatch-parser.xml</del> move entities to parent section
  * <del>peardoc/en/package/system/system-procwatch/system-procwatch.xml</del> move entities to parent section
  * <del>peardoc/en/package/text/text-highlighter/intro.xml</del> fixed, no root node
  * <del>peardoc/en/package/xml/xml-beautifier/example.xml</del> fixed, cdata
  * <del>peardoc/en/package/xml/xml-serializer/xml-serializer/examples.xml</del> fixed, cdata


The following files in other translations have problems:
THE FOLLOWING FILES HAD ERRORS:
  * <del>peardoc/fr/chapters/installation/shared.xml</del>