cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Pogue <mpo...@apache.org>
Subject Re: [RT] latest wonderings around W3C land and surroundings
Date Thu, 30 Mar 2000 17:46:18 GMT
Norman Walsh wrote:
> 
> / Mike Pogue <mpogue@apache.org> was heard to say:
> | "DocBook Lite", because DocBook was way too complex for general use.  But, feedback
from actual
> | writers was that even DocBook Lite was too complex for general use (it's powerful,
but way
> | complicated and more verbose than necessary).
> 
> Can you provide some more detail about what aspects of a
> simplified DocBook subset your writers found too complex and/or
> verbose?

Sure!
 
> I am in complete sympathy with authors who argue that DocBook is
> different and change is hard and besides they're way to busy
> getting work done to learn a new DTD, but I'm beginning to lose
> patience with vague generalizations like "it's too complex" or
> "too verbose" without a little more detail.
>

Let me try to characterize some of the comments I got, which I
summarized
as "it's too complex"  (I agree that I was being vague here).  And,
please
don't get me wrong -- I'm not against DocBook.  That's *exactly* where I 
started when I came up with the original Stylebook idea!  But, feedback
from
my users (including a technical writer) forced me to change my opinion.  
Also, I'm not interested in a point by point rebuttal here, this is just 
feedback, not an argument against Stefano or anybody else...'nuf said...

Couple of general points:

1) DocBook requires an O'Reilly book to decode.  And, it's a thick one. 
It has a large number of
	element names (for many different and powerful purposes).  Most of
	the tags are used infrequently.  Of course, there's a reason for
	the existence of every single one of them!  There's just a lot of them.
	So, by taking 20% of the tags (used 80% of the time), it was a lot
simpler.

	Side note:  There's a reason for each and every bit of bureaucracy in
the 
	US Government, but that doesn't mean that it makes sense, when you take
a 
	step back and look at the whole mess we ended up with.  I'd be willing
to
	put up with some corruption and stealing, if it meant that the
bureaucracy 
	were 80% smaller.  It would be cheaper overall, because the cost
savings
	by making it 80% smaller is much larger than the corruption/stealing.

2) DocBook is more verbose, and therefore requires more effort, than the
alternative.
	(Tags in DocBook tend to be longer, and more descriptive, as I recall).

	Both 1 and 2 argue for a *DocBook lite*, and that's where I went to,
except
	for that pesky feedback I got:

3) Many of the DocBook tags are unfamiliar to writers, who tend to be
familiar with HTML,
	and not with DocBook.  There doesn't seem to be much additional
semantic
	advantage to choosing different tags, when an HTML tag is essentially 
	available that means the same thing.  (e.g. lists, tables, etc.)
	Training is less, if it looks a lot like something you already know.

4) Most editors don't work with DocBook.  Sorry, but an emacs hack is
not
	sufficient.  Writers (and programmers) tend to stick with a single
tool,
	and they don't like to change.  With a more HTML-like language, a tool
	like Allaire HomePage (I think that's the name) or anything else
	can be used for editing the XML.  We tried a lot of XML editors, and
most are crap.

5) Any publishing system needs to be able to handle many grammars.  I
think that
	forcing everybody to use a single grammar is a common mistake.  People
view
	Stylebook (and Cocoon) as a publishing engine for a *single grammar*. 
That's
	what I call the Level I view.  I'm trying to get people to think about
the
	Level II view, which is that the whole point is that you can customize
the
	grammar to be specific to *your* needs.  

	Thus, we came up with the Properties part of the Stylebook grammar, the
Features part, the 
	FAQ part, and the Release Notes part.  These parts were all specific to
	software, and some are specific to XML parsers. AND: None have
equivalents in
	DocBook.  

	The whole Stylebook idea (and by extension, Cocoon) is that you can
edit in a
	grammar that is SPECIFIC TO YOUR PARTICULAR INDUSTRY/TASK, and you're
not
	forced to use the "Technical Book Writers DTD" (DocBook).

Side note: I'm not convinced that using DocBook as the Lingua Franca for
Cocoon (step 2 in the current diagram) is a wise idea.  That limits
people to being able to publish only that which can be represented in
DocBook form (since DocBook is an intermediate representation).  

It would analogous to say that all languages (like Italian :-) must be
translated to English, before the data can be stored in a database.  I
suppose you can do that, but it's not a good idea, because something
will be lost.

Stylebook (and Cocoon) are interesting to me, because they do NOT force
an intermediate representation (or, at least they didn't in the past). 
They associate an input format (grammar) with a processing pipeline, but
they do not force everything into one format.
 
> (And apologies in advance if I sound defensive. I'm
> not. Honest.)

No offense taken!  I think you're the first person who has asked "why
has Mike
said this -- what information does he have that I don't have?", rather
than jumping to "Mike is obviously wrong".  (Sorry if *I* seem defensive
here -- I really do appreciate that you're
asking, rather than assuming that I make statements with no information
or experience to 
back them up).   Ah well, I guess that sounded a wee bit defensive...

> 
>                                         Be seeing you,
>                                           norm
> 
> --
> Norman Walsh <ndw@nwalsh.com>      | To create a little flower is the
> http://nwalsh.com/                 | labour of ages.--Blake

Mime
View raw message