Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Message-ID: <38E47B88.3F6A1EC8@apache.org>
Date: Fri, 31 Mar 2000 12:18:48 +0200
From: Stefano Mazzocchi <stefano@apache.org>
Organization: Apache Software Foundation
MIME-Version: 1.0
To: cocoon-dev@xml.apache.org
Subject: Re: Documentation grammars,
 was:[Re: [RT] latest wonderings around W3C
 land and surroundings]
References: <38E14CF2.E4AD4AB7@apache.org> <38E22CDC.ACF4C279@apache.org>
 <1629-Thu30Mar2000011907-0500-ndw@nwalsh.com> <38E392EA.2169EF3A@apache.org>
 <2341-Thu30Mar2000154914-0500-ndw@nwalsh.com> <38E3E46E.17CAF6A7@apache.org>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

DISLAIMER: I'll try to be as neutral as possible so that people can
listen to me :)

Mike Pogue wrote:
> 
> Norman Walsh wrote:
> >
> > / Mike Pogue <mpogue@apache.org> was heard to say:
> > | 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...
> >
> > Right. I don't want to argue either. But I can't resist making a few
> > comments :-)
> >
> 
> I don't mind a good dialog at all!  (And this one is quite interesting!)

It is.
 
> > | 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.

> > | 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.
> >
> > Yep. The real question is what do you do when you need more
> > structure than HTML offers.
> 
> Agreed.  Thus the tags for stuff like Properties and Features.  Semantic
> tags
> that are specific to the XML parser.  In this case, documentation tags
> would
> have been the WRONG answer, since they have little semantic content.
> 
> 
> > | 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.

> > | 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!

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".

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.

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.

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".

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.

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