Re: [docbook-apps] Please respond: adding generic sibling to high-level book components

["Michael(tm) Smith" <smith@sideshowbarker.net>]

Camille B�«±gnis <camille@neodoc.biz>, 2007-02-15 20:06 +0100:

> Scott Hudson a �«±crit :
> 
> [...]
> 
> > Another consideration was a more general element that
> > could use a class attribute to distinguish between them. For example,
> > class="dedication" and class="acknowledgements" and perhaps others.
> > 
> > In this way, we could potentially consolidate some of these existing
> > front and back matter elements, while providing a generic structure to
> > meet future needs without having to adopt new elements.
> > 
> > What would you call such a structure?
> 
> I have no preference, but I am in favor of this suggestion, and any
> solution that stops the growth of DocBook elements...

The approach of adding a single element with a class attribute
having multiple enumerated values grows the schema just as much as
instead adding a corresponding new element were added for each of
the attribute values. It arguably makes things harder for users
because it basically just hides the additional complexity in a way
that makes it hard for users to find what they're looking for.

A case in point is the current systemitem content model, with 22
enumerated values on its class attribute:

  http://docbook.org/tdg/en/html/systemitem.html

So a users who want to, say, mark up a username or constant or an
IP address and goes looking through the docs for, well, a Username
element or a Constant element will find none. They are instead
expected to figure out (somehow) that the element they need is
Systemitem, with one of its mixed-bag of values on its class
attribute, which are actually only marginally related to each
other through the vague notion of being "system-related items".

I mean, if you were to ask somebody for an common-sense opinion
about how a constant and a username should be marked up in a
schema for technical documentation, I don't think most would
suggest that the same element should be used to mark them up, with
a class attributes on that element being the only thing used to
distinguish between them.

  --Mike

-- 
Michael(tm) Smith
http://people.w3.org/mike/