DOCBOOK: Modularity and PE reorganization

[Norman Walsh <ndw at nwalsh dot com>]

I spent some time this weekend with several hundred little slips of
paper[1] making a stab at a more logical set of parameter entities (or
at least, of classes) for DocBook. At the same time, I considered what
sets of elements might be grouped as modules.

The following document is my first stab at describing the results. I
make no claims that any of this will ever get finished or survive in
any form. I'm just exploring.

I think the psuedo-RELAX NG syntax will ultimately be useful as a
source for generating concrete realizations of DocBook with specific
modules selected. Actually, this little schema-description language
looks like an exciting project in its own right.

<schema-description xmlns:in="http://nwalsh.com/xmlns/inclusions";
                    xmlns:ex="http://nwalsh.com/xmlns/exclusions";
                    xmlns:min="http://nwalsh.com/xmlns/minimizations";
                    min:start="-"
                    min:end="o">

  <module name="link"/>
  <module name="olink"/>
  <module name="anchor"/>
  <module name="section"/>
  <module name="sectn"/>
  <module name="simplesect"/>
  <module name="admonition"/>
  <module name="math"/>
  <module name="gui"/>
  <module name="keyboard"/>
  <module name="callout"/>
  <module name="synopsis"/>
  <module name="verbatim"/>
  <module name="oo-programming"/>
  <module name="refentry"/>
  <module name="table"/>
  <module name="htmltable"/>
  <module name="programming"/>
  <module name="error"/>
  <module name="product"/>
  <module name="os"/>
  <module name="markup"/>
  <module name="bridgehead"/>
  <module name="metadata"/>
  <module name="publishing"/>
  <module name="legacy"/>
  <module name="list"/>
  <module name="segmentedlist"/>
  <module name="simplelist"/>
  <module name="procedure"/>
  <module name="glossary"/>
  <module name="bibliography"/>
  <module name="releaseinfo"/>
  <module name="qanda"/>
  <module name="credits"/>
  <module name="personname"/>
  <module name="address"/>
  <module name="toc-lot"/>
  <module name="ebnf"/>
  <module name="alt-para"/>
  <module name="svg"/>
  <module name="htmlform"/>
  <module name="affiliation"/>
  <module name="collab"/>
  <module name="contract"/>
  <module name="partnumber"/>
  <module name="msgset"/>
  <module name="indexing"/>
  <module name="indexes"/>
  <module name="conference"/>
  <module name="keyword"/>
  <module name="graphic"/>
  <module name="book"/>
  <module name="set"/>
  <module name="formal"/>
  <module name="informal"/>
  <module name="remark"/>

  <class name="technical.inlines.class">
    <ref name="replaceable"/>
    <ref name="systemitem"/>
    <ref name="option"/>
    <ref name="optional"/>
  </class>

  <class name="error.inlines.class">
    <ref name="errocode"/>
    <ref name="errortext"/>
    <ref name="errorname"/>
    <ref name="errortype"/>
  </class>

  <class name="programming.inlines.class">
    <ref name="function"/>
    <ref name="parameter"/>
    <ref name="varname"/>
    <ref name="returnvalue"/>
    <ref name="type"/>
  </class>

  <class name="product.inlines.class">
    <ref name="productnumber"/>
    <ref name="productname"/>
    <ref name="database"/>
    <ref name="application"/>
    <ref name="hardware"/>
    <ref name="trademark"/>
  </class>

  <class name="os.inlines.class">
    <ref name="prompt"/>
    <ref name="envar"/>
    <ref name="filename"/>
    <ref name="command"/>
    <ref name="computeroutput"/>
    <ref name="userinput"/>
  </class>

  <class name="markup.inlines.class">
    <ref name="sgmltag"/>
    <ref name="markup"/>
    <ref name="token"/>
    <ref name="symbol"/>
    <ref name="literal"/>
    <ref name="constant"/>
  </class>

  <class name="bibliography.inlines.class">
    <ref name="citation"/>
  </class>

  <class name="glossary.inlines.class">
    <ref name="glossterm"/>
    <ref name="firstterm"/>
  </class>

  <class name="publishing.inlines.class">
    <ref name="superscript"/>
    <ref name="citetitle"/>
    <ref name="bibliography.inlines.class"/>
    <ref name="glossary.inlines.class"/>
    <ref name="citerefentry"/>
    <ref name="footnote"/>
    <ref name="foreignphrase"/>
    <ref name="emphasis"/>
    <ref name="phrase"/>
    <ref name="footnoteref"/>
    <ref name="subscript"/>
    <ref name="quote"/>
    <ref name="acronym"/>
    <ref name="wordasword"/>
    <ref name="abbrev"/>
    <ref name="coref"/>
  </class>

  <class name="list.class">
    <ref name="itemizedlist"/>
    <ref name="orderedlist"/>
    <ref name="variablelist"/>
    <ref name="segmentedlist"/>
    <ref name="simplelist"/>
    <ref name="calloutlist"/>
    <ref name="segmentedlist"/>
  </class>

  <class name="procedure.class">
    <ref name="procedure"/>
  </class>

  <class name="core.info.class">
    <ref name="abstract"/>
    <ref name="artpagenums"/>
    <ref name="bibliocoverage"/>
    <ref name="biblioid"/>
    <ref name="bibliosource"/>
    <ref name="copyright"/>
    <ref name="edition"/>
    <ref name="issuenum"/>
    <ref name="legalnotice"/>
    <ref name="pagenums"/>
    <ref name="pubdate"/>
    <ref name="publisher"/>
    <ref name="publishername"/>
    <ref name="seriesvolnums"/>
    <ref name="volumenum"/>
  </class>

  <class name="legacy.info.class">
    <ref name="modespec"/>
    <ref name="issn"/>
    <ref name="isbn"/>
  </class>

  <class name="legacy.inlines.class">
    <ref name="structname"/>
    <ref name="structfield"/>
    <ref name="inlinegraphic"/>
    <ref name="medialabel"/>
    <ref name="interface"/>
    <ref name="action"/>
    <ref name="property"/>
  </class>

  <class name="legacy.class">
    <ref name="highlights"/>
    <ref name="graphic"/>
    <ref name="screenshot"/>
  </class>

  <class name="math.class">
    <ref name="equation"/>
    <ref name="informalequation"/>
  </class>

  <class name="math.inlines.class">
    <ref name="inlineequation"/>
  </class>

  <class name="tables.class">
    <ref name="tablen"/>
    <ref name="informaltable"/>
  </class>

  <class name="publishing.class">
    <ref name="example"/>
    <ref name="informalexample"/>
    <ref name="figure"/>
    <ref name="informalfigure"/>
    <ref name="math.class"/>
    <ref name="tables.class"/>
    <ref name="graphics.class"/>
    <ref name="blockquote"/>
    <ref name="sidebar"/>
  </class>

  <class name="graphics.class">
    <ref name="mediaobject"/>
    <ref name="mediaobjectco"/>
    <ref name="graphic"/>
    <ref name="graphicco"/>
  </class>

  <class name="graphic.inlines.class">
    <ref name="inlinemediaobject"/>
    <ref name="inlinegraphic"/>
  </class>

  <class name="para.class">
    <ref name="para"/>
    <ref name="simpara"/>
    <ref name="formalpara"/>
  </class>

  <class name="book.class">
    <ref name="book"/>
  </class>

  <class name="dedication.class">
    <ref name="dedication"/>
  </class>

  <class name="preface.class">
    <ref name="preface"/>
  </class>

  <class name="part.class">
    <ref name="part"/>
  </class>

  <class name="reference.class">
    <ref name="reference"/>
  </class>

  <class name="chapter.class">
    <ref name="chapter"/>
  </class>

  <class name="appendix.class">
    <ref name="appendix"/>
  </class>

  <class name="article.class">
    <ref name="article"/>
  </class>

  <class name="conference.info.class">
    <ref name="conftitle"/>
    <ref name="confdates"/>
    <ref name="confsponsor"/>
    <ref name="confgroup"/>
    <ref name="confnum"/>
  </class>

  <class name="keyword.info.class">
    <ref name="keywordset"/>
    <ref name="subjectset"/>
  </class>

  <class name="indexing.inlines.class">
    <ref name="indexterm"/>
  </class>

  <class name="partnumbers.inlines.class">
    <ref name="pubsnumber"/>
    <ref name="invpartnumber"/>
  </class>

  <class name="contract.info.class">
    <ref name="contractsponsor"/>
    <ref name="contractnumber"/>
  </class>

  <class name="ebnf.class">
    <ref name="constraintdef"/>
    <ref name="production"/>
    <ref name="productionset"/>
    <ref name="productionrecap"/>
  </class>

  <class name="ebnf.inlines.class">
    <ref name="nonterminal"/>
  </class>

  <class name="credits.info.class">
    <ref name="author"/>
    <ref name="editor"/>
    <ref name="authorgroup"/>
    <ref name="corpauthor"/>
    <ref name="othercredit"/>
  </class>

  <class name="oo-prog.inlines.class">
    <ref name="initializer"/>
    <ref name="interfacename"/>
    <ref name="methodname"/>
    <ref name="classname"/>
    <ref name="modifier"/>
    <ref name="ooexception"/>
    <ref name="oointerface"/>
    <ref name="exceptionname"/>
    <ref name="ooclass"/>
  </class>

  <class name="oo-prog.class">
    <ref name="destructorsynopsis"/>
    <ref name="classsynopsis"/>
    <ref name="constructorsynopsis"/>
    <ref name="methodsynopsis"/>
    <ref name="fieldsynopsis"/>
  </class>

  <class name="verbatim.class">
    <ref name="programlisting"/>
    <ref name="programlistingco"/>
    <ref name="screen"/>
    <ref name="screenco"/>
    <ref name="literallayout"/>
  </class>

  <class name="synopsis.class">
    <ref name="synopsis"/>
    <ref name="funcsynopsis"/>
    <ref name="cmdsynopsis"/>
  </class>

  <class name="gui.inlines.class">
    <ref name="guiicon"/>
    <ref name="guibutton"/>
    <ref name="guimenuitem"/>
    <ref name="guimenu"/>
    <ref name="guisubmenu"/>
    <ref name="guilabel"/>
    <ref name="menuchoice"/>
    <ref name="mousebutton"/>
  </class>

  <class name="keyboard.inlines.class">
    <ref name="keycombo"/>
    <ref name="keycap"/>
    <ref name="keycode"/>
    <ref name="keysym"/>
    <ref name="shortcut"/>
    <ref name="accell"/>
  </class>

  <class name="admonition.class">
    <ref name="note"/>
    <ref name="tip"/>
    <ref name="important"/>
    <ref name="warning"/>
    <ref name="caution"/>
  </class>

  <class name="link.inlines.class">
    <ref name="xref"/>
    <ref name="ulink"/>
    <ref name="link"/>
    <ref name="olink"/>
    <ref name="anchor"/>
  </class>

  <class name="nav.class">
    <ref name="toc"/>
    <ref name="lot"/>
    <ref name="index"/>
    <ref name="glossary"/>
    <ref name="bibliography"/>
  </class>

  <class name="object.descriptions.class">
    <ref name="abstract"/>
    <ref name="epigraph"/>
  </class>

  <class name="section.class">
    <ref name="section"/>
  </class>

  <class name="sect1.class">
    <ref name="section"/>
  </class>

  <class name="form.class">
    <ref name="html-form"/>
  </class>

  <class name="form.inlines.class">
    <ref name="html-input"/>
    <ref name="html-button"/>
    <ref name="html-label"/>
    <ref name="html-select"/>
    <ref name="html-textarea"/>
  </class>

  <!-- ====================================================================== -->

  <mixture name="info.mix">
    <ref name="core.info.class"/>
    <ref name="legacy.info.class"/>
    <ref name="conference.info.class"/>
    <ref name="keyword.info.class"/>
    <ref name="itermset"/>
  </mixture>

  <mixture name="div.component.mix">
    <ref name="list.class"/>
    <ref name="admonition.class"/>
    <ref name="verbatim.class"/>
    <ref name="synopsis.class"/>
    <ref name="para.class"/>
    <ref name="publishing.class"/>
    <ref name="object.descriptions.class"/>
    <ref name="msgset"/>
    <ref name="procedure.class"/>
    <ref name="qandaset"/>
    <ref name="highlights"/>
    <ref name="remark"/>
    <ref name="bridgehead"/>
    <ref name="anchor"/>
    <ref name="address"/>
    <ref name="indexterm"/>
    <ref name="beginpage"/>
    <ref name="form.class"/>
  </mixture>

  <mixture name="title.char.mix">
    <text/>
    <ref name="publishing.inlines.class"/>
    <ref name="link.inlines.class"/>
    <ref name="technical.inlines.class"/>
    <ref name="remark"/>
    <ref name="math.inlines.class"/>
    <ref name="graphic.inlines.class"/>
    <ref name="indexing.inlines.class"/>
    <ref name="glossary.inlines.class"/>
    <ref name="product.inlines.class"/>
    <ref name="personname"/>
    <ref name="error.inlines.class"/>
    <ref name="legacy.inlines.class"/>
    <ref name="programming.inlines.class"/>
    <ref name="os.inlines.class"/>
    <ref name="markup.inlines.class"/>
    <ref name="legacy.inlines.class"/>
    <ref name="indexing.inlines.class"/>
    <ref name="partnumbers.inlines.class"/>
    <ref name="ebnf.inlines.class"/>
    <ref name="oo-prog.inlines.class"/>
    <ref name="gui.inlines.class"/>
    <ref name="keyboard.inlines.class"/>
    <ref name="form.inlines.class"/>
  </mixture>

  <mixture name="ubiq.mix">
    <ref name="indexing.inlines.class"/>
    <ref name="beginpage"/>
  </mixture>

  <mixture name="ubiq.inclusion">
    <ref name="ubiq.mix"/>
  </mixture>

  <!-- ====================================================================== -->

  <define name="title.content">
    <sequence>
      <ref name="title"/>
      <optional>
	<ref name="subtitle"/>
      </optional>
      <optional>
	<ref name="titleabbrev"/>
      </optional>
    </sequence>
  </define>

  <define name="set.title.content">
    <ref name="title.content"/>
  </define>

  <define name="book.title.content">
    <ref name="title.content"/>
  </define>

  <define name="book.component.title.content">
    <ref name="title.content"/>
  </define>

  <define name="section.title.content">
    <ref name="title.content"/>
  </define>

  <define name="refsection.title.content">
    <ref name="title.content"/>
  </define>

  <class name="book.component.content">
    <choice>
      <sequence>
	<one-or-more>
	  <ref name="div.component.mix"/>
	</one-or-more>
	<choice>
	  <zero-or-more>
	    <ref name="sect1"/>
	  </zero-or-more>
	  <zero-or-more>
	    <ref name="refentry.class">
	  </zero-or-more>
	  <zero-or-more>
	    <ref name="simplesect">
	  </zero-or-more>

	  <zero-or-more>
	    <ref name="section.class">
	  </zero-or-more>
	</choice>
      </sequence>
      <choice>
	<one-or-more>
	  <ref name="sect1">
	</one-or-more>
	<one-or-more>
	  <ref name="refentry.class">
	</one-or-more>
	<one-or-more>
	  <ref name="simplesect">
	</one-or-more>
	<one-or-more>
	  <ref name="section.class">
	</one-or-more>
      </choice>
    </choice>
  </class>

  <!-- ====================================================================== -->

  <define name="set" in:name="ubiq.inclusion">
    <sequence>
      <optional>
	<ref name="set.title.content"/>
      </optional>
      <optional>
	<ref name="setinfo"/>
      </optional>
      <optional>
	<ref name="toc"/>
      </optional>
      <one-or-more>
	<ref name="book.class"/>
      </one-or-more>
      <optional>
	<ref name="setindex"/>
      </optional>
    </sequence>
  </define>

  <define name="setinfo">
    <one-or-more>
      <ref name="info.mix"/>
    </one-or-more>
  </define>

  <!-- ====================================================================== -->

  <define name="article" in:name="ubiq.inclusion">
    <sequence>
      <optional>
	<ref name="book.component.title.content"/>
      </optional>
      <optional>
	<ref name="articleinfo"/>
      </optional>
      <optional>
	<ref name="tocchap"/>
      </optional>
      <zero-or-more>
	<ref name="lot"/>
      </zero-or-more>
      <one-or-more>
	<ref name="book.component.class"/>
      </one-or-more>
      <ref name="book.component.content"/>
      <zero-or-more>
	<choice>
	  <ref name="nav.class"/>
	  <ref name="appendix.class"/>
	  <ref name="ackno"/>
	</choice>
      </zero-or-more>
    </sequence>
  </define>

  <define name="title">
    <zero-or-more>
      <ref name="title.char.mix"/>
    </zero-or-more>
  </define>

  <!-- ====================================================================== -->
  <!-- toc-lot module -->

  <define name="toc" in:module="toc-lot">
    <sequence>
      <optional>
	<ref name="beginpage"/>
      </optional>
      <optional>
	<ref name="book.component.title.content"/>
      </optional>
      <zero-or-more>
	<ref name="tocfront"/>
      </zero-or-more>
      <zero-or-more>
	<choice>
	  <ref name="tocpart"/>
	  <ref name="tocchap"/>
	</choice>
      </zero-or-more>
      <zero-or-more>
	<ref name="tocback"/>
      </zero-or-more>
    </sequence>
  </define>

  <define name="tocfront" in:module="toc-lot">
    <ref name="para.char.mix"/>
  </define>

  <define name="tocpart" in:module="toc-lot">
    <sequence>
      <one-or-more>
	<ref name="tocentry"/>
      </one-or-more>
      <zero-or-more>
	<ref name="tocchap"/>
      </zero-or-more>
    </sequence>
  </define>

  <define name="tocchap" in:module="toc-lot">
    <sequence>
      <one-or-more>
	<ref name="tocentry"/>
      </one-or-more>
      <zero-or-more>
	<ref name="toclevel1"/>
      </zero-or-more>
    </sequence>
  </define>

</schema-description>

                                        Be seeing you,
                                          norm

[1] http://nwalsh.com/docbook/docbook-clippings.png

-- 
Norman Walsh <ndw@nwalsh.com>      | During the first period of a man's
http://www.oasis-open.org/docbook/ | life the greatest danger is:
Chair, DocBook Technical Committee | <em>not to take the
                                   | risk</em>.--Kierkegaard