DOCBOOK: Contents vs. contexts in schemas

["Eve L. Maler" <elm at east dot sun dot com>]

At the DocBook meeting in Philly a few weeks ago, I promised to post to 
this list my DocBook-related examples of "complex types" vs. "equivalence 
classes" in XML Schemas.

In DocBook, there are elements that share the same model by design, and 
there are elements that share the same available contexts (places they're 
allowed in other content models) by design.  The ones that share the same 
model contain a reference to a parameter entity (usually *.content or 
*.mix) in their content model, whereas the ones that share the same 
contexts _appear in_ the definition of a *.class parameter entity, which 
then gets used in various other content models.

Example 1:

Element name             Contents                      Contexts
============             ========                      ========
variablelist             title stuff, varlistentry+    with lists
itemizedlist             listitem+                     with lists
orderedlist              listitem+                     with lists

Example 2:

Element name             Contents                      Contexts
============             ========                      ========
synopsis                 para.char.mix etc.            with synopses
cmdsynopsis              command etc.                  with synopses
productname              para.char.mix                 with doc info
programlisting           para.char.mix etc.            with informals

In example 1, you want the elements that are "semantically" lists available 
in all the same places, so that authors can choose among them when deciding 
how to encode their content.  But syntactically, the list elements are 
pretty different: numbered and unnumbered plain lists have the same 
internal structure, but two-part lists don't.  Same thing in example 2: 
Even though the synopses are structured radically differently, you want 
them available in the same locations.  And things that happen to have the 
same or similar contents as, say, a plain synopsis may be very different 
creatures.

In a schema, you could set up a complex type called, say, 
"enumerates-with-items" that offers a standard content model of 
listitem+.  Then itemizedlist and orderedlist could be based on the 
enumerates-with-items type, thus keeping their definitions in sync and 
allowing for applications to specify formatting or other behavior for all 
"enumerates-with-items" elements at once.

You could also set up a "lists" equivalence class and make variablelist, 
itemizedlist, and orderedlist members of that class.  It wouldn't keep 
anything in sync regarding the definitions of these elements, but it would 
allow them to be referenced from content models as a choice group.  And 
again, it would allow for applications to specify formatting or other 
behavior for all "list" elements at once.

The kinds of formatting/behavior you'd apply to types would tend to be 
"internal": indents, font, etc.  On the other hand, the kinds of 
formatting/behavior you'd apply to equivalence classes would tend to be 
"external": whether the content is wrapped with its surroundings or 
vertically set off, how much vertical spacing to use, etc.

The argument for having types and equivalence classes at all, rather than 
entities, is that the name of the type/class hangs around after its 
referenced content model (or whatever) has been resolved.  This means you 
can attach processing to it.  The argument for having hierarchically 
defined types and classes is that you can reuse and specialize your 
processing code just the same way you reuse and specialize your type/class 
definitions.

	Eve
--
Eve Maler            Sun Microsystems
elm @ east.sun.com    +1 781 442 3190