Re: [docbook] making macros

["Rowland, Larry" <larry.rowland@hp.com>]

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.

-- 
=======================================================================
[ Larry Rowland             | If you want to build a ship, don't drum ]
[ ATCL                      | up the men to gather the wood, divide   ]
[ Hewlett-Packard           | the work, and give orders. Instead,     ]
[ 3404 East Harmony Road    | teach them to yearn for the vast and    ]
[ Fort Collins, CO  80528   | endless sea. - Antoine de Saint Exupery ]
[ Phone: 970/898-2280       +-----------------------------------------]
[ FAX:   970/898-2188   E-Mail:larry.rowland@.hp.com                  ]
=======================================================================