Re: [docbook] making macros

[Chuck Robey <chuckr@chuckr.org>]

Rowland, Larry wrote:

>Perhaps part of the confusion is from a misunderstanding about DocBook;
>DocBook is not a low-level language.  TROFF (and NROFF and GROFF) are
>all low-level typesetting languages.  The macro packages provide the
>level of abstraction necessary for efficiently producing documentation.
>The ROFFs themselves are almost like "machine code."  
>
>DocBook is a high-level, structured, semantic markup.  It is already
>performing the same class of operations that things like the mm and man
>macro packages do for the *roff languages (and frequently providing an
>even higher level of abstraction).  With a half decent syntax driven
>editor there is little need for additional macros; instantiating a new
>element populates it with any necessary children and positioning the
>cursor inside an element provides a description of the content model
>(permitted elements).  
>
>People working in high-level markups are not as likely to feel the need
>for the macro packages, since the language itself provides much of the
>semantic abstraction that the macro packages provide in lower level
>languages.
>
>It is worth the time to study the examples provided for the higher-level
>elements in "DocBook: The Definitive Guide," to see how the pieces go
>together.  Another productive exercise is to get a good XML editor and
>experiment with the structure yourself: start with book or chapter or
>article and create a sample document similar to those you are thinking
>about creating.  Look at things like procedures, examples, variablelist
>and table to see how the pieces work together.  With structured markups,
>understanding the hierarchical structure relationships is key.
>
>  
>
It's possible, I'm going back to reading again.  I have had enough 
response from this list now, to make me think my basic architectural 
idea might be right, but I need to spend at least SOME more time on 
docbook.  Right now, it seems too huge, to be a directly useful tool 
(which is what I wanted to find a way around by using an artificial set 
of elements (implemented in a set of xslt macros, or what I think of as 
macros).  I'm convinced now that most of the original complaints I heard 
were because some folks with less of a programming ouotlook 
misunderstood  me (or I provoked it, since our two backgrounds are too 
different, I guess).

I'll admit that the purpose of the macros in troff is somewhat different 
than the problem I wanted to correct; in troff, it was to organize more 
higher-level commands.  In docbook, I think of it as allowing me to see 
a smaller set of more often used commands.

Anyhow, I need to read more, definitely.  I'm beginning to be worried I 
might be getting close to asking folks to do my work for me, and that 
scares me, I would be VERY embarrassed at that idea.
That came to me from some of Per Bothner's comments, though he didn't 
say it directly..