debiandoc-sgml to docbook-xml conversion

==========================================================================
        (original concept) Philippe Batailler <pbatailler@teaser.fr>
        (original concept) Adam DiCarlo       <aph@debian.org>
        (ghost writer) Osamu Aoki             <osamu@debian.org>
                                                  Sat Dec 14 00:54:21 2002
==========================================================================

Table of contents

• Why convert?
• How to read this?
• Step by step guide.
• How tags are converted?

Why convert?

Because it is cool to be XML :)

How to read this?

Use table capable web browser if you are reading HTML.

• Mozilla
• Galeon
• links
• w3m
• ...

Step by step guide.

This is a rehashed tutorial given by Philippe Batailler's to Osamu Aoki through the private e-mails in 2002.

In order to convert debiandoc-sgml into docbook-xml, following steps needs to be taken:

1. Install debiandoc2dbxml
2. Make source file compatible with script manually

   Due to some conversion script limitations, if you experience problems converting files, please consider the following source touch-up rules presented below, although script might have fixed some of the issues already (it will not harm).

   • Adjust SGML header lines (first few lines of the file)

     If foo.sgml includes many files (subset of dtd), first line must end with [ as:

     <!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
     ... content
     ]>
     

     Here splitting each start and end of these section will fail.

     If foo.sgml is a single file, header is:

     <!DOCTYPE debiandoc  PUBLIC "-//DebianDoc//DTD DebianDoc//EN">
     

   • Keep some conditionals within one line.

     <[%bar;[
     

   • Keep some some tags within one line.

     <chapt>...</chapt>
     <appendix>...</appendix>
     <sect>...</sect>
     <sect1>...</sect1>
     <sect2>...</sect2>
     

   • Remove some comment

     <!-- ... -->
     

     This is to avoid script to malfunction by " ]> " in the comment.

   • make attribute such as "id" a single token.

     wrong:   <book id="foo bar">
     correct: <book id="foo_bar">
     

3. Normalize SGML to XML compatible format (debiandoc-tidy)

   $ debiandoc-tidy foo.sgml
   $ debiandoc-tidy -e bar.ent
   

4. Convert SGML tags into XML tags (debiandoc2dbxml)

   If foo.sgml is smaller article in a single file without subset of dtd.

   $ debiandoc2dbxml -a path/to/foo.sgml
   

   If foo.sgml is larger book in a single file without subset of dtd.

   $ debiandoc2dbxml -b path/to/foo.sgml
   

   If foo.sgml is larger book with many included files (subset of dtd).

   $ debiandoc2dbxml -s -b path/to/foo.sgml
   

   Now we have got a large single foo.xml

   If foo.sgml is larger book with many included files (subset of dtd). To create split file output in directory path/to/locale, you should use the option -S and the option -l (locale = en, fr, es...)

   $ debiandoc2dbxml -S -s -b -l fr path/to/foo.sgml
   

   Now we have got a foo.xml in path/to/ with many chunks of files under path/to/fr/

   For debugging, use "-k" to keep intermediate files and use "-t" to trace shell activities.

5. Test it with emacs and psgml, or nsgmls:

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

6. Format source for readability

   In order to make source more readable, some reformatting may be good idea. For example, to add newline after </listitem>:

   $ perl -i -p -e's,</listitem>,</listitem>\n,g' foo.xml
   

7. Building output

   There are few strategies to build output.

   Stylesheet	Back end
   DSSSL	jade and jadetex
   CSS	mozilla?
   XSL	passivetex?

   Needs more documentation for creating files (plain text, multi-file, HTML, PS, PDF).

How tags are converted?

Here is a conversion list of tags from debiandoc-sgml to dookbook-xml. Each column means as follows:

• "debiandoc-sgml tag" are the tags used in original documents.
• "converted docbook-xml tag" are the tags converted programatically by XLST.
• "alternative docbook-xml tag" are the alternative tags which may be used in places by editing dookbook-xml source later by the human.

Here *HTML* entries above is not real tags in debiandoc-sgml but tags of the missing feature to create corresponding HTML tags.

file splitting is has funny bug which create titletoc.xml in scripts directory. Also, multi file XML requires entries like:

<!ENTITY titletoc       SYSTEM "en/titletoc.sgml">