cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Pogue <mpo...@apache.org>
Subject Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]
Date Thu, 30 Mar 2000 23:34:06 GMT
Norman Walsh wrote:
> 
> / Mike Pogue <mpogue@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 <ndw@nwalsh.com>      | Man's sensitivity to little things
> http://nwalsh.com/                 | and insensitivity to the greatest
>                                    | are the signs of a strange
>                                    | disorder.--Pascal

Mime
View raw message