[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ A ] [ B ] [ next ]

DebianDoc-SGML Manual
Appendix B - Conversion to XML

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.

This appendix was written by Osamu Aoki (GPL2) in 2005.

B.1 Basic conversion method

No particular preparation of debiandoc-sgml SGML source is needed to use the conversion tool debiandoc2xml . See debiandoc2xml(1).

To make a single XML file from valid debiandoc-sgml source, issue the following commands:

     $ cd path/to/sgml-source-tree/
     $ debiandoc2xml -1 foo.sgml
     $ cd foo.xml/
     $ mv index.xml foo.xml

The generated XML file is named as index.xml and let's manually rename as foo.xml for this time.

B.2 Advanced conversion methods

In order to make generated file manageable, you may want to have them split into separate files for each chapter and preserve external ENTITY definitions as separate file. They are quite easy.

B.2.1 Split XML file output

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

B.2.2 Preserving external ENTITY definitions

Some SGML sources use external file to manage common information across the documentation source and maintain good coherence. Creating this ENTITY definitions in a separate file named default.ent is common practice. It contains entries such as:

     <!ENTITY debianhome     "http://www.debian.org/">

You probably want to preserve these remote definition after XML conversion. Following describes how to do this.

In order to simplify this conversion, you need to simplify default.ent by removing definition for conditional switching such as:

     <!ENTITY % q-ref   "IGNORE">

and

     <![%lang-fr;[
     <!ENTITY full-title "Guide de référence pour Debian">
     <!ENTITY p-debian-reference "debian-reference-fr">
     ]]>

Then, you tweak default.ent file (assuming files are normally formatted) as follows:

     $ mv default.ent default.ent.orig
     $ egrep "<\![[:space:]]*ENTITY[[:SPACE:]]+" <default.ent.orig | \
       perl -p -e \
          's/<\!\s*ENTITY\s+([-\w]+)\s.*$/<\!ENTITY $1 "@#@#@#$1#@#@#@">/' \
          > default.ent

This will create alternative entries, which generate reference markers such as:

     <!ENTITY debianhome "@#@#@#debianhome#@#@#@">

Then use this alternative default.ent file for XML conversion. (You may still modify this to include missing required definitions such as lines containing "%" in the original default.ent file.)

For each generated XML files with this alternative default.ent file, you recover remote references by converting markers with:

     $ for i in *.xml ; do \
       perl -p -i -e 's/@#@#@#$([\w]+)#@#@#@/\&$1;/g' $i ; \
       done

You need to add specification of including original default.ent in the header area of foo.xml XML file at the top again as:

     <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
         "/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [
     
     <!ENTITY % default  SYSTEM "default.ent">  %default;
     
     <!-- more lines here -->
     
     ]>

B.3 Testing generated XML file(s)

You can test the generated XML file with Emacs and psgml, or nsgmls:

     $ nsgmls -s /usr/share/sgml/declaration/xml.decl foo.xml

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ A ] [ B ] [ next ]

DebianDoc-SGML Manual