cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Mark Washeim" <>
Subject Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]
Date Mon, 03 Apr 2000 14:11:13 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 :)

Periodically I have to coral in my programmers to make them clean up
documentation. However, over time, they've tended to simply make better
'in-line' documentation AND secondary (ie, read me) docs by virtue of the
fact that it saved them time. We don't have a 'documentation' team, per se
and live by the philosophy that those who write the code, if it is to be of
any use to anyone, must be documented by those who know it best.

Of course, not a mentality in many code factories. Our programmers are also
designers, by and large.....

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

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

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

>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. I mentioned the CALS table model (US military spec) in
an earlier mail. It's the basis of much of what's in HTML. It's also
limiting in ways that make it useless for publishing while very usefull for
industrial purposes (where the constraints of 'layout' are not in effect).

In any case, we're working on publishing tools (you should get a tar ball of
an alpha, schema based xml editor, today) which will leverage schemas and
the site map. In our applications, the visual apps are initialized using
schemas which encompass collections of documents (as well as schemas for
individual documents). While some elements which belong to the site wide
schema are shared (using schema extensions) most documents do not derive
from the site wide schema in the sense that they 'share' all of the site
wide schema's elements. They 'may' or not. They may also derive their own

It boils down to there being document structures such as
'DepartmentDescription' that are shared between the human resources and
public relations deptartments. In the file system (one of our mechanisms):

where dd is department description.

There is also:

the latter being all 'shared' element types across linguistic/national
The en_US variant is the american english derivatives, obviously.

As it happens, concrete files may also live in the system, as such:

for instance. That's were we're headed to promote reuse of schemas while
permiting derivations or in fact utterly different types to come into play.

The site map is used to handle public access (ie, using process instructions
in cocoon 2, when we get that far..._)

>So, visualize the parallel: for DTDs is
>  <p> ---> <paragraph> ----> <fo:block>
>(simple)    (complex)         (final)
>like for programming is
>  XSP ---> generator ---> cocoon
>(simple)   (complex)      (final)

I don't think you're example has much meaning here because it's not a
question of a <P> being transformed into a block, since the xml is bound,
often to be entirely arbitrary. Paragraph may be useful when you KNOW you're
making a document in the first place and not just dealing with an
'arbitrary' data structure....

If you chose docbook, you chose a set of data structures well suited to the
task of editing documentation books, obviously. I think that in itself is
like chosing a well encapsulated design for an object.

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

And thank you very much. We're using BOTH! Yeah!

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

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

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

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?

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

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?


>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