Re: Elements versus Attributes

[Norman Walsh <ndw@nwalsh.com>]

/ Camille BĂ©gnis <camille@neodoc.biz> was heard to say:
| When designing an XML grammar, an obvious rule seem to use different
| element names if they have different content models. Attributes can be
| used to further specialize elements.
|
| 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]

Right. In the DTD world, there are two reasons for giving elements
different names. One is if they have different content models. The
other is if they have semantics that are different and the distinction
is sufficiently important that you want to be able to control where
they can *appear* in content models.

In the case of admonitions, some places have very strict rules about
what constitutes a warning, a caution, and an important note. For
example, <warning> is used exclusively when there is the possibility
of death or injury to the operator; <caution> is used exclusively when
there is the possibility of damage to equipment, etc.

Under these circumstances, you might very well want to enforce the
rule that a warning *must not* occur in a preface. By giving the
element a different name, you can do that.

There are lots of places where the names don't serve technical needs,
they serve the needs of authors: chapter|preface|appendix could all be
"bigchunk" with a class attribute; almost all the inlines could be
"inline" with a class attribute; etc.

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

Class attributes have discrete, enumerated values. Type attributes are
open-ended. (Note, there are a few places where this rule isn't
followed, but those are accidents.)

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

Not really. There probably should be, but not having done it a decade
a ago, it's a little difficult to back-form now. It's also, honestly,
the case that there are enough exceptions in DocBook, motivated by
perceived needs at the time, that there probably aren't many design
principles that you could articulate that we've never violated. I
can't think of any rational design principles that would have allowed
msgset to get into the DTD while precluding a whole bunch of other
stuff that we have rejected.

The best I can say is that DocBook represents the collected wisdom of
a bunch of smart folks with exceptional markup design skills and a few
hundred years of combined technical publishing experience.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Wherever they burn books they will
http://www.oasis-open.org/docbook/ | also, in the end, burn human
Chair, DocBook Technical Committee | beings.-- Heine

PGP signature