Brown ODDs.odd

Introduction
The TEI tagset for markup language documentation (module tagdocs, chapter 22 “Documentation Elements”), affectionately called “ODD”, is a generic meta-language that can be used to develop markup languages from scratch. But most of us use it create TEI customizations; furthermore, most of those customizations do not use some capabilities of ODD. (E.g., it is very rare to add a new class to a customization ODD — it is a perfectly reasonable thing to do, we just don’t do it often.)

The ODD language itself, as documented in the TEI Guidelines and instantiated in the tei_odds.odd customization available as part of the P5 package from Sourceforge, is (appropriately) very loose, permitting all sorts of constructs that are not used by current ODD processors or are not often used in creating TEI customizations. This means that many documents that are valid against tei_odds are not proper TEI customization files, and thus will fail to produce a conforming TEI schema when submitted to (e.g.) Roma. Thus as a constraint for writing or hand-editing TEI customizations, tei_odds is not particularly useful.

By contrast, the “Brown ODD for Hand-editing ODDs” language is deliberately very restrictive in an attempt to be helpful for the average user customizing TEI at the expense of the power user developing non-TEI languages or using esoteric features of ODD. For example, the @ident attribute of &lt;classSpec> is restricted to a list of the classes available in the TEI. This is wonderful for the vast majority of us customizing TEI — when we enter the &lt;classSpec> element, our XML editor (e.g., oXygen) automatically inserts an @ident attribute and gives us a pop-up list of available classes.

Getting and Using
There are several possible ways to get your hands on brown_odds</tt>. Here they are arranged in what I think is roughly easiest to hardest.
 * Download the derived files from the WWP website.[1]
 * RELAX NG (compact syntax)
 * ISO Schematron
 * HTML documentation
 * Download the ODD file itself from the WWP website, and submit it to Roma or some other ODD processor.
 * Copy-and-paste the ODD file itself into a file, and submit it to Roma or some other ODD processor.
 * Download the source ODD file and building programs, figure out how to alter them so they run on your system, generate a new brown_odds.odd from them, and submit that to an ODD processor. Useful files:
 * source ODD file
 * stylesheet that reads in the TEI Guidelines from disk and generates lists of elements, modules, and classes.
 * shell script that runs the process on my Mac
 * shell script that supposedly runs the process on a TEI Ubuntu system, but the resulting schema will be invalid until the next release of the Stylesheets.

Process
The TEI is not a static language. E.g., the list of elements names one might use for the @ident</tt> of &lt;elementSpec></tt> or in the @include</tt> or @except</tt> of &lt;moduleRef></tt> may change at any release. Thus the ODD file is particular to a given version of the TEI Guidelines. Rather than changing the ODD file each time a new version of the TEI Guidelines is released, there is a stylesheet that extracts the lists of elements, etc., from the Guidelines and a shell script that inserts them (using XInclude) into a ‘driver’ ODD file, and the result is the ODD file.

Known limitations

 * Does not check that the elements in @include</tt> and @except</tt> of &lt;moduleRef></tt> come from the module listed on @key</tt>.
 * Does not check that the element or class named on @ident</tt> of &lt;elementSpec></tt> or &lt;classSpec></tt> comes from the module named on @module</tt>.
 * Does not test that there is only one &lt;schemaSpec></tt>.

Other

 * The system for building, which was originally intended to build it against the current development release of TEI for WWP workshops, could use a lot of improvement.
 * Trying to distribute this via a wiki page like this is a bit nuts.

ODD
This particular version was built against (and thus for) TEI P5 1.9.1.

Sorry — the ODD itself can’t be put on the wiki page, as it triggers the spam filter (due to an attribute of &lt;person></tt> that has as its possible values <tt>0</tt>, <tt>1</tt>, <tt>2</tt>, and <tt>9</tt>).

Stats
Just because it’s fun, I thought I’d list the size of both the source <tt>brown_odds_driver.odd</tt> file, and the <tt>brown_odds.odd</tt> file once built.

Note 1
Remember that some processors (including oXygen) will not read the ISO Schematron that is embedded in the RELAX NG compact syntax. Thus you will need to either use the XML syntax (from which oXygen will read the Schematron), or explicitly ask that both the RELAX NG and the Schematron be used. In which case, the top of your ODD might look like this: