[kde-doc-english]DTD incompatibility

[Frederik Fouvry]

,-- On 21 Mar 2003 15:27:02 -0800, Gregory Leblanc wrote:
| 

[...]

| > V4.1.2Based Variant V1.1 will work on 3.1 and HEAD
| > V4.1.2-Based Variant V1.0 will work on KDE 3.0.x
| 
| What's the rationale behind KDE still maintaining a custom variant of
| the DocBook DTD? (Hopefully I've got the right list for this question)
| 	Greg

First of all, the goal is to maintain the customisation as a
_subset_ of the standard DTD (for instance to stop people from
using elements like bridgehead etc. to hack out certain visual
effects, although this is less needed now than at the beginning).
For most of the time (and currently), this is the case.  That
means that the documentation is valid with the standard DocBook
DTD (where the KDE FPI can be interpreted as an alias for the
DocBook DTD FPI).  So the KDE DTD is not _necessary_ to _read_
the documentation.  At KDE, however, we require adherence to the
subset to ensure the consistency of the markup.  In some cases,
we use more specific attribute values for attributes that had no
further specified value in the DTD (e.g. the language codes,
which are required to comply with ISO-639).  For recording
information about documents, we also require some
meta-information to be present.  Without specifying this in the
DTD, the documents would not be processed correctly by the style
sheets (and possibly other scripts), but we might never know in
some cases if checks are missing in the style sheets.  The DTD
customisation makes it very easy to check these requirements by
validating the document.

We also need a set of entities to make markup easier (and the
lists have grown quite long!), and for internationalisation.  For
that purpose the DTD has to be customised anyway (but it does NOT
make it an extension of the DTD - this is very important).

A great deal of omnipresent but unused attributes was turned off
to speed up processing.  If required they can be added at any
time, but currently they just would take time and space and not
give anything at all in return.  (Although I just noticed they
have been turned on again.  Perhaps it doesn't make a difference
in libxml2 ...)

Finally, in some cases - there was one at the very beginning when
we started using DocBook - an extension is necessary.  The case
I'm referring to was the lack of a PNG notation for images.  The
DocBook technical committee had agreed to add it, but since we
really needed the PNG notation (concerning the GIF patent
issues), we could not wait for the new release of the DTD.  In
such case, I find it entirely acceptable to turn the
customisation temporarily into an extension.  (Among others since
in the following release the extension isn't one anymore.)

To conclude, I am of the opinion that any documentation project
that takes itself seriously needs a customisation of some sort
(even if it only adds entities), but preferably a subset.  The
standard DocBook DTD is just too general (lots of elements for
marking up legacy documents; lots of attributes that are not
needed/used), and the use of entities in KDE has proven to be a
great help in ensuring consistency of the documentation (e.g. in
application names and their markup).

Frederik Fouvry

PS: It has been decided to keep the old versions of the DTDs
    around, at least for as long as binary compatibility of
    kdelibs is required (never thought that DTDs might count as
    binaries ;-), but possibly longer.