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
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
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):
Move PECL SPPLUS docs to phpdoc ([http://news.php.net/php.doc/969378514])- done, Brett/Hannes Build an apache redirect for the PECL docs to their correct place in the php manual- done, helgi Remove PECL docs from peardoc- done, Mark Convert peardoc to Docbook5 - see conversion script below- done, cweiske Create a branch in peardoc to do the conversion, we can merge back to HEAD when complete- done, cweiske Handling the translations needs to be taken into account in some way- done, cweiske Cloak entities so we don't lose them [http://docbook.svn.sourceforge.net/viewvc/docbook/trunk/contrib/tools/cloak/cloak?view=markup]- done, cweiske Convert files to Docbook5 using db4-upgrade.xsl- done, cweiske Uncloak the files to get entities back in- done, cweiske
Validate all the docs- done, cweiske Get [http://wiki.php.net/doc/phd PhD] running on the files- done, cweiske
Items which I don't know where to place:
Decide on a move to a set/book structure, and where the sets/books are separated at (categories/collectives, or individual packages)- done, cweiske what, semantically is involved in this - docbook reference- done, cweiske
- Examine the OO Skeletons developed for phpdoc
move PEARDoc to Book structure?- done, cweiske
- move relevant pages to an OO skeleton..?
This is a start at a conversion script, which will handle almost all of step 4 above.
Convert all files
Convert one file
Code can be found in http://cvs.php.net/viewvc.cgi/peardoc/phd-db5-conversion/
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.xmlfixed, cdata peardoc/en/chapters/installation/shared.xmlmove info on manually installing into separate file peardoc/en/guide/newmaint/first-package-tips.xmlremoved, empty file peardoc/en/package/gtk2/gtk2-indexedcombobox/glade.xmlfixed, cdata peardoc/en/package/pear/pear-info/pear-info/getstylesheet.xmlfixed, cdata peardoc/en/package/php/phpunit/testcase.xmlremove entities to missing content, file isn't used anyways peardoc/en/package/system/system-procwatch/system-procwatch-config.xmlmove entities to parent section peardoc/en/package/system/system-procwatch/system-procwatch-parser.xmlmove entities to parent section peardoc/en/package/system/system-procwatch/system-procwatch.xmlmove entities to parent section peardoc/en/package/text/text-highlighter/intro.xmlfixed, no root node peardoc/en/package/xml/xml-beautifier/example.xmlfixed, cdata peardoc/en/package/xml/xml-serializer/xml-serializer/examples.xmlfixed, cdata
The following files in other translations have problems: THE FOLLOWING FILES HAD ERRORS: