Introduction to Writing ODDs

Writing ODD files by hand

A few things that are useful to remind ourselves of and bear in mind before we start:

An ODD file is just a TEI file (with a bunch of unusual and special-purpose elements in it)
It serves two functions: to express the customizations you’ve made, in formal terms, and to document those customizations (we’re going to focus right now on expressing the customizations, but we’ll talk about documentation a little alter on)
When the ODD file is processed (by roma), the elements that express schema modifications are used to affect the generation of your custom schema, and the documentation elements are used in generating your custom documentation.

What are these specialized elements doing? They’re saying things like:

Include this element!
Delete this element!
Change this attribute!
Replace the default definition with my custom definition!
...and of course Here’s what it means and why I did it!

Including Modules

So we’re going to start out by talking about how to work with elements in your customization, and then we’ll try this out in practice; then we’ll talk about how to modify attributes (and try that out), and finally look at managing classes and the big picture.

The most basic thing you can do in a TEI customization (and the most obligatory) is to specify what modules you’ll be including in your schema. Let’s remind ourselves that modules are equivalent to chapters in the Guidelines, and they are organized topically: for instance, there are modules on drama, on linking, on the transcription of primary sources.

To include a module in your schema, use the <moduleRef> element; the @key attribute tells us what module we’re including.

Note that when you include a module, by default you will get all the elements, classes, and macros from that module in your schema.

Example

So here’s a little tiny customization...

Trimming your modules

What if there are a few elements in a given module that you don’t want? or what if there are only a few that you do want?

You can specify which elements from the module will be included in your schema, using @except or @include

The @except attribute on <moduleRef> lists which elements defined by the given module will not be included.

The @include attribute on <moduleRef> lists which elements defined by the given module will be included

Two important gotchas to remember here:

It’s important to note that you can’t use both mechanisms on the same <moduleRef>, but you can use @include on one <moduleRef> and @except on another.
Make sure that the elements listed are actually in the module specified, and that they aren’t misspelled: you will get an unhelpful error message from tei_customization, but other schemas won’t flag an error; in any case things Just Won’t Work...

What’s the difference between these two approaches? (ask for ideas)

efficiency (how many elements you have to list)
how about when the TEI changes and you regenerate your schema?

Element white-lists

If you’re creating a very slim schema with very few elements, this process we just illustrated can get cumbersome: including modules and then deleting all the elements you’re not including; it’s sort of like ordering a meal by listing all the menu items you don’t want to order, instead of listing just the ones you do want to order.

Recently added feature in TEI: the ability to include elements one by one...

So if we just wanted to include <persName>, <placeName>, and <orgName> in our schema, instead of including the whole module on Names and Dates, we could do something like the example here

So let’s try this out in practice...

The `@mode` attribute

We’ve now seen a few more examples of the @mode attribute and it’s worth pausing for a second to pay closer attention to it. You can use it on almost all of the schema specification elements we’re looking at, and even though they’re valid without it, roma may not process your ODD properly if it’s not present. So you should get in the habit of using it.

It has several possible values:

mode="delete": delete this feature
mode="add": add this new feature
mode="change": change just the parts of this feature that I am specifying here
mode="replace": replace this feature completely with my version

Attributes removal: Overview

So far we’ve learned how to include modules and include or exclude elements. How about if we want to change or remove an attribute? Let’s focus first on removing attributes.

Remember that elements get attributes by belonging to an attribute class: because <div> is in the attribute class att.typed, it gets the @type and @subtype attributes (just like all members of that attribute class: <persName>, <head>, <note>, and a whole bunch of other elements)

And elements can also have attributes privately: these are attributes that belong to that element alone, rather than being part of a class. E.g., <handShift> has its @new attribute, and <relation> has its @mutual attribute.

Hence there are a few different ways to remove an attribute:

To remove it from the entire schema, you can either
- delete the entire attribute class from the schema. This of course deletes all the attributes that are members of that class. E.g., if you never plan to use either the @full or the @sort attribute on your names, you might delete the att.personal class from your schema. OR
- delete the attribute from the attribute class it belongs to. In this case, no element in the schema will have that attribute, but the others in the class will survive. So if you think the @subtype attribute is evil and unnecessary, you might want to delete it from the att.typed class, thus leaving the ever-important @type attribute
To remove an attribute from a single element, if the element has that attribute because of class membership, you can remove the element from that attribute class; that way the other elements that subscribe to that attribute class won’t be affected. So if you want to use @subtype on <div>, but not on <head>, you would just want to remove it from <head> and leave <div> unchanged. (But note the gotcha in a moment...)
To remove an attribute from a single element, if that element is a private owner of that attribute, you can just change the definition of that specific element to remove the attribute.

We’ll illustrate all of these in the next slide. First, the gotcha: when you unsubscribe an element from an attribute class, it loses all the attributes that it gets from that class. So in our example, if we remove <head> from the att.typed class, what will happen? (It will lose both @type and @subtype, which isn’t really what we want.) The solution is that you have to remove the element from the class, and then restore any individual attributes you want it to retain. We’ll show that in a second.

Changing attributes: Specifying values

OK, let’s walk through this one together...

First, what are these new elements doing? Figure it out based on what we’ve already seen...

What’s a data type? A way of constraining what kinds of data are valid in this space: for instance, requiring that a number consist of integers only, or that a date conform to a specific format. In this case, we’re saying that the contents of the @type attribute must be from a controlled list that we specify; the datatype data.enumerated is one that the TEI has defined for us, and this is the mechanism for referencing it.

We’ll deal with data types in more detail a bit later in the workshop.

The <valList> contains the possible values; @type indicates whether the list is closed (no other values permitted) or semi-closed (these values will show up in a menu but others are permitted) or open (the values given are suggestions only).

Use mode="change" on <attDef> if the attribute already exists; use mode="add" if this is a new attribute.

Let’s try this out in practice...

datatypes, general

The TEI’s use of the term probably doesn’t precisely fit this definition, but it’s close enough for our purposes

The bigger picture …

Show <specDesc> in context of entire TEI file

Tour and Try

Show a commented, well-organized ODD with each set of customization components grouped together neatly

Tour of a real-world example