cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <>
Subject Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]
Date Sun, 02 Apr 2000 23:03:18 GMT
Pierpaolo Fumagalli wrote:

> And also, Stefano, please... DocBook _is_ a DTD, is not an API carved
> into stone, chill out, will ya? you want the docs in DocBook? Ok, let me
> pay that 50$ and buy that book from O'Reilly and come up with a couple
> of stylesheets...
> Pier (asking why people cannot see sometimes 1 inch after their nose!)

I believe the problem is exactly that I see further than my nose. And
it's a pretty big one, you know that ;-)

Mark Washeim wrote:

> Though I think you're right to attempt to inject a bit of levity, you are
> missing one point both Norm and Stefano are 'circling' around.

No, he's trying to fucus on programming and I understand him... the
problem is that _somebody_ must care about documentation if we want this
project to be successful. Normally, Pier doesn't write docs unless
forced to do it, so he doesn't count :)
> Namely, that it is important for those collectively working on the
> documentation for the xml.apache projects (and other apache projects, for
> that matter) to spare themselves future 'reconcilliation' problems (that is,
> making the documentation 'similar' across projects).
> I KNOW this is a problem. That's why most corporation, including mine,
> impose a standard (I'm assuming you follow javadoc conventions for the
> convienience and consistancy it offers). DocBook is merely a useful,
> well-constructed DTD which could serve as a reference for those who must
> produce documentation. No need for everyone to use it, of course and as you
> point out. As long as YOU produce the xsl to transform it (or anyone else
> that choses another DTD).
> Personally, I think it would be great if DocBook were used at the apache sf.
> It would resolve consitancy problems with a reasonable, single point of
> reference for all documentation producers.

Might be a dream, but this is not the point.

My point is: 

 "you need solid contracts in order of two contexts to work together"

For programming, these contracts are APIs. For publishing, these
contracts are schemas. Period! 

Cocoon is a framework and a framework is a collection of guidelines,
design patterns and software to enforce them. A framework must be
flexible, but limit the flexibility to those patterns...

My vision is not the Perl-ish "there is always another way of doing it",
but the Java-ish "there are only a few optimal ways of doing something".

So, there is no "quest for the perfect publishing DTD", but a good
thought about what DTD is good for us, exactly like we did for the
internal Cocoon APIs.

Sure, we cannot possibly think about all the possible usages of
Cocoon... this is why we give the source code.

At the same time, we cannot possibly attach Cocoon to a particular
DTD... so we make Cocoon DTD-abstracted.

But at the same time, we _DO_ provide APIS to simplify the creation of
modules (the whole Avalon ideas comes after this)... what I'm trying to
do is to find out what is the best DTD we could use to match that on the
publishing side.

So, visualize the parallel: for DTDs is

  <p> ---> <paragraph> ----> <fo:block>
(simple)    (complex)         (final)

like for programming is
  XSP ---> generator ---> cocoon
(simple)   (complex)      (final)
Nobody ever forced people to write generators by hand, but some people
like this more... others like XSP more because there is more content
than code. So we provide both ways.

On the DTD side, there are cases where you don't care about docbook
complexity, so you write your own special DTD and convert this with
XSLT. I _NEVER_ had problems with that.
The question is: would you like, for example, a generator API which is
not complete, so you have to hook this into Cocoon core everytime you
need more stuff? of course not.

Think parallel: would you like a DTD that you have to extend everytime
you expand your documentation and make it more complex?

We choose SAX and TRaX because they convey programming patterns
solidified into APIs.

I proposed to choose DocBook for documentation because it includes
authoring patterns solidified into a schema.

Tell me, am I that insane to think parallel like this?

or, even more, am I making any sense at all?

[sometimes I feel like I speak a language you guys don't understand...
if this is the case, please, let me know because otherwise, I'll save my
time for something more fun that fighting over "contracts" :)       
well, language is the first of our contracts... so we must take care of

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