Balisage Paper: One Document Does-it-all (ODD): a language for documentation, schema generation, and customization from the Text Encoding Initiative

Documentation

As a TEI document, an ODD can contain extensive prose describing either a new markup language or a customization. This human-readable documentation is typically contained within the TEI <text> element, and can make use of the standard TEI elements including those for divisions, headings, paragraphs, and snippets of computer code.

<schemaSpec ident="myTEI" start="TEI" ns="http://tei-c.org/ns/1.0">
  <!-- specification and customization elements go here -->
</schemaSpec>

Specifications: a brief overview

The specifications introduced below are defined and referenced using ODD elements that share a similar structure. First, the names of these elements are formed by a term plus “Spec”, such as <elementSpec> or <classSpec>. Elements that express references to these specifications end in “Ref”, such as <elementRef> or <classRef>. Other shared features include the @ident attribute to indicate the name of the object being specified or referred to, and documentation elements for providing descriptions and usage examples.

<*Spec ident="name">
  <gloss>An expansion of the name, if necessary</gloss>
  <desc>A description of this specification</desc>

  <!-- definitions depending on the type of specification -->

  <exemplum>
    <!-- Examples of usage -->
  </exemplum>
  <remarks>
    <!--Any further notes or comments about this specification-->
  </remarks>
</*Spec>

Modules

A module provides a name for a set of other formal declarations, which other specifications will use to indicate their membership to the module and that module alone (specifications can only belong to one module).

<moduleSpec ident="namesdates">
  <desc>Additional elements for names and dates</desc>
</moduleSpec>

Modules are rarely changed, but a customization ODD will use <moduleRef> to indicate which of them are to be included in the customization. This element is also equipped with attributes to exclude or include element members; for example the following example includes the whole “namesdates” module, but without <event> and <listEvent>:

<moduleRef ident="namesdates" except="event listEvent" />

This element can also be used to bring in external schemata if necessary.

<moduleRef url="svg.rng" />

A TEI customization needs four modules to be functional: tei, core, header, and textstructure. TEI’s ODD processor does not enforce the presence of these modules, however, and it is left to the user to make sure they are included.^[5]

Model Classes

Model classes work similarly to modules, but only accept memberships from element declarations (elements may be members of multiple model classes). A model class can be referenced from within a content model, allowing all members of the model class to appear at that point in the content model. When the class is referenced, one can indicate cardinality and the order (alternation or sequence) of any or all members of the class (see Elements below).

<classSpec module="tei" type="model" ident="model.segLike">
  <desc>groups elements used for arbitrary segmentation.</desc>
  <classes>
    <memberOf key="model.phrase"/>
  </classes>
</classSpec>

Customizations may change model classes to fine-tune class dependencies. Here is an example that allows members of the model.segLike class to appear wherever members of the model.addrPart class are allowed.

<classSpec module="tei" type="model" ident="model.segLike" mode="change">
  <classes>
    <memberOf key="model.phrase"/>
   <memberOf key="model.addrPart"/>
  </classes>
</classSpec>

Attribute Classes

Attribute classes declare and provide documentation for a set of attributes. Elements and other attribute classes can inherit from them.

<classSpec module="verse" type="atts" ident="att.enjamb">
  <attList>
    <attDef ident="enjamb" usage="opt">
      <desc>indicates whether the end of a verse line is marked by enjambement.</desc>
      <datatype>
        <dataRef key="teidata.enumerated"/>
      </datatype>
      <valList type="open">
        <valItem ident="no">
          <desc>the line is end-stopped </desc>
        </valItem>
        <valItem ident="yes">
          <desc>the line in question runs on into the next </desc>
        </valItem>
        <valItem ident="weak">
          <desc>the line is weakly enjambed </desc>
        </valItem>
        <valItem ident="strong">
          <desc>the line is strongly enjambed</desc>
        </valItem>
      </valList>
    </attDef>
  </attList>
</classSpec>

Customizations may adjust dependencies to other attribute classes and will often update and constrain attribute values. The example below makes the @enjamb attribute required (by default it is optional), changes its values to a particular preferred terminology, and closes the list of values, thus disallowing a value that is not from the specified preferred terminology. All of these changes are well within the original specification of the TEI, which is quite permissive, but this case supposes a situation where a mandatory and stricter version of @enjamb is required by a text encoding project. Note how children of <classSpec> that do not need change are not included (such as <desc>). Note the use of @mode="replace" to override the attribute declaration.

<classSpec module="verse" type="atts" ident="att.enjamb" mode="change">
  <attList>
    <attDef ident="enjamb" usage="req" mode="replace">
      <valList type="close">
        <valItem ident="endstop">
           <desc>the line is end-stopped </desc>
         </valItem>
         <valItem ident="light">
           <desc>the line is lightly enjambed</desc>
         </valItem>
         <valItem ident="heavy">
           <desc>the line is heavily enjambed</desc>
         </valItem>
      </valList>
    </attDef>
  </attList>
</classSpec>

Elements

The definition of elements includes their memberships to modules and classes, attributes, and a content model declaration.

<elementSpec module="tagdocs" ident="code">
  <desc>contains literal code</desc>
  <classes>
    <memberOf key="model.emphLike"/>
  </classes>
  <content>
    <textNode/>
  </content>
  <attList>
    <attDef ident="type" usage="opt">
      <desc>the language of the code</desc>
      <datatype>
        <dataRef key="teidata.enumerated"/>
      </datatype>
    </attDef>
  </attList>
</elementSpec>

Content models can be defined using RELAX NG, or (preferably) using dedicated ODD elements. There are a number of features available to organize the content model, such as <alternate> and <sequence> to determine how the referenced elements can be combined; and @minOccurs and @maxOccurs attributes to set cardinality. Note that each specification element (<moduleSpec>, <classSpec>, <elementSpec>) has corresponding reference elements (<moduleRef>, <classRef>, <elementRef>).

<content>
  <alternate>
    <classRef key="model.pLike" maxOccurs="unbounded"/>
    <sequence>
      <elementRef key="summary" minOccurs="0" maxOccurs="1"/>
      <elementRef key="msItem" maxOccurs="unbounded"/>
    </sequence>
  </alternate>
</content>

Model classes group elements by membership and typically do not impose a specific order. When referenced, however, the @expand attribute can be used to override this behavior. For example, the following content model boils down to ( p*, ab* ) rather than the usual ( p | ab ).

<content>
  <classRef key="model.pLike" expand="sequenceOptionalRepeatable" />
</content>

In a customization, including or removing an element is typically done when selecting a module via the @include and @except attributes on <moduleRef>. However, these operations can also be performed explicitly using <elementRef> inside a <schemaSpec>. For example, to add the element <msItem> (manuscript item) without including the manuscript description module:

<elementRef key="msItem" />

Or to remove the <p> (paragraph) element without removing the core module (without which TEI would make little sense):

<elementRef key="p" mode="delete" />

More minute changes to elements are quite common in a TEI customization and they will range from adjusting the description, to adjusting attribute values, to class memberships. A typical operation would be constraining attributes, for example the @type attribute on the <div> (textual division) element. The @type attribute is derived from <div>’s membership in the attribute class att.typed. Note the use of @mode="replace" to override the declaration of the @type attribute inherited from att.typed.

<elementSpec ident="div" mode="change">
  <attList>
   <attDef ident="type" mode="replace">
      <valList type="closed">
        <valItem ident="chapter"/>
        <valItem ident="section"/>
      </valList>
    </attDef>
  </attList>
</elementSpec>

Entirely new elements can be added as well, though when customizing TEI, the Guidelines require that new elements and attributes are added under a new namespace. Membership to classes will determine where the element can go; for example model.phrase groups “inline” elements, so a new inline element can simply declare its membership to that class.

<elementSpec ident="opus" ns="myTEI.example.org" mode="add">
  <desc>The opus number or "work number" that is assigned to a musical composition</desc>
  <classes>
    <memberOf key="model.phrase"/>
    <memberOf key="att.global"/>
  </classes>
  <content>
    <textNode/>
  </content>
</elementSpec>

Likewise, a “block” element could be part of the same model class as <div> (model.divLike) or as <p> (model.pLike). When the new element is meant to be a child of another specific element, the parent element’s content model will need to be changed. For example this is how the new element <opus>, presuming it is not a member of model.phrase, could be added to TEI’s <title> element only.

<elementSpec ident="title" mode="change">
  <content>
    <alternate minOccurs="0" maxOccurs="unbounded">
      <macroRef key="macro.paraContent"/>
      <elementRef key="opus" />
    </alternate>
  </content>
</elementSpec>

Datatypes

Datatypes for attributes and other string content can be specified and used by multiple declarations. W3C XML datatypes can be referred directly by their name and need not be redefined.

<dataSpec ident="teidata.pointer">
  <desc>defines the range of attribute values used to provide a single URI, absolute or relative,
    pointing to some other resource, either within the current document or elsewhere.</desc>
  <content>
    <dataRef name="anyURI"/>
  </content>
</dataSpec>

When referenced, datatypes can be restricted to match a given regular expression.

<!-- a fraction: -->
<dataRef name="token" restriction="(\-?[\d]+/\-?[\d]+)"/>

Datatypes can be changed by customizations, though it is more common to add or change restrictions or introduce entirely new datatypes.

Macros

Macros are used to declare predefined strings or patterns. Content models can be defined here just like they are in elements.

<macroSpec module="tei" ident="macro.paraContent">
  <content>    
    <alternate minOccurs="0" maxOccurs="unbounded">
      <textNode/>
      <classRef key="model.gLike"/>
      <classRef key="model.phrase"/>
      <classRef key="model.inter"/>
      <classRef key="model.global"/>
      <elementRef key="lg"/>
      <classRef key="model.lLike"/>
    </alternate>    
  </content>
</macroSpec>

Customizations may consider introducing new macros, or adding new classes and elements to existing macros.

Constraints

Other formal constraints can be documented and specified within the <constraintSpec> element. These can be placed within other specification elements, or elsewhere in the documentation text. The TEI source uses Schematron to express constraints, for example:

<constraintSpec ident="activemutual" scheme="schematron">
  <constraint>
    <s:report test="@active and @mutual">Only one of the
      attributes @active and @mutual may be supplied</s:report>
  </constraint>
</constraintSpec>

Expressing constraints is a powerful tool for building customizations, particularly when multiple encoders will be working with the schema. Schematron in particular offers many level of reporting for catching encoding errors and offering suggestions to encoders.

More literate programming

A truly literate programming ODD will couple prose with specifications, yet the elements introduced so far are children of <schemaSpec>, which is somewhat divorced from the <text> element containing the bulk of the human-readable documentation. It is possible, nonetheless, to refer from the prose to specifications in the <schemaSpec>, which a processor will expand when generating documentation. The TEI Guidelines use this mechanism, which simplifies the maintenance of specifications organized into multiple XML files.

<listRef>
  <ptr target="#ID_OF_SPEC_ELEMENT"/>
</listRef>

This is hardly a tight coupling of prose and specification, but it works well for a complex ecosystem such as the TEI Guidelines. It is also possible, however, to do just the opposite: break up specifications into groups to be included within the documentation prose. References within <schemaSpec> can then take care of telling the processor how to put everything back together. The more recent TEI customization for “Simple Print” documents employs this strategy.^[6]

The following (abridged) bit of prose describes the selection of elements from the TEI header for the Simple Print customization:

<div>
  <p>A subset of 45 elements is selected from the TEI header module. In addition, <!-- etc. --></p>
  <specGrp xml:id="header">
    <moduleRef key="header" include="abstract availability biblFull catDesc etc" />
    <moduleRef key="corpus" include="particDesc settingDesc"/>
  </specGrp>
</div>

Elsewhere in the document, the <schemaSpec> points back to this and other <specGrp> elements.

<schemaSpec ident="teisimpleprint" start="TEI teiCorpus">
  <specGrpRef target="#base"/>
  <specGrpRef target="#header"/>
  <!-- etc. -->
</schemaSpec>