Transitionning from DocBook SGML to DocBook XML

[Daniel Veillard <veillard redhat com>]

  Okay since people are confused about some of the issues involved in
producing docs for the Gnome-2.0 release, here are a few things which should
help the people doing the docs:

   1/ subscribe to gnome-doc-list gnome org 
   2/ join #docs IRC channel on irc.gnome.org when you can
   3/ read the doc produced by Alexander Kirillov
      on how to process XML docs to generate HTML
      http://www.math.sunysb.edu/~kirillov/dbxml/index.html
      verify that your setup is proper as indicated

  To help in the transition there are at least basic tools to
help migrating from DocBook SGML to DocBook XML, I added a --sgml
option to xmllint (coming with libxml2), it will parse an SGML DocBook
entity and try to output a corresponding XML DocBook output. Example:

   glossary.example.1.sgm is one of the examples from DocBook SGML:

orchis:~/XML -> xmllint --sgml test/DocBook/glossary.example.1.sgm 
<?xml version="1.0"?>
<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
<glossary><title>Example Glossary</title><para>
This is not a real glossary, it's just an example.
</para><!-- ... --><glossdiv><title>E</title><glossentry id="xml"><glossterm>Extensible Markup Language</glossterm><acronym>XML</acronym><glossdef><para>Some reasonable definition here.</para><glossseealso otherterm="sgml"/></glossdef></glossentry></glossdiv><!-- ... --><glossdiv><title>S</title><glossentry><glossterm>SGML</glossterm><glosssee otherterm="sgml"/></glossentry><glossentry id="sgml"><glossterm>Standard Generalized
  Markup Language</glossterm><acronym>SGML</acronym><abbrev>ISO 8879:1986</abbrev><glossdef><para>Some reasonable definition here.</para><glossseealso otherterm="xml"/></glossdef></glossentry></glossdiv></glossary>
orchis:~/XML ->

  The output should be a well-formed XML file referencing the new XML
Dtd. Most elements are still valid. You can verify the validity of the result
to fix it if you were using elements now deprecated on DocBook 4:

orchis:~/XML -> xmllint --sgml test/DocBook/glossary.example.1.sgm > res.xml
orchis:~/XML -> xmllint --valid --noout res.xml
orchis:~/XML -> 

  If the valid check complains about missing DTDs or takes a long time
it means the Dtd or catalogs were not properly installed, go back to step
3/ and fix it.
  If the valid check complains about an invalid content model, it probably
means that you need to adapt the content to be proper for DocBook 4.

  One caveat is that xmllint --sgml can't handle entities in a simple way.
If your documentation is splitted this way, there is multiple approaches
possible:
   - use xmllint --sgml --nooent , it should generate a single output
     for the full set, basically replacing all entities references into
     the output. Then work from there to split the result once validation
     passes.
   - use xmllint --sgml for each of the entities, transforming all of them
     one at a time into XML docs. And when an entity is transformed change
     the entities declarations to the new ones and progress from leaves to
     root until you have covered the full tree.

  Hope this will help people transitions their documentation to XML.
Of course gtk-doc should be fixed too, and proper XSLT stylesheet should
be developped to replace their Jade based counterpart. But most of this
is automated processing and far less time-consuming than translating the
doc not automatically generated.

If KDE was able to make the transition, I don't see why we should be blocked.

Daniel

-- 
Daniel Veillard      | Red Hat Network https://rhn.redhat.com/
veillard redhat com  | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/