OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

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:


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.


Michael(tm) Smith

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]