On automatic conversion

[Frederik Fouvry <fouvry@sfs.nphil.uni-tuebingen.de>]

| But the auto-conversion process can *never*, no matter how much
| feedback, do a real job of converting Linuxdoc to DB
| automagically. Why? Because there is a massive impedance mismatch
| between Linuxdoc and DB, as others have pointed out repeatedly, most
| recently Ed Bailey from Red Hat.
| 
|     Gary> If we go with a half-cocked Author Guide, we will be faced
|     Gary> with having to re-format new documents to our eventual style
|     Gary> guide, whereas if we use existing docs to auto-generate what
|     Gary> we *think* people will want, if they don't like it, it is no
|     Gary> big deal to re-generate a modified set and to continue the
|     Gary> iterations until everyone is happy (well, at least content)
| 
| I think that this kind of up-translation from a semantically-sparse
| DTD to a semantically-rich DTD isn't going to be automatically
| possible. In fact, I'm pretty sure I've heard *real* SGML experts say
| that very same thing. :>

It is entirely true (even tough I'm not a real expert ;-) that the
conversion cannot happen automatically.  However, it is possible to
convert LinuxDoc to _valid_ DocBook documents.  This is the KDE
approach: the documents are first converted automatically to valid
DocBook documents (20% are valid without changes, a large majority
need trivial changes, which could have been avoided if the main aim
had been to generate valid documents; the rest are slightly more
complicated cases, or come from non-valid LinuxDoc documents).  In the
next step, the valid DocBook is converted to "proper DocBook".  This
major (!) task will start soon.  The conversion is used for what it
can do (converting existing information) - and that's a rather boring
and cumbersome task that is avoided already; adding markup is left to
human editors.  For new documentation, it is possible that we'll have
a couple of DocBook authors who put new documentation in the correct
format, for those who don't want to deal with it (for some LinuxDoc is
nearly too much already).  In the meantime, we can generate HTML from
our documentation without errors, and the result looks pretty much
like it would do with proper markup (which is fortunate
w.r.t. documentation uniformity for the user).

I would suggest you try to convert a few documents automatically, and
consider what you want to do based on that, without dismissing
conversion out-of-hand.

-- 
Frederik Fouvry
KDE DocBook Team


--  
To UNSUBSCRIBE, email to ldp-docbook-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org