DOCBOOK: On the size of DocBook...

[Norman Walsh <ndw at nwalsh dot com>]

The recent thread about DocBook and LaTeX raised the issue of the size
of DocBook (measured as the number of elements). (It's not the first
thread to raise the issue, just the most recent.)

Certainly one of the complaints that new users make about DocBook is that
it's "too big". At the "paragraph level", the list is pretty daunting:

(calloutlist|glosslist|itemizedlist|orderedlist|segmentedlist|
 simplelist|variablelist|caution|important|note|tip|warning|
 literallayout|programlisting|programlistingco|screen|screenco|
 screenshot|synopsis|cmdsynopsis|funcsynopsis|classsynopsis|
 fieldsynopsis|constructorsynopsis|destructorsynopsis|
 methodsynopsis|formalpara|para|simpara|address|blockquote|
 graphic|graphicco|mediaobject|mediaobjectco|informalequation|
 informalexample|informalfigure|informaltable|equation|example|
 figure|table|msgset|procedure|sidebar|qandaset|productionset|
 constraintdef|anchor|bridgehead|remark|highlights|abstract|
 authorblurb|epigraph|indexterm|beginpage)+

And it's worse at the paragraph level:

(#PCDATA|footnoteref|xref|abbrev|acronym|citation|citerefentry|
 citetitle|emphasis|firstterm|foreignphrase|glossterm|footnote|
 phrase|quote|trademark|wordasword|personname|link|olink|ulink|
 action|application|classname|methodname|interfacename|
 exceptionname|ooclass|oointerface|ooexception|command|
 computeroutput|database|email|envar|errorcode|errorname|
 errortype|errortext|filename|function|guibutton|guiicon|guilabel|
 guimenu|guimenuitem|guisubmenu|hardware|interface|keycap|keycode|
 keycombo|keysym|literal|constant|markup|medialabel|menuchoice|
 mousebutton|option|optional|parameter|prompt|property|
 replaceable|returnvalue|sgmltag|structfield|structname|symbol|
 systemitem|token|type|userinput|varname|nonterminal|anchor|
 author|authorinitials|corpauthor|modespec|othercredit|
 productname|productnumber|revhistory|remark|subscript|
 superscript|inlinegraphic|inlinemediaobject|inlineequation|
 synopsis|cmdsynopsis|funcsynopsis|classsynopsis|fieldsynopsis|
 constructorsynopsis|destructorsynopsis|methodsynopsis|indexterm|
 beginpage|calloutlist|glosslist|itemizedlist|orderedlist|
 segmentedlist|simplelist|variablelist|caution|important|note|tip|
 warning|literallayout|programlisting|programlistingco|screen|
 screenco|screenshot|address|blockquote|graphic|graphicco|
 mediaobject|mediaobjectco|informalequation|informalexample|
 informalfigure|informaltable|equation|example|figure|table)*

Whenever I think of adding new elements to DocBook, I think about
these content models and wonder if it's really worth it. Now, in a
sense, this is completely unfair. It's quite possible that the
proposed element is just as valuable, to someone certainly and to
everyone maybe, as, say "errorcode". The fact that errorcode got there
first doesn't seem like a very satisfying criteria on which to choose
between them.

Simplified DocBook is really a much more manageable size,
offering:

(itemizedlist|orderedlist|variablelist|note|literallayout|
 programlisting|para|blockquote|mediaobject|informaltable|
 example|figure|table|sidebar|abstract|authorblurb|epigraph)+

and

(#PCDATA|footnoteref|xref|abbrev|acronym|citetitle|emphasis|
 footnote|phrase|quote|trademark|link|ulink|command|
 computeroutput|email|filename|literal|option|replaceable|
 systemitem|userinput|inlinemediaobject)*

respectively.

The problem, of course, is that for any given document, one probably
needs Simplified DocBook plus a half-dozen other elements from
DocBook.

A few things occur to me.

1. The difference between 400 elements and 800 elements isn't
significant, just add 'em all.

2. 400 is just too many, we need to make DocBook smaller.

3. Some sort of "pizza cutter" a la TEI could be invented to allow
selection of "just the right" elements. (But what will that do to
interchange?!)

4. Refactoring the parameter entity structure in a more satisfying way
might make it easier to customize which would offer some sort of a
compromise between 1 and 3.

Any thoughts?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | The sense of existence is the
http://www.oasis-open.org/docbook/ | greatest happiness.--Benjamin
Chair, DocBook Technical Committee | Disraeli