Re: [docbook] Elements versus Attributes

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

Camille B�«±gnis <camille@neodoc.biz>, 2006-10-27 10:49 +0200:

> When designing an XML grammar, an obvious rule seem to use different
> element names if they have different content models.

But that doesn't imply a rule that different element names should
not be used for elements that have the same content model.

> Attributes can be used to further specialize elements.

The can be, but it doesn't mean they should be just because they can.

> However DocBook goes beyond this: the example of admonitions is
> striking: 5 elements (db.caution | db.important | db.note | db.tip |
> db.warning) with exact same content model.[1]

What's so striking about it? Five different elements that have
five different meanings (though they are all types of admonitions).

> I wonder why not using a class or type attribute (what's the difference
> between these btw?).

The class attribute is supposed to always have an preset enumerated
list of values. The value of the type attribute is text.

Anyway, I guess it's always arguable whether having <note
class="warning"> and <note class="tip"> would be better or worse
than having <warning> and <tip>. I think have warning and tip as
elements make things easier for users, but I can't claim I have
any research to support that.

> In short, is there a document somewhere that explains, even quickly, the
> designing principles behind DocBook?

"Developing SGML DTDs: From Text to Model to Markup" by Eve Maler
and Jeanne El Andaloussi is the closest thing I've ever come
across. I think Eve did a lot of work on the redesign of DocBook
at the time of DocBook 2.0, and that some of the ideas behind it
are reflected in that book.

There is otherwise not much of a record of the rationale behind
some of the design decisions that went into DocBook back in the
day. There's an archive of Davenport Group mailing-list
discussions here:

  http://docbook.sourceforge.net/archive/ftp.ora.com/pub/davenport/archive/

And some archived copies of docs and DTDs for DocBook v1 and v2.

  --Mike

Digital signature