cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Norman Walsh <...@nwalsh.com>
Subject Re: Documentation grammars, was:[Re: [RT] latest wonderings around W3C land and surroundings]
Date Fri, 31 Mar 2000 05:37:32 GMT
/ Mike Pogue <mpogue@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 <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

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | One must look for one thing only,
http://nwalsh.com/                 | to find many.--Cesare Pavese


Mime
View raw message