If you've got real amounts of content in DocBook, migrating to DocBook V5.0 is going to require effort. There's going to be a transitional period when tools support lags behind and support for DocBook V5.0 is considerably less mature than support for V4.x. Support for the DocBook V4.x DTDs isn't going away any time soon, so you don't have to migrate to DocBook V5.0. What everyone needs is experience. We need real world experience with DocBook V5.0 during its public testing phase and with the migration path outlined in this document. Even if you don't have any plans to migrate your production systems to DocBook V5.0 next year, you can contribute in an important and significant way to the future of DocBook by testing the V5.0 schemas and the conversion tools described herein with your real, production content. Please report the problems you encounter. Every failure during the testing period is worth a thousand successes later on.

The DocBook V5.0 schema ships with an XSLT 1.0 stylesheet that is designed to transform valid DocBook V4.x documents to valid DocBook V5.0 documents. To convert your document, doc.xml in the examples below, follow these steps: Check the validity of your DocBook XML V4.x document. The conversion tool assumes that the input document is valid. If the input document contains markup errors, the results will be unpredictable at best. Transform doc.xml to newdoc.xml with the db4-upgrade.xsl stylesheet included in the DocBook V5.0 distribution that you are using. Check the validity of your DocBook XML V5.0 document against the DocBook V5.0 RELAX NG grammar. In the vast majority of cases, the resulting document should be valid and your conversion process is finished. If the document is not valid, please report the problem. (Over time, we'll have more experience with the sorts of things that can go wrong and we'll update this document to reflect that experience.)

Using XSLT to transform existing documents to DocBook V5.0 has one potential disadvantage: it removes all entity references from your document. If preserving entities is an important aspect of your production work flow, you will have to engage in a semi-manual process to preserve them. Open your existing document using your favorite editing tool. You must use a tool that is not XML-aware, or one that allows you to edit markup “in the raw”. Replace all occurrences of the entity references that you want to preserve with some unique string. For example, if you want to preserve “&Product;” references, you could replace them all with “[[[Product]]]” (assuming that the string “[[[Product]]]” doesn't occur anywhere else in your document). Copy the document type declaration off of your document and save it some place. The document type declaration is everything from “<!DOCTYPE” to the closing “]>”. Perform the conversion described in . Open the new document using your favorite editing tool. Replace all occurrences of the unique string you used to save the entity references with the corresponding entity references. Paste the document type declaration that you saved onto the top of your new document. Remove the external identifier (the PUBLIC and/or SYSTEM keywords) from the document type declaration. A document that begins: ]>]]> is perfectly well-formed. If you don't remove the references to the DTD, then your parser will likely try to validate against DocBook V4.0 and that's not going to work. Alternatively, you could refer to the DocBook V5.0 DTD.

External parsed entities, entities which load part of a document from another file, are a special case. These can often be replaced with XInclude elements. The Perl script db4-entities.pl, also included in the DocBook V5.0 distribution attempts to perform this replacement for you. To use the script, perform the following steps: Process your document with db4-entities.pl. The script expects a single filename and prints the XInclude version on standard output. Process the XInclude version as described in .