Introduction to Writing ODDs

Syd Bauman and Julia Flanders

2019-04-25

Writing ODD files by hand

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

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

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:

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

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:

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:

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

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