<appendix id="xml">Conversion to XML
<p>
Now debiandoc-sgml package offers conversion to Docbook
XML format for its user to smoothly migrate to the newer
well maintained tool set called Docbook XML.
<p>
This appendix was written by Osamu Aoki (GPL2) in 2005.

<sect>Basic conversion method
<p>
No particular preparation of debiandoc-sgml SGML source is needed 
to use the conversion tool <prgn>debiandoc2xml</prgn> .
See <manref section="1" name="debiandoc2xml">.
</p>
<p>
To make a single XML file from valid debiandoc-sgml source, issue 
the following commands:
<example>
$ cd path/to/sgml-source-tree/
$ debiandoc2xml -1 foo.sgml
$ cd foo.xml/
$ mv index.xml foo.xml
</example></p>
<p>
The generated XML file is named as <file>index.xml</file> and let's
manually rename as <file>foo.xml</file> for this time.
</p>

<sect>Advanced conversion methods
<p>
In order to make generated file manageable, you may want to have them
split into separate files for each chapter and preserve external
<tt>ENTITY</tt> definitions as separate file.  They are quite easy.

<sect1>Split XML file output
<p>
When issuing <prgn>debiandoc2xml</prgn> command, just issue it without
<tt>-1</tt> option in the above example.  You get XML files with file 
names matching <tt>id</tt> values of <tt>chapt</tt> tags.
The top page is <file>index.xml</file> and it will contain file 
inclusion directions.
</p>

<sect1>Preserving external <tt>ENTITY</tt> definitions
<p>
Some SGML sources use external file to manage common information 
across the documentation source and maintain good coherence.  
Creating this <tt>ENTITY</tt> definitions in a separate file named 
<file>default.ent</file> is common practice.  It contains entries 
such as:
<example>
&lt;!ENTITY debianhome     "http://www.debian.org/"&gt;
</example>
You probably want to preserve these remote definition after XML 
conversion. Following describes how to do this.
<p>
In order to simplify this conversion, you need to simplify 
<file>default.ent</file> by removing definition for conditional
switching such as:
<example>
&lt;!ENTITY % q-ref   "IGNORE"&gt;
</example>
and
<example>
&lt;![%lang-fr;[
&lt;!ENTITY full-title "Guide de référence pour Debian"&gt;
&lt;!ENTITY p-debian-reference "debian-reference-fr"&gt;
]]&gt;
</example>
<p>
Then, you tweak 
<file>default.ent</file> file (assuming files are normally formatted)
as follows:
<example>
$ mv default.ent default.ent.orig
$ egrep "&lt;\![[:space:]]*ENTITY[[:SPACE:]]+" &lt;default.ent.orig | \
  perl -p -e \
     's/&lt;\!\s*ENTITY\s+([-\w]+)\s.*$/&lt;\!ENTITY $1 "@#@#@#$1#@#@#@"&gt;/' \
     &gt; default.ent
</example>
This will create alternative entries, which generate reference markers
such as:
<example>
&lt;!ENTITY debianhome "@#@#@#debianhome#@#@#@"&gt;
</example>
<p>
Then use this alternative <file>default.ent</file> file for 
XML conversion. (You may still modify this to include missing 
required definitions such as lines containing "%" in the original 
<file>default.ent</file> file.)
<p>
For each generated XML files with this alternative 
<file>default.ent</file> file, you recover remote references by 
converting markers with:
<example>
$ for i in *.xml ; do \
  perl -p -i -e 's/@#@#@#$([\w]+)#@#@#@/\&$1;/g' $i ; \
  done
</example>
You need to add specification of including  original 
<file>default.ent</file> in the header area of <file>foo.xml</file> 
XML file at the top again as:
<example>
&lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [

&lt;!ENTITY % default  SYSTEM "default.ent"&gt;  %default;

&lt;!-- more lines here --&gt;

]&gt;
</example>

<sect>Testing generated XML file(s)
<p>
You can test the generated XML file with Emacs and psgml, or nsgmls:
<example>
$ nsgmls -s /usr/share/sgml/declaration/xml.decl foo.xml
</example>

