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 Mon, 03 Apr 2000 19:09:34 GMT
Mark Washeim wrote:

> I agree with this entirely and everything (more or less) you say below. I
> was only referring to documentation. That is, a common 'type' of reference
> document for the applications under the ASF umbrella. That doesn't impose
> much of anything on anyone??? Or what am I missing. . .

Hey, I never tried to impose anything on anybody... "suggest" and
"provide alternatives" are much better terms. 

> >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.
> When you refer to a DTD here, what document are you referring to? I don't
> understand your drift?

I'm talking about documentation.
> >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.
> There is NO SUCH DTD. 

Totally right. I would like to rephase the above:

"I'm trying to find the best DTD that matches our needs for
documentation and it's also capable of being scaled across all apache
projects at one point".

I DID not want to mean: "the ultimate DTD for XML publishing"... I know
such think doesn't exist.

> I can't imagine documentation complexity beyond what doc book can't handle
> that also wouldn't make writing documentation onerous. I'm sure you have
> examples though???

That's the point. I can't either.

But I do have _TONS_ of examples of documentation that doesn't fit the
DTD used originally in Stylebook. (and currently used in Xerces and
Xalan projects).

In fact, I wrote my own (that Cocoon currently uses)... but planning to
make a PDF version of the documentation... I see that what we have is
not enough...

So, instead of patching each and every time and rewrite the whole
stylesheets, I think it's worthwhile learning a complete and well
established documentation DTD and move from there on.

At least, for my _very_ personal point of view... then, if others like
the approach, great, if not... I don't care: they'll have to patch their
stylesheets everytime a new writer comes in the picture.
> >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?
> I think you're making sense, though, I think the point you make about using
> XSL transformations frees us all. I don't think there is a fundemental
> disagreement here at all.

no, I don't think so... it's a matter of misunderstandings.
> My question is, what is the likelyhood of having everyone deliver
> documentation in the same way (as we expect of javadoc), preferably across
> apache projects?

Good question.

My personal opininon:

1) provide complete solutions and solid contracts
2) smooth and reshape the learning curve afterwards with tools

this works for Cocoon APIs, sitemaps and documentation. Care about
teckies first, users later.

It's like the good old profiling pattern: complete first, optmimize

I don't know if this will work.... but I'm confident that once the
docbook stylesheets are in place and complete and a good and free XML
authoring tool is available, the transition path will appear so tempting
that will become a no-brainer.

I'm sure many of you disagre with me.... but this is my personal opinion

> >[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
> >that...]
> I'm not sure why you think you're not being understood. 


> I explicitly
> endorsed your suggestion and simply mentioned that I thought the 'contract'
> you were proposing between creators of software (programmers) and users
> (programmers, document maintainers, whoever) would be well served by the doc
> book schema. Hmmm. What's the problem?

Ok, let's get over this and do a votation:

"do you have any problems if the Cocoon2 documentation will be written
using the Docbook schema?"

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