You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Mike Pogue <mp...@apache.org> on 2000/03/31 01:34:06 UTC
Documentation grammars, was:[Re: [RT] latest wonderings around W3C land
and surroundings]
Norman Walsh wrote:
>
> / Mike Pogue <mp...@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!)
> | 1) DocBook requires an O'Reilly book to decode. And, it's a thick one.
> | It has a large number of
> | element names (for many different and powerful purposes). Most of
> | the tags are used infrequently. Of course, there's a reason for
>
> I've tried to get O'Reilly interested in doing a quickref, maybe
> that would help. Moreover, I should probably make a version of
> TDG for the Simplified subset (which has 100 tags instead of 400 :-).
I think we ended up with about 20 in Stylebook, and that includes the
ones that were developed specifically for XML and the parser
documentation.
Where possible (like tables), the tags are identical to HTML.
If you can, try to make the simplified subset even smaller!
> | 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).
> | 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.
> | 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.
> | Stylebook (and Cocoon) are interesting to me, because they do NOT force
> | an intermediate representation (or, at least they didn't in the past).
> | They associate an input format (grammar) with a processing pipeline, but
> | they do not force everything into one format.
>
> DocBook is a lousy choice if you want to model your data (which is what
> I interpret "intermediate representation" to imply). Docbook is for
> documentation, not modelling.
I feel that it is for one particular KIND of documentation, too. It is
too
expressive for Software Documentation, and not expressive enough for
Shoe
and Bicycle Documentation! :-)
> Be seeing you,
> norm
>
> --
> Norman Walsh <nd...@nwalsh.com> | Man's sensitivity to little things
> http://nwalsh.com/ | and insensitivity to the greatest
> | are the signs of a strange
> | disorder.--Pascal
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C
land and surroundings]
Posted by Pierpaolo Fumagalli <pi...@apache.org>.
Mike Pogue wrote:
>
> I think we ended up with about 20 in Stylebook, and that includes the
> ones that were developed specifically for XML and the parser
> documentation.
> Where possible (like tables), the tags are identical to HTML.
And I can live with those 20, even if I use only 10 of them :) :) :)
Kids... those are JUST DTDs...
Pier
--
----------------------------------------------------------------------
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]
Posted by Mike Pogue <mp...@apache.org>.
Norman Walsh wrote:
>
> / Mike Pogue <mp...@apache.org> was heard to say:
> | I think we ended up with about 20 in Stylebook, and that includes the
> | ones that were developed specifically for XML and the parser
> | documentation.
> | Where possible (like tables), the tags are identical to HTML.
>
> Where is the stylebook DTD?
I think it's in the Stylebook section of CVS. There's no documentation
though,
just the DTD.
> | If you can, try to make the simplified subset even smaller!
>
> I have. http://nwalsh.com/docbook/simple/sdocbook/: what would you delete?
I'll take a look!
> | 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).
>
> I disagree that it's easier to learn in principal, but given that
> almost everyone now knows HTML, perhaps it's easier in practice.
Yep. "in practice" is what I meant.
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]
Posted by Norman Walsh <nd...@nwalsh.com>.
/ Mike Pogue <mp...@apache.org> was heard to say:
| I think we ended up with about 20 in Stylebook, and that includes the
| ones that were developed specifically for XML and the parser
| documentation.
| Where possible (like tables), the tags are identical to HTML.
Where is the stylebook DTD?
| If you can, try to make the simplified subset even smaller!
I have. http://nwalsh.com/docbook/simple/sdocbook/: what would you delete?
| 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).
I disagree that it's easier to learn in principal, but given that
almost everyone now knows HTML, perhaps it's easier in practice.
| > | 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.
|
| > | 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.
|
| > | Stylebook (and Cocoon) are interesting to me, because they do NOT force
| > | an intermediate representation (or, at least they didn't in the past).
| > | They associate an input format (grammar) with a processing pipeline, but
| > | they do not force everything into one format.
| >
| > DocBook is a lousy choice if you want to model your data (which is what
| > I interpret "intermediate representation" to imply). Docbook is for
| > documentation, not modelling.
|
| I feel that it is for one particular KIND of documentation, too. It is
| too
| expressive for Software Documentation, and not expressive enough for
| Shoe
| and Bicycle Documentation! :-)
|
| > Be seeing you,
| > norm
| >
| > --
| > Norman Walsh <nd...@nwalsh.com> | Man's sensitivity to little things
| > http://nwalsh.com/ | and insensitivity to the greatest
| > | are the signs of a strange
| > | disorder.--Pascal
Be seeing you,
norm
--
Norman Walsh <nd...@nwalsh.com> | One must look for one thing only,
http://nwalsh.com/ | to find many.--Cesare Pavese
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]
Posted by Norman Walsh <nd...@nwalsh.com>.
/ Stefano Mazzocchi <st...@apache.org> was heard to say:
| Mike Pogue wrote:
| > Norman Walsh wrote:
| > > / Mike Pogue <mp...@apache.org> was heard to say:
| > > | 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
None taken, by the way. I forgot to say that in my first reply. :-)
| ???? the EMACS "hack" you're talking about talks SGML/XML... I can't see
| your point.
I took this comment to be in reference to my docbookide mode,
not psgml-mode.
| > 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.
We're wandering a bit far afield here. All of the DTDs we're
discussing are ostensibly for the same purpose: software
documentation. (There's an element of modeling in some of the
DTDs that I don't claim to understand just yet.)
I don't know about shoe and bicycle manufacturers, but I'm pretty
confident that dress shoe and hiking boot manufacturers would
benefit from some common foundation.
| 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!).
With respect, XML has been around for more than 10 years. It
just had bad marketing. There are well understood design
practices and methodologies for DTD design (I'm not 100% sure
that schema design is exactly the same, but I think it will be
similar).
If you can find a copy of Maler and Andaloussi's book, buy it:
<biblioentry id="maler96">
<title>Developing &SGML; &DTD;s</title>
<subtitle>From Text to Model to Markup</subtitle>
<authorgroup>
<author>
<firstname>Eve</firstname>
<surname>Maler</surname>
</author>
<author>
<firstname>Jeanne</firstname>
<surname>El Andaloussi</surname>
</author>
</authorgroup>
<isbn>0-13-309881-8</isbn>
<publisher>
<publishername>Prentice-Hall PTR</publishername>
<address>
<city>Upper Saddle River</city>
<state>New Jersey</state>
</address>
</publisher>
<pubdate>1996</pubdate>
</biblioentry>
(It has, alas, gone out of print.)
| 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.
Makes sense to me.
Be seeing you,
norm
--
Norman Walsh <nd...@nwalsh.com> | In science, "fact" can only mean
http://nwalsh.com/ | "confirmed to such a degree that
| it would be perverse to withhold
| provisional assent." I suppose
| that apples might start to rise
| tomorrow, but the possibility does
| not merit equal time in physics
| classrooms.--Stephen J. Gould
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C
land and surroundings]
Posted by Pierpaolo Fumagalli <pi...@apache.org>.
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]
Posted by Stefano Mazzocchi <st...@apache.org>.
Mike Pogue wrote:
> That's ironic! We both agree here. I'm suggesting that we reuse HTML,
> you're suggesting that we reuse DocBook. (NOTE: I initially suggested
> Docbook, but
> I was voted down by technical writers and engineers alike, because in a
> contest
> between DocBook and HTML, HTML wins. I have to agree that they have a
> point! :-)
Interesting: XML was created as a way to overcome HTML limitations and
your document writers say HTML wins or a documentation-specific
language.
There is clearly something wrong happening here.
> > 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.
>
> Right, so stick with the HTML DTD, for those tags that can do so! ;-)
> ;-)
>
> > 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".
>
> Oooh. You are heading away from the whole idea of the Bazaar here,
> which
> "resemble[s] a great babbling bazaar of differing agendas and
> approaches".
> DocBook strikes me as "quiet, reverent cathedral-building". (quotes are
> from the Cathedral and the Bazaar).
??? Norman is here and I'm sure that he'll be totally happy to discuss
publicly additions to the standard.
> Forking is not Bad. It's not necessarily bad to "waste" some resources,
> as long
> as not all of your resources are wasted. [Side note for Computer
> Science
> geeks: note the analogy to hill climbing and simulated annealing
> algorithms, which
> require some "wasted" random effort to function well, or at all]
Forking is not bad? How about having two competing parsers under the
Apache XML project? how happy would you be with that?
> > 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.
>
> Sorry, didn't mean it that way. IMHO, both Stylebook and Cocoon are
> dangerously
> close to having an "Official DTD". My evidence? How many alternate
> DTD's do we
> have? Few. How many site styles do we have? Few. And, all the styles
> that we do
> have look pretty much alike (hierarchical nav bar on the left,
> composited banner at
> the top, copyright at the bottom, etc.) I'd say that's strong evidence
> that we don't have
> ENOUGH diversity, ENOUGH randomness, and ENOUGH wasted energy, and we
> probably have
> too much Cathedral building going on here.
>
> By the way, Zope appears to have the same exact problem. All the Zope
> sites look very similar.
> What does that tell us about Zope? (And, by analogy, Stylebook and
> Cocoon?)
The whole thing is clearly getting too religious to be resolved: you
like one DTD, I like another.
Well, this arguing is pointless.
But don't worry, we will _NOT_ impose any DTD on this project or to any
other. How could we possibly do that?
Of course, we'll vote to choose one for our docs and we'll write the
skins for it. 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.
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.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Missed us in Orlando? Make it up with ApacheCON Europe in London!
------------------------- http://ApacheCon.Com ---------------------
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]
Posted by Norman Walsh <nd...@nwalsh.com>.
/ Mike Pogue <mp...@apache.org> was heard to say:
| Stefano Mazzocchi wrote:
[Mike, try not to trim out the attributions, ok?]
| > 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!
|
| I think I can say it clearest by saying that DocBook is a "Software
| Documentation Markup Language", it's not a "Shoe Documentation Markup
| Language" or a "Open Source XML Parser Documentation Markup Language".
DocBook has always maintained that its domain is computer
software and hardware documentation. (I suppose it's not a
narrow scope, but the assertion that we have a scope keeps us
honest. Presented with new feature requests, we have
occasionally declined perfectly intelligent proposals on the
basis that they didn't meet a need in our domain.)
| And, it's not clear to me that all things in Shoe Documentation Markup
| Language can be represented in Software Documentation Markup Language (I
| think there's likely to be an information loss.
No argument about shoes, but you seem to be implying that "Open
Source XML Parser Documentation Markup Language" is not computer
software documentation, and I don't get that at all.
| I was voted down by technical writers and engineers alike, because in a
| contest
| between DocBook and HTML, HTML wins. I have to agree that they have a
| point! :-)
They definitely have a point. But what exactly is it? I think it
amounts to something along these lines: we're busy, change is
hard, documentation is rarely a priority, we know HTML, we don't
know DocBook, we want to use HTML.
I sympathize.
I would like to make a different point. The Apache Project is
undertaking a large, complex project involving at least six
major products (Xerces in two languages, Xalan in two languages,
Cocoon, and FOP--and those are just the ones I know about).
These projects are all related in some respects. At the end of
the day, there will be a lot of documentation in this project.
That documentation will need to be presented in a variety of
ways (at least on paper and on full-featured browsers, but
probably also on PDAs and electronic books, and speach readers,
and braille devices, and maybe even cell phones).
If no effort is made to develop a common vocabulary for this
documentation, things are not going to be very pleasant for the
authors and publishers of this information. HTML does not have
rich enough semantics to capture the information that you're
going to want to have captured for flexible rendering and
next-generation search and indexing tools.
Drawing on many years experience, I assert that in the long run,
it's better to train authors now, deal with the pain and anguish
that change causes, and establish a common vocabulary now.
That common vocabulary does not have to be a single schema, and
it certainly doesn't have to be DocBook, although I am inclined
to think that DocBook is the obvious and correct choice, a small
set of schemas makes perfect sense. But make it rich enough to
get the job done tomorrow or you'll find yourself with thousands
of pages of documentation to drag up hill. And dragging
documentation up hill is a painful process that requires
significant human intervention.
| Right, so stick with the HTML DTD, for those tags that can do so! ;-)
| ;-)
Sure. But what do you do for HTML thags that "almost do". Do you
have add <procedure> tag, or do you accept that you can't
distinguish between procedures and numbered lists that aren't
procedures. Do you add markup for class and function synopses,
or do you rely on some collection of <sup>, <sub>, <br>, and
<font> tags to get the job done.
Authors love to twiddle with documents, getting the formatting
"just so". (I'm guilty of it too, so I know I'm throwing stones
in a glass house.) But that is not the author's job, it
distracts them from getting the words down, and it ties the
information to the presentation medium they worked in.
If you want to stick with HTML, I strongly encourage you to rip
all the presentational markup out.
| DocBook strikes me as "quiet, reverent cathedral-building". (quotes are
| from the Cathedral and the Bazaar).
LOL! You weren't at some of the early meetings, I can tell<wink/>.
| Sorry, didn't mean it that way. IMHO, both Stylebook and Cocoon are
| dangerously
| close to having an "Official DTD". My evidence? How many alternate
| DTD's do we
| have? Few. How many site styles do we have? Few. And, all the styles
| that we do
| have look pretty much alike (hierarchical nav bar on the left,
| composited banner at
| the top, copyright at the bottom, etc.) I'd say that's strong evidence
| that we don't have
| ENOUGH diversity, ENOUGH randomness, and ENOUGH wasted energy, and we
| probably have
| too much Cathedral building going on here.
Are you arguing that we should encourage every project and every
team within every project, to customize the DTD to suit their
particular needs?
On the surface, perhaps that sounds like a good idea, because we
imagine that they will all produce sound, logical "perfect" DTDs
for thier domain. But I think it's a recipe for disaster.
Please accept the following statement as my humble opinion and
not as hubris or arrogance. Schema design is not self-evident,
it is a skill acquired through study and experience. Project
teams are not likely to have much experience in this area and
are likely to do the job badly. It would be much, much better if
they could be convinced to use a common vocabulary for as much
as was reasonable. There will naturally be some need for
customization in some projects, but it ought to be in the 20%
range, not the 80% range. IMHO.
| By the way, Zope appears to have the same exact problem. All the Zope
| sites look very similar.
| What does that tell us about Zope? (And, by analogy, Stylebook and
| Cocoon?)
Why on *earth* is it bad for sites to have a common interface to
documentation? Why would one intentionally confuse the poor
beleagured reader? By the same argument, we could propose that
some books should be printed front to back, some back to front,
some with all the even pages first and all the odd pages last,
etc., because all of our (our in an inclusive cultural sense, I
recognize that books vary across cultural and language
boundries) books for the last 500 years have looked about the
same and that must be a bad thing.
To which I reply, "Huh?"
Be seeing you,
norm
--
Norman Walsh <nd...@nwalsh.com> | Any bureaucracy reorganized to
http://nwalsh.com/ | enhance efficiency is
| indistinguishable from its
| predecessor.
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C
land and surroundings]
Posted by Pierpaolo Fumagalli <pi...@apache.org>.
Norman Walsh wrote:
>
> | 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...
>
> (c) the book is free, http://docbook.org/tdg/
Cool :) Thanks :) I didn't know it :) I'm off downloading it :)
Pier
--
----------------------------------------------------------------------
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]
Posted by Norman Walsh <nd...@nwalsh.com>.
/ Pierpaolo Fumagalli <pi...@apache.org> was heard to say:
| kids kidS kiDS kIDS KIDS... I'm asking... Why in the world are you
| _BOTH_ overreacting in that way??? We're talking about (sorry Norman) a
| stupid DTD...
(a) I thought this was an interesting discussion and that all
participating parties had done a fairly good job of not
overreacting despite fairly diverse opinions held rather
strongly and (b) you don't have to apologize to me for your
opinion.
| 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...
(c) the book is free, http://docbook.org/tdg/
Be seeing you,
norm
--
Norman Walsh <nd...@nwalsh.com> | Nearly every complex solution to a
http://nwalsh.com/ | programming problem that I have
| looked at carefully has turned out
| to be wrong.--Brent Welch
RE: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]
Posted by Gerard van Enk <ge...@eo.nl>.
> [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...]
>
Most of the time I perfectly understand what you're trying to say, and if
not the first time, I will after reading it 10 times!
Gerard
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C
land and surroundings]
Posted by Niclas Hedhman <ni...@localbar.com>.
Stefano Mazzocchi wrote:
> I proposed to choose DocBook for documentation because it includes
> authoring patterns solidified into a schema.
>
I have been following this pattern, and maybe I have missed some major point, but
isn't Stefano talking about Cocoon (and related) documentation??
If so, why is anyone arguing?
If Stefano is discussing DocBook outside the scope of Cocoon's documentation,
I would say it is at the most a recommendation, and each and everyone of us can
make the judgement whether this is any good, just as we can choose to use any
tool we want, such as Cocoon itself, or craft it by hand ourselves.
Regarding the general versus specialized DTDs, IMHO, it seems that people forget
one thing (except Pier who sits at that end).
Although it is possible to craft a different DTD for every single topic, and the
effort of doing so seems reasonable ( neglecting the fact that tag learning is
not trivial), there are more efforts on top of the DTD than the XML document.
Especially the XSLT for, let say, 5 different browsers (current situation) and
possibly another half dozen of handheld devices in the near future. If one can
not re-use these, content generation becomes a nightmare.
Niclas
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C
land and surroundings]
Posted by Stefano Mazzocchi <st...@apache.org>.
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
that...]
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Missed us in Orlando? Make it up with ApacheCON Europe in London!
------------------------- http://ApacheCon.Com ---------------------
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C
land and surroundings]
Posted by Pierpaolo Fumagalli <pi...@apache.org>.
Stefano Mazzocchi and Mike Pogue wrote:
>
> > 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".
>
> Oooh. You are heading away from the whole idea of the Bazaar here,
> which "resemble[s] a great babbling bazaar of differing agendas and
> approaches".
> DocBook strikes me as "quiet, reverent cathedral-building". (quotes are
> from the Cathedral and the Bazaar).
>
> > 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.
>
> Sorry, didn't mean it that way. IMHO, both Stylebook and Cocoon are
> dangerously close to having an "Official DTD". My evidence? How many
> alternate DTD's do we have? Few. How many site styles do we have? Few.
> And, all the styles that we do have look pretty much alike (hierarchical
> nav bar on the left, composited banner at the top, copyright at the bottom,
> etc.) I'd say that's strong evidence that we don't have ENOUGH diversity,
> ENOUGH randomness, and ENOUGH wasted energy, and we probably have too much
> Cathedral building going on here.
>
> It's not just Cocoon (hey, chill out, will ya?!), it's Stylebook, too
> (re-read my quote above -- I'm commenting on both of them).
kids kidS kiDS kIDS KIDS... I'm asking... Why in the world are you
_BOTH_ overreacting in that way??? We're talking about (sorry Norman) a
stupid DTD...
THE TOOLS ARE DTD-FREE... And you both know it... The point is: why did
noone came up with something different with Stylebook? Because it's
structure is SO COMPLICATED that it's easier to reuse the same shit over
and over (and I wrote that shit, so I know how it stinks!) than EVEN
THINKING about doing something different (I didn't do it twice! and I'm
the freakin' author of it!). Cocoon 2.0 addresses THAT SPECIFIC PROBLEM
I FOUND IN STYLEBOOK, and eases _so_much_ the creation process that
currently, in my Cocoon 2.0 talk I use more than 8 different
"approaches" to solve the same problem... XML publication.
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!)
--
----------------------------------------------------------------------
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]
Posted by Norman Walsh <nd...@nwalsh.com>.
/ Donald Ball <ba...@webslingerZ.com> was heard to say:
| I will say, though - one of the things that irritates me about "new media"
| like Wired magazine is the way they screw with traditional layout rules.
| Sure, it's fun to be hip and different, but those layout rules evolved
| because they proved to be an effective way to convey information, and not
| obeying those rules makes the information parsing task more difficult for
| the reader.
Amen.
Be seeing you,
norm
--
Norman Walsh <nd...@nwalsh.com> | Man's sensitivity to little things
http://nwalsh.com/ | and insensitivity to the greatest
| are the signs of a strange
| disorder.--Pascal
Re: Documentation grammars, was:[Re: [RT] latest wonderings around
W3C land and surroundings]
Posted by Donald Ball <ba...@webslingerZ.com>.
On Fri, 31 Mar 2000, Mike Pogue wrote:
> > 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.
>
> Sorry, didn't mean it that way. IMHO, both Stylebook and Cocoon are
> dangerously close to having an "Official DTD". My evidence? How many
> alternate DTD's do we have? Few. How many site styles do we have?
> Few. And, all the styles that we do have look pretty much alike
> (hierarchical nav bar on the left, composited banner at the top,
> copyright at the bottom, etc.) I'd say that's strong evidence that we
> don't have ENOUGH diversity, ENOUGH randomness, and ENOUGH wasted
> energy, and we probably have too much Cathedral building going on
> here.
>
> It's not just Cocoon (hey, chill out, will ya?!), it's Stylebook, too
> (re-read my quote above -- I'm commenting on both of them).
Hold up. You're saying that cocoon is close to having an official DTD. I
hope you mean strictly for internal documentation. If so, then what's the
problem? We have to agree on a common language or else we can't
communicate effectively. If you have suggestions for altering the DTD (and
documentation to contribute that can only be expressed in the new DTD),
speak up by all means, we're all ears.
If you mean that sites that use cocoon all share the same style - I beg to
differ. I've deployed at least half a dozen sites that use cocoon to style
part or all of themselves, and they differ wildly from each other, both in
terms of internal DTD and in terms of the interface they present to the
user.
If you're saying that the web as a whole has too few site styles - well,
your criticism isn't of cocoon, then, but the web publishing industry as a
whole. However, site navigation strategies evolved to the handful of
paradigms we see today because those were the most effective given the
constraints of the era. Perhaps as the constraints change (as we are given
new tools like cocoon) more successful strategies will evolve. We'll see.
I will say, though - one of the things that irritates me about "new media"
like Wired magazine is the way they screw with traditional layout rules.
Sure, it's fun to be hip and different, but those layout rules evolved
because they proved to be an effective way to convey information, and not
obeying those rules makes the information parsing task more difficult for
the reader.
Final bit of rant, completely offtopic - what is it with this bazaar v.s.
cathedral dichotomy? How come there's only room for two programming
methodologies, and how come the "cathedral builder" cry is viewed so
negatively? I would suggest that the cocoon project sometimes favors the
monastary approach. The bazaar is a great place to share and test ideas
but a terrible place to develop them - too noisy and crowded. Sometimes we
need to retreat to the monastary to work on a problem in some peace and
quiet before it's ready to face the competitive world of the bazaar.
- donald should be doing work right about now
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C
land and surroundings]
Posted by Mike Pogue <mp...@apache.org>.
Stefano Mazzocchi wrote:
> > > | 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.
Yes. However, although <p> and <paragraph> are equivalent from a
programmer's point of view (e.g. one can always be transformed into the
other), they are not equivalent from a technical writer's point of view.
> >
> > > | 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.
It's a minor point. Let me use an example: If we created a new grammar
"SML" for Shoe Markup Language,
and then wrote an editor for it (an emacs hack, say), and then declared
"see -- the problem
is solved!", I think we would get some disagreement on that.
In Computer Science we tend to do this:
GOAL: to prove that something is true, e.g. "DocBook needs to be
easily editable"
step 1) create one instance of it e.g. "I have created a DocBook mode
in emacs"
step 2) declare victory e.g. "therefore, everybody can now use
DocBook, Q.E.D."
However, in the Real World (in my humble experience), one instance is
not sufficient to solve the problem. We generally end up with solutions
like "you can use any editor you want".
This is a minor point, so I wouldn't get stuck on it.
> > > | 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!
I think I can say it clearest by saying that DocBook is a "Software
Documentation Markup Language", it's not a "Shoe Documentation Markup
Language" or a "Open Source XML Parser Documentation Markup Language".
And, it's not clear to me that all things in Shoe Documentation Markup
Language can be represented in Software Documentation Markup Language (I
think there's likely to be an information loss. Therefore, I conclude
two things, that:
a) DocBook might not be the best initial representation language, if
you are an Open Source XML Parser Documentation writer, (e.g. the best
language
for Open Source XML Parser Documentation might be OSXPDML, rather than
DocBook) and
b) DocBook might not make a good intermediate language (lingua franca)
in the pipeline.
> 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".
>
True. Some things could be common, like <p> and <ul> and <table>. But,
lots of
other things won't be, like <size> and <manufacturer> and <property>.
This argues for
factoring of grammars, something that people are working on, but the
results are not
really widespread yet.
> 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.
That's ironic! We both agree here. I'm suggesting that we reuse HTML,
you're suggesting that we reuse DocBook. (NOTE: I initially suggested
Docbook, but
I was voted down by technical writers and engineers alike, because in a
contest
between DocBook and HTML, HTML wins. I have to agree that they have a
point! :-)
> 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.
Right, so stick with the HTML DTD, for those tags that can do so! ;-)
;-)
> 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".
Oooh. You are heading away from the whole idea of the Bazaar here,
which
"resemble[s] a great babbling bazaar of differing agendas and
approaches".
DocBook strikes me as "quiet, reverent cathedral-building". (quotes are
from the Cathedral and the Bazaar).
Forking is not Bad. It's not necessarily bad to "waste" some resources,
as long
as not all of your resources are wasted. [Side note for Computer
Science
geeks: note the analogy to hill climbing and simulated annealing
algorithms, which
require some "wasted" random effort to function well, or at all]
> 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.
Sorry, didn't mean it that way. IMHO, both Stylebook and Cocoon are
dangerously
close to having an "Official DTD". My evidence? How many alternate
DTD's do we
have? Few. How many site styles do we have? Few. And, all the styles
that we do
have look pretty much alike (hierarchical nav bar on the left,
composited banner at
the top, copyright at the bottom, etc.) I'd say that's strong evidence
that we don't have
ENOUGH diversity, ENOUGH randomness, and ENOUGH wasted energy, and we
probably have
too much Cathedral building going on here.
It's not just Cocoon (hey, chill out, will ya?!), it's Stylebook, too
(re-read my quote above -- I'm commenting on both of them).
By the way, Zope appears to have the same exact problem. All the Zope
sites look very similar.
What does that tell us about Zope? (And, by analogy, Stylebook and
Cocoon?)
Mike
> --
> Stefano Mazzocchi One must still have chaos in oneself to be
> able to give birth to a dancing star.
> <st...@apache.org> Friedrich Nietzsche
> --------------------------------------------------------------------
> Missed us in Orlando? Make it up with ApacheCON Europe in London!
> ------------------------- http://ApacheCon.Com ---------------------
Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C
land and surroundings]
Posted by Stefano Mazzocchi <st...@apache.org>.
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 <mp...@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.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Missed us in Orlando? Make it up with ApacheCON Europe in London!
------------------------- http://ApacheCon.Com ---------------------