OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: Re: DOCBOOK: Re: On the size of DocBook...

On Fri, Sep 06, 2002 at 03:24:09PM -0400, Norman Walsh wrote:
> Why is Simplified DocBook easier to use than "full" DocBook?
> 1. Because when you open the DTD in emacs and read the content models,
>    it's smaller.
> 2. Because the user documentation for Simplified lists fewer elements.
> 3. Because when you pull down the "what can I insert here list", it's
>    shorter.
> 4. Because it's named "Simplified", it's less intimidating.
> 5. ...?
> Options 3 and 4 seem most likely to me.
> Option 1 really requires making the schema smaller, but I can't
> imagine the set of people comfortable reading DocBook "in the raw" who
> are also disturbed by its size is very large.

That's a tautology: people who are using the 400-element DocBook
DTD aren't put off by the fact that it's a 400-element DTD.

There are many people out there who aren't using DocBook, and it's
important to understand why.  That it takes 650 pages to describe 
is rather intimidating.  That there are elements like <errorcode>
and <calloutlist> doesn't help someone trying to write an article, or a
simple HOWTO structured as a book.

I've tried to introduce DocBook in a handful of organizations.
The TDG made it somewhat easier (it *must* be real; there's an
O'Reilly book about it).  But in the end, I've seen a lot of efforts
fail because using DocBook only seems to work for people who have
decided that learning how to use the DTD and tools is eventually
better than the alternatives, despite the initial pain.

Just for kicks, how difficult would it be to refactor DocBook into
a simple core (based on Simplified DocBook, or the moral equivalent),
and implement the full DTD as multiple layers of customizations on
top of the simpler core?  Once that's done, then it's easier[*] to
consider adding more elements in the DTD: a simple core plus the
required extra layers plus a few more elements, vs. a huge core
plus a few extra elements.


*: easier from the user perspective, not from the DTD maintainer/tool
   writer's perspective.

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC