cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Pogue <>
Subject Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]
Date Fri, 31 Mar 2000 17:25:49 GMT
Stefano Mazzocchi wrote:

> > > | 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:
> > >
> > > Here I have little sympathy. Arguing for short tag names is like arguing
> > > for short variable names.
> > I see your point.  There is, of course, a happy medium.  For example:
> >
> >         <p> vs. <para> vs. <paragraph>
> >
> > In this case, StyleBook went with the HTML style, rather than the
> > DocBook style
> > (which is <para> as I recall). We killed several birds with one stone:
> > it's
> > shorter, it's easier to learn, and you can cut/paste from HTML (OK,
> > XHTML).
> Hmmm, the verbosity problem doesn't count: it's easy to use <p> instead
> of <para> and have easy incremental XSLT that does the conversion. Or
> even
>  <author name="..."/> -> <author><name>...</name></author>
> and stuff like that.
> The problem is "tag-learning" and you don't learn tags easier if they
> are smaller... it's just the fact that HTML is already known, that's the
> key point.

Yes.  However, although <p> and <paragraph> are equivalent from a
programmer's point of view (e.g. one can always be transformed into the
other), they are not equivalent from a technical writer's point of view.

> >
> > > | 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
> > >
> > > Hack? *sniff* :-)
> >
> > No offense intended!  Just that if only one editor works with a
> > language,
> > then many people won't use it.
> ???? the EMACS "hack" you're talking about talks SGML/XML... I can't see
> your point.

It's a minor point.  Let me use an example:  If we created a new grammar
"SML" for Shoe Markup Language,
and then wrote an editor for it (an emacs hack, say), and then declared
"see -- the problem
is solved!", I think we would get some disagreement on that.  

In Computer Science we tend to do this:

	GOAL:  to prove that something is true, e.g. "DocBook needs to be
easily editable"
	step 1) create one instance of it	e.g. "I have created a DocBook mode
in emacs"
	step 2) declare victory			e.g. "therefore, everybody can now use
DocBook, Q.E.D."

However, in the Real World (in my humble experience), one instance is
not sufficient to solve the problem. We generally end up with solutions
like "you can use any editor you want".
This is a minor point, so I wouldn't get stuck on it.

> > > | 5) Any publishing system needs to be able to handle many grammars.  I
> > >
> > > Yep.
> > >
> > > |       Level II view, which is that the whole point is that you can customize
> > > | the
> > > |       grammar to be specific to *your* needs.
> > >
> > > This works fine until you want to get interoperability across
> > > classes of documents. Then you begin to wish that they had a
> > > common foundation.
> >
> > If I'm a SHOE manufacturer, I'm not sure how much I'll have in common in
> > my documentation with a BICYCLE retail store.  Sure, there will be some,
> > but there are bound to be differences.
> >
> > So, I believe there will be two tag sets here, one for the SHOE guy, one
> > for the BICYCLE guy.  Both will have tables, paragraphs, etc. in common.
> > But, the SHOE guy will have shoe styles, sizes, etc. and the bicycle guy
> > will have wheel size, color, seat configuration, etc. in his
> > documentation.
> This is the key point.
> This is EXACTLY the point.
> What you're saying about the XML world is equivalent to the following in
> the Java world:
> "my parser and your parser will surely parse a document but they will
> have both similarities and differences... so a common API doesn't make
> sense."
> Since I _know_ you believe in common and open APIs, I cannot understand
> while you don't believe in common "interfaces" for the XML world.
> Please, I want to understand!

I think I can say it clearest by saying that DocBook is a "Software
Documentation Markup Language", it's not a "Shoe Documentation Markup
Language" or a "Open Source XML Parser Documentation Markup Language".  
And, it's not clear to me that all things in Shoe Documentation Markup
Language can be represented in Software Documentation Markup Language (I
think there's likely to be an information loss.  Therefore, I conclude
two things, that:

	a) DocBook might not be the best initial representation language, if 
	you are an Open Source XML Parser Documentation writer, (e.g. the best
	for Open Source XML Parser Documentation might be OSXPDML, rather than
DocBook) and

	b) DocBook might not make a good intermediate language (lingua franca)
in the pipeline.

> True, the show-maker and the bike-maker will have different needs at
> some granularity... but if they do share something in common, good
> object oriented practices should be applied, rather than "everyone has
> it's own taste".

True.  Some things could be common, like <p> and <ul> and <table>.  But,
lots of 
other things won't be, like <size> and <manufacturer> and <property>. 
This argues for
factoring of grammars, something that people are working on, but the
results are not
really widespread yet.
> In OOP you are never forced to do something, as in XML. But while OOP
> has practices and design patterns that solidified over the years, XML
> does not (yet!).
> To me, it seems that "trying" hard to use DocBook (or a subset) instead
> of having different DTDs and stylesheets for every project it has
> _exactly_ the same reason as API and component creation: ineroperability
> and effort reuse.

That's ironic!  We both agree here.  I'm suggesting that we reuse HTML, 
you're suggesting that we reuse DocBook.  (NOTE: I initially suggested
Docbook, but
I was voted down by technical writers and engineers alike, because in a
between DocBook and HTML, HTML wins.  I have to agree that they have a
point!  :-)

> Of course, this doesn't mean you cannot do your own direction, but doing
> this you loose all the benefits of sticking with those interfaces and
> the community that builds around them.

Right, so stick with the HTML DTD, for those tags that can do so!  ;-)
> Exactly like happens on programming languages, or all types of common
> interfaces or paradigms.
> You know how much I'm obsessed by "forking" and "overlapping"... why?
> because in the open source movement they don't represent "diversity",
> they represent "waste of precious resources".

Oooh.  You are heading away from the whole idea of the Bazaar here,
"resemble[s] a great babbling bazaar of differing agendas and
DocBook strikes me as "quiet, reverent cathedral-building".  (quotes are
from the Cathedral and the Bazaar).

Forking is not Bad.  It's not necessarily bad to "waste" some resources,
as long
as not all of your resources are wasted.  [Side note for Computer
geeks:  note the analogy to hill climbing and simulated annealing
algorithms, which
require some "wasted" random effort to function well, or at all]
> This is my humble opinion.
> > > | Stylebook (and Cocoon) are interesting to me, because they do NOT force
> > > | an intermediate representation (or, at least they didn't in the past).
> I find this unfair and utterly offensive.
> The Cocoon project was created with _no_ absolute whatsoever knowledge
> about the DTD that is being processed and _there_ is no absolute way we
> can force one DTD to be the only one recognized. The Cocoon architecture
> was _designed_ to be abstracted and it's power is and will always remain
> its abstraction.
> If you believe we can possibly think about changing this, it's easier
> that you say that I'm a total idiot, because that is what your sentence
> meant to me.

Sorry, didn't mean it that way.  IMHO, both Stylebook and Cocoon are
close to having an "Official DTD".  My evidence?  How many alternate
DTD's do we 
have?  Few. How many site styles do we have?  Few.  And, all the styles
that we do 
have look pretty much alike (hierarchical nav bar on the left,
composited banner at 
the top, copyright at the bottom, etc.)  I'd say that's strong evidence
that we don't have 
ENOUGH diversity, ENOUGH randomness, and ENOUGH wasted energy, and we
probably have 
too much Cathedral building going on here.  

It's not just Cocoon (hey, chill out, will ya?!), it's Stylebook, too
(re-read my quote above -- I'm commenting on both of them).

By the way, Zope appears to have the same exact problem.  All the Zope
sites look very similar.
What does that tell us about Zope?  (And, by analogy, Stylebook and

> --
> Stefano Mazzocchi      One must still have chaos in oneself to be
>                           able to give birth to a dancing star.
> <>                             Friedrich Nietzsche
> --------------------------------------------------------------------
>  Missed us in Orlando? Make it up with ApacheCON Europe in London!
> ------------------------- http://ApacheCon.Com ---------------------

View raw message