Re: debiandoc vs. docbook
On Fri, 20 Sep 2002, Susan Kleinmann wrote:
> I believe it would be a good idea to revisit the policy stating that all
> debian documentation should be written in debiandoc.
Agreed.
With due deference to those writers who are more interested in matters
of content than the niceties of markup, I nevertheless feel that this proposal
is timely, given the ever-widening gap between Docbook SGML/XML and Debiandoc
SGML, and the increasing need to _process_ documentation text in various ways,
as well as simply format it for presentation.
The debiandoc DTD may now be said to have lived out its useful life-span; it
has helped introduce novices and non-specialists to SGML markup, certainly;
but those days are past, and today it is something we should be aiming at
actively phasing out rather than hanging on to for nothing more than
historical reasons. Sorry if that upsets anyone; but we really *should* be
looking for a more suitably adapted replacement to take us on into the future
now.
So yes; it _is_ time we revisited policy on this.
(We could also perhaps start tentative discussions on how we are going
to cope with audio, video and multi-media documents too, whilst we're at it.)
> 1. We should adopt an XML based language because of the abundance of tools
> that exist to manipulate such languages.
Yes; but let's not throw the baby out with the bath water completely for the
moment.
I know that for many XML is the latest and greatest buzzword-of-the-month
technology, and that indeed, some think it has completely 'replaced' SGML
markup outright (!?!); but this just isn't true, and certainly does not
reflect the daily working reality of many of us.
Quite simply, there are a lot of non-professional authors, writers and
documentation specialists who are only just coming to terms with the needs
of markup and the sort of environment SGML processing requires; asking them to
set up and work with a full-blown XML database-driven environment at this
point might be just too much to take on. (Besides which, lots of it is still
iffy, anyway :)
So I would say: Yes; let's move on from debiandoc, officially; let's start
mandating Docbook; but in either SGML _or_ XML form, _not_ specifically XML
only. (Define a phase-out period to XML environment only, if necessary -- two
years?)
> 2. We should consider docbook-xml because it is widely used, well
> documented, well supported by tools, and provides much greater expressive
> power than is currently achievable with debiandoc. There even exists a
> docbook-simple now, for those who are initially overwhelmed by the
> richness of the docbook tag set.
No problem with this as long as SGML per se is also allowed and allowable;
any conversion required (such as it is) could perhaps be carried out by a
specialist team? Is the debian-doc team thinking of moving to the lampadas
database entry system for documentation? Should not moves be made to tie in
what debian-doc is doing with what linux-doc (tldp) is doing?
(This is the crux of the matter as far as I am concerned. The two projects
have diverged too far in their repective manner of processing text, and need
to be brought back closer in line with each other. Most of us are writing for
both, anyway.)
> 3. We should (soon) transform the debiandoc files that we now have to
> docbook-xml using, e.g., the script written by Ardo van Rangelrooij:
> http://lists.debian.org/debian-doc/2002/debian-doc-200205/msg00183.html
> In any case, we should agree on a script or process to do the
> transformation, because without that, in order to ensure some uniformity
> in the transformation of all the documents to a new DTD.
Yes. How about making it the specific responsibility of a specific team?
Maybe take up the slack of the new upcoming group of documentation-maintainers
in this way? (Documentation-maintainers are currently a widely misunderstood
and disregarded group amongst the debian developer community, and need a far
higher profile and degree of acceptance in their own right.)
> 4. If the original/current authors don't want to do the translation, we
> should consider setting up some kind of volunteer method to do that,
> something like a bug-squashing-party.
Absolutely. [And I love the idea of a documentation 'write-out' (?)
Even if the general readership gives this the thumbs-down, could you and I try
that one weekend, Susan? Could be fun, as well as instructive.]
> 5. Those who prefer to write in debiandoc can of course go ahead and do so,
> but should transform their documents to docbook-xml (or whatever DTD or
> schema is adopted) before uploading them to the CVS repository.
Or know who to go to to get them transformed.
> Please note the word "propose",
Noted. [Not that it'll make any difference you know. This is the stuff
flame-wars are made of. :-]
msw
--
Martin Wheeler - StarTEXT / AVALONIX - Glastonbury - BA6 9PH - England
msw@startext.demon.co.uk http://startext.demon.co.uk/
GPG pub key : 8D6B948B ECC6 D98E 4CC8 60E3 7E32 D594 BB27 3368 8D6B 948B
- Share your knowledge. It's a way of achieving immortality. -
Reply to: