Re: DocBook vs. DebianDoc
On Sat, Jan 19, 2002 at 12:05:36AM +0100, Xavier Cazin wrote:
> 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.
This sounds like the absolute best solution. It really looks like XML
is going to be the de facto standard in the coming decade, for not
just documentation but also lots of programming interfaces. So we will
be forced into being able to use the lingua franca whether we plan for
it or not. We should make it easy!
--
*------v--------- Installing Debian GNU/Linux 3.0 --------v------*
| <http://www.debian.org/releases/woody/installmanual> |
| debian-imac (potato): <http://debian-imac.sourceforge.net> |
| Chris Tillman tillman@azstarnet.com |
| May the Source be with you |
*----------------------------------------------------------------*
Reply to: