Re: DocBook vs. DebianDoc
On Sun, 30 Dec 2001, john@geekhavoc.com wrote:
> One problem with the "natural selection" theory, though, is that
> many writers will likely choose the simpler markup, given the
> choice; the simpler markup may well not be in Debian's best
> interests.
When do we speak of _authoring_ documentation, and when do we speak of
_using_ it (reading, querying, transforming in various formats, ...)?
As authors, we ideally want the smallest DTD with respect with what we
currently need to write. Small and ad-hoc, if possible. On the other hand,
when the doc is made public, we want it to be in a standard format, and big
enough to convey any technical realities. Difficult to have more opposite
goals. This contradiction usually leads discussions on the topic to
nowhere.
Fortunately, we now have tools that allow us to transform instances of
ad-hoc document types into plain standard DocBook. These tools are simply
XSLT engines (or even DSSSL, for that matter).
Instead of balancing the (relative) simplicity of debian-doc with the
completeness of docbook, another approach could be to elect docbook once
for all as our official source document type, while providing authors with
a set of small DTDs, along with their associated *_to_docbook XSLT sheets.
They could choose any DTD x out of this set, being assured that x_to_db.xsl
would produce the DocBook needed by the Debian project.
Even better, they could devise their own ad-hoc DTD and write themselves
the transformation sheet that produce documents of a type supported by the
"authoring DTD set". If their transformation sheet produce docbook
directly, they could contribute it to the set. Well, of course, they'd be
requested to document their DTD :-)
I happen to work for a technical publisher and I've never seen a book that
used more than 65 elements out of the 350 Docbook offers. For most of the
written at Debian, I'd say we don't need more than 30 different elements at
a time. It means that the authoring DTDs would be quite easy to design,
and the transformations would be simple as well, having to deal with very
few elements.
Xavier.
Reply to: