Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
To: cocoon-dev@xml.apache.org
Subject: Re: C2 documentation
References: <20000919072459.15426.qmail@web6204.mail.yahoo.com>
In-Reply-To: Giacomo Pati's message of "Tue, 19 Sep 2000 00:24:59 -0700 (PDT)"
Message-ID: <m2g0mwqcy2.fsf@niedermann.bb.bawue.de>
From: Hans Ulrich Niedermann <niedermann@isd.uni-stuttgart.de>
Date: 20 Sep 2000 01:53:46 +0200
Lines: 48
User-Agent: Gnus/5.0807 (Gnus v5.8.7) XEmacs/21.1 (Bryce Canyon)
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii

Giacomo Pati <pati_giacomo@yahoo.com> writes:

> > I'm +1 on using some form of DocBook for the documentation, using a
> > non-standard DTD when a standard one exists is silly.  However,
> > DocBook
> > is rather complex 
> 
> This is what scares me using it.

Hmm. I don't think Docbook is complex. Docbook defines a lot of
elements, right. But using an editor like XEmacs+PSGML, which lets
you choose from a list of valid elements and attributes at every
position in your document, you find the elements you need quite fast
and can type them in directly next time. I don't consider Docbook as
scaringly complex. I think Docbook just tries to cover all aspects of
software documentation. And we're going to use most of them anyway.

> > but I have heard of the Simple Docbook DTD - how
> > "simple" is this, or should we create a custom Docbook DTD like the
> > Simple DTD.
> 
> Having little DTD for specific document types (FAQ, Changes, document,
> etc.) is what I've liked best since. But I think we need to agree to a
> convention rather sooner than later.

Well, the structure of our docs is also quite complex. We have text
that has a section of subsections structure, we have reference pages,
we have FAQs, all representing different structures. If we want to
mark up our docs according to logical structure and semantics instead
of according to common layout ideas, the DTD also gets complex. And
nobody forbids you to use <!DOCTYPE qandaset "-//..."> for your FAQ.

Of course, we could try to define our own subset of the Docbook
DTD. This subset would only contain what we really use and therefore
be a subset of Docbook but a superset of Simplified Docbook. How big
exactly our Docbook subset would be, is a question that remains to be
answered. 

I personally would use "real" Docbook and also provide conversion
facilities for "real" Docbook. This would still allow for simple docs
written in Simplified Docbook (which is a subset of Docbook).

Or do you see the complexity you speak about within the markup of
acronyms, file names, XML elements, attributes, Java class names,
interface names with their respective markup in the text instead of
just using <code>? 

Uli