[TYPO3-doc] Converting DocBook4 to DocBook5

[Thomas Schraitle]

Hi François,


Tuesday 28 December 2010

> A new question about DocBook: are there utilities for migrating v4 files
> to v5? Is it possible at all?

Sure, it's just a matter of transformation. The markup changes are explained 
in [1]. It's not that big, the important changes are the new DocBook 
namespace, the renaming of *info elements to info, id -> xml:id, lang -> 
xml:lang, and XLinks.

If you have valid DocBook 4 files this shouldn't be a problem. The DocBook SVN 
repository contains a XSLT stylesheet[2] that does this migration. I did it 
with my 2nd edition of my book (the 1st edition was written in DocBook 4) and 
converted it to v5. It was done without any trouble, although I've slightly 
modified the above stylesheet. 
I would suggest to test it and validate the result file. If you encounter any 
problems, it's just a matter of a new XSLT template to fix the issue.

However, keep in mind, entities are not preserved. So if you have some 
entities in your v4 files like &product; etc. they will not show up as 
&product; in your v5 files anymore. Entities are resolved _before_ the 
transformation takes place (so you end up as "TYPO3", for example). If 
entities are an issue for you, look at [3] for more information.


> [...]
> The question is then: should be go ahead and
> produce v4 DocBook which we can then safely "upgrade" to v5 with
> existing tools or should we modify the existing script to produce v5
> DocBook straightaway?

If you are only interested in DocBook 5 as your main documentation format, I 
would go straight ahead to producing v5. Why create v4 when you write in v5 
anyway? The only reason why creating v4 would make sense are some legacy 
tools. 

Depending on the migration process, there could be some "cleanup" step 
necessary. For example, to improve consistency, introduce some styleguide 
issues, or some remarks for your authors (as a kind of FIXME).


Cheers,
  Tom

--- References:
[1] http://www.docbook.org/docs/howto/#changes
[2] https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/
relaxng/tools/db4-upgrade.xsl
[3] http://www.docbook.org/docs/howto/#convert4to5