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

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

Peter Ring <PRI@magnus.dk>, 2007-02-23 10:23 +0100:

> Camille B�«±gnis wrote:
> > 
> > Rationale: When our clients come to docbook they are frightened by the
> > number of elements. So we provide them with a limited list so they can
> > get started. But while they start learning new elements they realize
> > they should have called that element <preface> rather than <chapter>.
> > And it's easier to add an attribute to specialize the element rather
> > than renaming it, possibly with content model issues.
> > 
> 
> I'd second that, i.e., favor generic elements that can be
> specialized by adding child nodes (attributes and elements) --
> without changing the element name.
> 
> I also happen to like <systemitem>. A <systemitem
> class="library"> is 'a kind of' or 'an extension of'
> <systemitem>;

And what exactly is a systemitem? Where, outside of the DocBook
community, is the term "system item" familiar to anybody, or where
does it have any kind of documented meaning?

It seems to me that systemitem@library simply forces users to
consider a library as a "kind of" or "extension of" a class of
things that are not necessarily intuitively related to each other
at all -- the class that we're using the invented name
"systemitem" for.

How are we expecting users to discover that we have classified a
library as a class of a "system item"?

For the situation where we have a new user who wants to mark up,
say, both a constant and a username or a constant and and IP
address, we are expecting the user to do ... what. Say to himself,
OK, those are both classes of things that are used on a system, so
I guess I should maybe I should find an element that starts with
the name "system"?

How likely is it that a user is going to do that, as opposed to
doing the intuitive thing of looking for an element called
Username or Contast or IPAddress?

> the proliferation of @class values is just a reflection of the
> number of system-related terms that have similar behavior.

No, it's simply a reflection of that fact that we have chosen to
classify all 22 of those things as "system-related terms"
(whatever that means). And how the behavior of a constant similar
to the behavior of a library or a username>

> To the extent that a number of elements have similar content
> models and similar processing expectations, it is a moot point
> whether you say <gi class="special">...</gi> or
> <gi><special/>...</gi> or <special>...</special>, cf. "Should I
> use elements or attributes to store data?" [1].

No, it's not very far from being a moot point. At least not to
users. Users who wants to mark up a certain piece of information
intuitively go looking for an element name that matches the name
of the type of information they want to mark up. They do not go
looking for an element with the name: [insert invented element
name with with you've chosen to classify a set of things that
users may or may not consider to be similar or related].

The big difference is that with the @class approach, you are
forcing your classification scheme on users, and requiring them to
learn and adopt it in order to mark up their content. By providing
elements instead, your not forcing any particular classfication
scheme on users, and they choice of how they want to consider
semantic relationships among the elements is instead left up to them.

  --Mike

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