TEI ODD Exercise: Customizing and Documenting the TEI

Introducing TEI ODD

Up to this point, we have been applying code based on researching the Guidelines of the Text Encoding Initiative (TEI) and seeing what is available to us in the oXygen XML Editor on a TEI-All document. TEI projects often begin this way, exploring what is possible in the hundreds of elements and attribute options available. However, sooner or later as a project continues, it is best to customize the TEI by reducing the options we want to be available within a project. What elements are we actually using and how much of the TEI do we really need?

Customizing the TEI involves a process of generating a new Relax NG schema that typically represents a much smaller subset of the TEI. We could also introduce some of our own custom elements from outside the TEI (as in make up some elements that are not otherwise represented in the TEI Guidelines), but that is a little more advanced and usually unecessary for most TEI projects.

So, how do we access the TEI Relax NG schema? Because the TEI represents such a large schema, we do not edit its Relax NG directly. (TEI Relax NG is typically expressed in the verbose XML syntax because it requires some functionality from XML processing code that is not available in the Relax NG Compact Syntax you have learned to write.) Instead, to customize the TEI, we work with a TEI language called ODD for One Document Does it all. ODD syntax concisely expresses in XML which modules of the TEI we are working with (clusters of TEI elements grouped based on their functionality and purpose; currently there are 20 modules as of this writing in 2022). In preparing an ODD, when we represent a module, we can also indicate which of its elements we want to include (throwing out all the others) or which ones we want to exclude (keeping the rest). TEI ODD XML can also express specific customizations, to lay out which attribute values you want to use in your project customization for, say, the attribute xml:id on the handNote element.

Here I have linked an example of an ODD customization made by students working on a project to encode Hamilton the Musical, with lots of customized attribute values mostly for providing distinct identifiers for characters in the musical. Since we are working with manuscripts and other kinds of materials, our ODD customizations will certainly look different from this: we will need to work with different modules, but we will still want to customize them as we see in the ODD file, to determine which elements we ware going to use and to indicate what values we want to work with on some of the attributes.

To explore how to create an ODD, let's work with one of the TEI files you have been coding so far. You may also opt to work with our class examples for TEI posted in the textEncoding-Hub.

A good place to begin work on an ODD customizations is a tool designed for TEI called Roma, available at https://romabeta.tei-c.org/. This is where we created our starter ODD for class, which I downloaded and pushed to our textEncoding-Hub repo, and stored in Class Examples >> TEI-ODD-Examples. For this exercise, you may begin with this ODD file and continue to customize it, or you may start from scratch exploring how to include and exclude elements in Roma Beta. My assignment for you is simply to refine what we started, to try the following:

• Upload our customized ODD from class to the Roma Beta tool (or if you wish to experiment more, try starting from scratch working with TEI All or one of the other customizations available).
• Try viewing the elements by module in TEI Roma so they are grouped together helpfully (rather than viewing them all in alphabetical order).
• Try adding or removing one or more elements from the customization (so long as this makes sense based on your TEI coding decisions).
• Work on modifying an element to customize its attribute values, or even remove some attributes you probably will not use. Click through the menus to see how to edit attributes and values on an element. Suggestion: work on the handNote element to customize the attributes on it, and give them specific values.
• Continue looking stuff up in the TEI Guidelines, that is Googling for TEI P5 whateverYouLookFor to see element spec pages and examples of how these are used in TEI projects.
• Now, download your ODD and save it with your homework files. In Roma Beta, use the first download option: Customization as ODD.
• Open your ODD in the oXygen XML Editor (it should be clear and legible to read as an XML file). Make edits to the top of it to change its name and the descriptive contents as you wish.
• Apply the wrench tool to set up an ODD transformation: select the following settings (as shown in the screen capture):
  1. TEI ODD XHTML
  2. TEI ODD to RELAX NG XML
  
• View the HTML documentation in a web browser and see the list of elements you have customized for the project.
• The Relax NG you can associate with your XML file is saved in a directory named out/ just below the ODD and the ODD XHTML file. Your next task is to associate that schema with your TEI XML file and see if your code is valid to the schema. If it is not, try to amend your coding to work with the ODD schema, or update the ODD (using Roma or the ODD file in oXygen) to generate an improved schema.
• What to submit on Canvas:
  1. Your ODD file saved with .odd extension.
  2. The ODD HTML documentation file (as output with a .html extension).
  3. Your TEI XML file saved with the schema associated (with .xml extension). Add XML comments to either of these files if you are having trouble getting the ODD schema to validate your XML.