In this new post to his blog Matthew Weier O'Phinney looks at the steps he took to convert over the documentation for the Zend Framework 2 from the DocBook 4 formatting over to DocBook 5. Included in the post is some of the (PHP and bash) code he used to make the switch.
Within the Zend Framework 2 repository, I recently performed a conversion from DocBook 4 to 5. [...] Interestingly, for DocBook5 being available in beta since 2005 and an official standard since 2009, there is very little material on migrating from DocBook 4 to 5.
Right from the start he came across a few problems with the included conversion process that're a part of the "db4-update.xsl" definitions. He has a list of eight steps he had to perform on the current DocBook 4 formatted documentation to make the conversion work smoothly including:
- Identify files containing entity declarations, and skip them.
- Run the XML file through the db4-upgrade.xsl stylesheet and restore XML entities from the previously placed markers
- Fix programlisting elements (replaces entities with original text and wraps in CDATA).
He details these steps in a few different sections talking about handling the entities, creating some helper scripts and how to put the two code parts together in a single bash script that can be run on the entire documentation set. If you're just looking for the code, you can find it on his github account.
