PEARDocMoveToDocbook5

From PEAR Wiki

Contents 1 Intro 2 TODO 3 Conversion Script 4 Conversion problems

[edit] Intro

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 PEAR-DOC mailing list [1]

Please read the docbook 4 to 5 conversion documentation to get an idea of what is involved.

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

[edit] 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):

1. Move PECL SPPLUS docs to phpdoc ([2]) - done, Brett/Hannes
2. Build an apache redirect for the PECL docs to their correct place in the php manual - done, helgi
3. Remove PECL docs from peardoc - done, Mark
4. Convert peardoc to Docbook5 - see conversion script below
   1. Create a branch in peardoc to do the conversion, we can merge back to HEAD when complete
   2. Handling the translations needs to be taken into account in some way
   3. Cloak entities so we don't lose them [3]
   4. Convert files to Docbook5 using db4-upgrade.xsl
   5. Uncloak the files to get entities back in
5. Validate all the docs
6. Get PhD running on the files

Items which I don't know where to place:

1. Decide on a move to a set/book structure, and where the sets/books are separated at (categories/collectives, or individual packages)
   1. what, semantically is involved in this - docbook reference
2. Examine the OO Skeletons developed for phpdoc
   1. Book structure [4]
   2. OO Skeleton [5]
3. move PEARDoc to Book structure?
4. move relevant pages to an OO skeleton..?
5. bleed
6. sweat

[edit] Conversion Script

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

Execution examples:

Convert all files $ ./peardoc_conversion.sh

Convert one file $ ./peardoc_conversion.sh peardoc/en/chapters/installation/shared.xml

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

[edit] 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).

• peardoc/en/chapters/faq/documentation.xml fixed, cdata
• peardoc/en/chapters/installation/shared.xml move info on manually installing into separate file
• peardoc/en/guide/newmaint/first-package-tips.xml removed, empty file
• peardoc/en/package/gtk2/gtk2-indexedcombobox/glade.xml fixed, cdata
• peardoc/en/package/pear/pear-info/pear-info/getstylesheet.xml fixed, cdata
• peardoc/en/package/php/phpunit/testcase.xml remove entities to missing content, file isn't used anyways
• peardoc/en/package/system/system-procwatch/system-procwatch-config.xml move entities to parent section
• peardoc/en/package/system/system-procwatch/system-procwatch-parser.xml move entities to parent section
• peardoc/en/package/system/system-procwatch/system-procwatch.xml move entities to parent section
• peardoc/en/package/text/text-highlighter/intro.xml fixed, no root node
• peardoc/en/package/xml/xml-beautifier/example.xml fixed, cdata
• peardoc/en/package/xml/xml-serializer/xml-serializer/examples.xml fixed, cdata

The following files in other translations have problems: THE FOLLOWING FILES HAD ERRORS:

• peardoc/fr/chapters/installation/shared.xml