Brown ODDs.odd - Revision history

Syd: /* Note 1 */ oXygen will read Schematron from RNG (just not RNC)

2011-09-16T21:21:17Z

‎Note 1: oXygen will read Schematron from RNG (just not RNC)

Syd: added limitation; added stats

2011-09-05T20:00:15Z

added limitation; added stats

Syd: fix link in /* Getting and Using */

2011-09-05T19:25:39Z

fix link in ‎Getting and Using

Syd: added category (which I had deliberately not done earlier, so it wouldn’t show up until now)

2011-09-05T19:21:47Z

added category (which I had deliberately not done earlier, so it wouldn’t show up until now)

Syd: New page: == Introduction == The TEI tagset for markup language documentation (module `tagdocs`, chapter 22 “Documentation Elements”), affectionately called “ODD”, is a generic meta-l...

2011-09-05T19:19:09Z

New page: == Introduction == The TEI tagset for markup language documentation (module <tt>tagdocs</tt>, chapter 22 “Documentation Elements”), affectionately called “ODD”, is a generic meta-l...

New page

== Introduction ==
The TEI tagset for markup language documentation (module <tt>tagdocs</tt>, 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 <tt>tei_odds.odd</tt> 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 <tt>tei_odds</tt> 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, <tt>tei_odds</tt> 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 <tt>@ident</tt> attribute of <tt><classSpec></tt> 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 <tt><classSpec></tt> element, our XML editor (e.g., [[OXygen|oXygen]]) automatically inserts an <tt>@ident</tt> attribute and gives us a pop-up list of available classes.

== Getting and Using ==
There are several possible ways to get your hands on <tt>brown_odds</tt>. Here they are arranged in what I think is roughly easiest to hardest.
* Download the derived files from the WWP website.[[#Note 1|[1]]]
*# [http://www.wwp.brown.edu/outreach/seminars/_current/handouts/TEI_exercise/schemas/brown_odds.rnc RELAX NG (compact syntax)]
*# [http://www.wwp.brown.edu/outreach/seminars/_current/handouts/TEI_exercise/schemas/brown_odds.isosch ISO Schematron]
*# [http://www.wwp.brown.edu/outreach/seminars/_current/handouts/TEI_exercise/schemas/brown_odds.doc.html HTML documentation]
* Download the [http://www.wwp.brown.edu/outreach/seminars/_current/handouts/TEI_exercise/schemas/brown_odds.odd ODD file] itself from the WWP website, and submit it to [http://www.tei-c.org/Roma/ Roma] or some other ODD processor.
* Copy-and-paste the [[#ODD|ODD file]] itself into a file, and submit it to [http://www.tei-c.org/Roma/ 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:
** [http://www.wwp.brown.edu/outreach/seminars/_current/handouts/TEI_exercise_support/brown_odds_generation/brown_odds_driver.odd source ODD file]
** [http://www.wwp.brown.edu/outreach/seminars/_current/handouts/TEI_exercise_support/brown_odds_generation/generate_valLists.xslt stylesheet] that reads in the TEI Guidelines from disk and generates lists of elements, modules, and classes.
** [http://www.wwp.brown.edu/outreach/seminars/_current/handouts/TEI_exercise_support/brown_odds_generation/generate.bash shell script] that runs the process on my Mac
** [http://www.wwp.brown.edu/outreach/seminars/_current/handouts/TEI_exercise_support/brown_odds_generation/brute_force_generate_released_version.bash 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 <tt>@ident</tt> of <tt><elementSpec></tt> or in the <tt>@include</tt> or <tt>@except</tt> of <tt><moduleRef></tt> may change at any release. Thus the [[#ODD|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|ODD file]].

==Problems==
===Bugs===

===Known limitations===
* Does not check that the elements in <tt>@include</tt> and <tt>@except</tt> of <tt><moduleRef></tt> come from the module listed on <tt>@key</tt>.
* Does not check that the element or class named on <tt>@ident</tt> of <tt><elementSpec></tt> or <tt><classSpec></tt> comes from the module named on <tt>@module</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. Warning: This is a very large file (~321 KiB), so copy-and-paste may give you trouble.

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

==Notes==
===Note 1===
Remember that some processors (including oXygen) will not read the Schematron that is embedded in the RELAX NG, so you will need to explicitly say to use it. So, e.g., in oXygen the top of your ODD might look like <code lang="xml"><pre><?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="brown_odds.rnc" type="application/relax-ng-compact-syntax"?>
<?xml-model href="brown_odds.isosch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<TEI xmlns="http://www.tei-c.org/ns/1.0" version="1.9.1"
xmlns:sch="http://purl.oclc.org/dsdl/schematron"
xmlns:rng="http://relaxng.org/ns/structure/1.0" ></pre></code>

@@ Line 29: / Line 29: @@
 * Does not check that the elements in <tt>@include</tt> and <tt>@except</tt> of <tt>&lt;moduleRef></tt> come from the module listed on <tt>@key</tt>.
 * Does not check that the element or class named on <tt>@ident</tt> of <tt>&lt;elementSpec></tt> or <tt>&lt;classSpec></tt> comes from the module named on <tt>@module</tt>.
 ===Other===
@@ Line 35: / Line 36: @@
 ==ODD==
-This particular version was built against (and thus for) TEI P5 1.9.1. Warning: This is a very large file (~321 KiB), so copy-and-paste may give you trouble.
+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 <tt>&lt;person></tt> that has as its possible values <tt>0</tt>, <tt>1</tt>, <tt>2</tt>, and <tt>9</tt>).
 ==Notes==

← Older revision		Revision as of 19:21, 5 September 2011
Line 47:		Line 47:
	xmlns:sch="http://purl.oclc.org/dsdl/schematron"		xmlns:sch="http://purl.oclc.org/dsdl/schematron"
	xmlns:rng="http://relaxng.org/ns/structure/1.0" ></pre></code>		xmlns:rng="http://relaxng.org/ns/structure/1.0" ></pre></code>
		+	[[Category:Customization]]

@@ Line 67: / Line 67: @@
 ==Notes==
 ===Note 1===
-Remember that some processors (including oXygen) will not read the Schematron that is embedded in the RELAX NG, so you will need to explicitly say to use it. So, e.g., in oXygen the top of your ODD might look like <code lang="xml"><pre><?xml version="1.0" encoding="UTF-8"?>
+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:<code lang="xml"><pre><?xml version="1.0" encoding="UTF-8"?>
 <?xml-model href="brown_odds.rnc" type="application/relax-ng-compact-syntax"?>
 <?xml-model href="brown_odds.isosch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>