Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]

[Mark Washeim <es...@canuck.com>]

Pierpaolo,

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.

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.

As for my part, if you think a discussion of docbook is a waste of time, you
should try getting out of the perpetual CALS table model discussion I've
been working through for the last n years....

Respectfully and with thanks to Norm, Mike and Stefano for wrangling this
out,
Mark
-----Original Message-----
From: Pierpaolo Fumagalli <pi...@apache.org>
To: cocoon-dev@xml.apache.org <co...@xml.apache.org>
Date: 01 April 2000 21:33
Subject: Re: Documentation grammars, was:[Re: [RT] latest wonderings around
W3C land and surroundings]


>Stefano Mazzocchi wrote:
>>
>> The whole thing is clearly getting too religious to be resolved: you
>> like one DTD, I like another.
>>
>> Well, this arguing is pointless.
>
>Ohhh..... Finally something _SERIOUS_ said here....
>
>> But don't worry, we will _NOT_ impose any DTD on this project or to any
>> other. How could we possibly do that?
>
>And also because if you do, I know where you live :) :) :)
>A nice kick in 'da ass will be surely deserved :) :) :)
>
>> Of course, we'll vote to choose one for our docs and we'll write the
>> skins for it.
>
>And if DocBook will be voted to be _THE_ DTD, I'll have to pass all docs
>in Cocoon before committing them to the CVS to convert them from MY DTD
>to yours.... Is this THAT HARD to do????
>
>> But we will _NEVER_ limit the ability to Cocoon/stylebook
>> to that single DTD and we are committed to include in the distribution
>> all the skins/DTD that the different projects can produce.
>> There are no reasons to do otherwise.
>
>That's for sure :) So, you produce the stuff for DocBook, and I produce
>the stuff for my DTDs....
>
>> I believe a more powerful DTD is needed, you don't. That's it.
>> It's the same old "VI vs. Emacs" tune and doesn't help anyone because
>> there's room for both.
>
>In fact I use UltraEdit... And screw both religions :)
>
> Pier (and the first person who will reopen this discussion
>              will be mailbombed, by me! :)
>--
>----------------------------------------------------------------------
>pier: stable structure erected over water to allow docking of seacraft
><ma...@betaversion.org>      <http://www.betaversion.org/~pier/>
>----------------------------------------------------------------------
>
>

Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]

[Pierpaolo Fumagalli <pi...@apache.org>]

Mark Washeim wrote:
> 
> 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).

Did I say that someone other than me is going to be producing that XSL?
Nope... I'm just a software coder, never written more than 10 lines of
docs in my life, and my only point is to develop the best possible XML
publishing engine (and we're succeding in it, Cocoon 2.0 is the proof...
Everytime I'm out showing it off -4 convention talks about it in the
last month- everyone is impressed by what WE are doing...)
As I said DocBook or the XML.APACHE.ORG DTDs are JUST DTDs... The focus
of this mailing list MUST be the development of the tool... And we
shouldn't all waste time arguing (gettin' angry) about those... And if
we really want to do it, please let's do it in <ge...@xml.apache.org>
or somewhere like that...
The cocoon-dev mailing list focuses on the development of Cocoon, and
DTDs are, IMVHO, out of context...

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

Mike, it's already hard to talk about how projects are structured in the
foundation, it's even harder to talk about the introduction of XML in
places where it would be really useful like configurations (see the
flames on the different mailing lists!)...
If you think it will be EVER possible to let all the people in the
foundation (all developers and doc writer) agree on a single DTD, or
even just to use XML to write docs, you _ARE_ dreaming... 

> As for my part, if you think a discussion of docbook is a waste of time, you
> should try getting out of the perpetual CALS table model discussion I've
> been working through for the last n years....

I think it's NOT relevant here, where we're discussing about the
implementation of a publishing framework called Cocoon. if you guys want
to fight about anything (because lately the discussion _was_ a fight)
that is not strictly related to the architecture and bugs of Cocoon
2.0,  please don't do it here... Or if you do, just tell me, and I'll be
more than happy to unsubscribe... 
I don't want to see my friends flaming each other on things that are, on
this mailing list, of marginal importance. We _have_ to concentrate on
the tool right now, and get it out for JavaONE... Because that's the
promise I made on behalf of this group, and regardeless of the fact that
the group follows me or not, I'm going to maintain it.

	Pier

-- 
----------------------------------------------------------------------
pier: stable structure erected over water to allow docking of seacraft
<ma...@betaversion.org>      <http://www.betaversion.org/~pier/>
----------------------------------------------------------------------