Module 8 Sections

Table of Contents

Export

4.1. The Power of ODD #

Remember how ODD stands for “One Document Does it all”? You can derive a number of different schema and documentation output formats from the single ODD file you’re editing! The “Download” button at the top right of the Roma screen lets you choose between 3 types of output:

• ODD files
• schema files, in a number of flavours
• documentation files, in a number of output formats

Since these are frequent operations when customising TEI, they are treated in separate sections below.

4.1.1. Generating a Schema #

Select the “Download” button at the top right in the Roma screen, and choose the schema language of your choice (the various schema language output formats are highlighted in yellow):

Figure 5. Schema download formats in Roma.

Roma can generate schemas in following schema languages:

• RelaxNG schema: a schema in the more verbose XML syntax of the RelaxNG language
• RelaxNG compact: a schema in the more concise compact syntax of the RelaxNG language
• W3C schema: a schema in the W3C XSD schema language
• DTD: a schema in the DTD language
• ISO Schematron constraints: a stand-alone file containing all ISO Schematron constraints that are present in the ODD file.

Although the schemas generated in these different schema languages are roughly equivalent, some schema languages offer more expressive power than others. The schema languages that offer most complete coverage of TEI features are RelaxNG (XML syntax) and W3C schema.

Note

We’ll not go into details about the differences between these XML schema languages here. For more information, Wikipedia is your friend: https://en.wikipedia.org/wiki/XML_schema.

When choosing one of the schema flavours, your browser will download a file named TBEcustom (as we had specified earlier for our ODD in the “Settings” Roma tab). The file’s extension depends on the schema format chosen: .rng (Relax NG XML), .rnc (Relax NG compact), .xsd (W3C schema), .dtd (DTD), or .isosch (ISO Schematron). You can store this file and use it to validate your TEI documents.

4.1.2. Generating Documentation for a Customisation #

Select the “Download” button at the top right in the Roma screen, and choose the documentation format of your choice (the various documentation formats are highlighted in yellow):

Figure 6. Documentation download formats in Roma.

Roma can generate documentation in following formats:

• HTML: a web page containing the documentation of the TEI customisation
• TEI Lite: a TEI Lite file containing the documentation of the TEI customisation
• MS Word: a Word file containing the documentation of the TEI customisation
• LaTeX: a LaTeX file containing the documentation of the TEI customisation

Make sure you save the file, and see how this produces a file named TBEcustom, either in HTML, TEI XML, DOCX, or LaTeX format. This documentation can serve as your project-specific TEI Guidelines, containing formal references for all elements in the schema, as well as any prose documentation present in the ODD file.

4.1.3. Generating an ODD File #

We saved the best for last: without doubt, saving your customisation as an ODD file is the most important step of customising TEI with Roma. It will allow you (and others) to upload this customisation again for reuse, fine tune it further, and / or generate both schemas and documentation from this single source file again. Notice that, although all changes you make in the Roma web interface are being recorded automatically, you still have to save your customisation as an ODD file. In order to do so, all you have to do is hit the “Download” button at the top right in the Roma screen, and choose one of the ODD formats (the ODD formats are highlighted in yellow):

Figure 7. ODD download formats in Roma.

Roma offers following ODD formats:

• Customization as ODD: an ODD file, referencing the various TEI components
• Compiled ODD: an expanded ODD file, containing full documentation and with all references to the TEI components resolved

You’ll probably need the first option: “Customization as ODD.” This will create a file called TBEcustom.odd, which is a TEI XML file you can open in any plain text or XML editor. Notice, once again, how the file name corresponds to the one specified for our customisation in the “Settings” Roma tab.

Summary

Roma provides a visual interface to create TEI customisations, either from any of the customisation templates provided by the TEI Consortium, or from a previously saved ODD file on your file system. Customisations can be edited in Roma and exported as an ODD (One Document Does it all) file, from which both a TEI schema and accompanying documentation can be derived in a number of output formats. The ODD file is the core of your TEI customisation.

4.2. What Does a Minimal TEI Customisation Tell Us? #

Before proceeding, let’s have a closer look at what we’ve done. As mentioned before, the TBEcustom.odd file we had stored earlier, is just a TEI XML file. Let’s have a look what’s inside!

One immediate observation is that an ODD file is indeed just a regular TEI document, with a <TEI> root element, containing a <teiHeader> element and a <text> element. Remember the metadata you entered in the “Settings” tab in Roma, and see how it is reflected at the proper places inside the <teiHeader>. However, the most interesting bits are inside the <body> part.

Apart from regular body content, as illustrated by the <p> contents of our minimal TEI customisation, an ODD file contains a specific <schemaSpec> element. This element indicates a formal definition of a TEI schema. It has a mandatory @ident attribute, supplying an identification code for the schema. The language of the documentation can be specified with an optional @docLang attribute; when necessary a @targetLang attribute can specify what language to use for element and attribute names. The @prefix attribute specifies the prefix that will be added to the names of TEI patterns in the customisation. The @start attribute identifies the root element(s) of the customisation: in this case, it will produce a schema that only allows the <TEI> element as root element for valid TEI documents.

The <schemaSpec> element is the core of any ODD file, specifying the formal definition of a TEI schema. A TEI customisation can be constructed by referring to definitions of existing TEI objects (element and attribute classes, datatypes, and macros), or—as will be covered later in this tutorial—by declaring new objects as well. In our example so far, the schema specification only contains references to four of the predefined TEI modules. Each module is being referred to in a separate <moduleRef> element, whose @key attribute is pointing to the formal identifier of that module in the TEI source.

When a module is selected with <moduleRef> in an ODD file, by default all elements and attributes of that module are incorporated in the customisation. In our example, this is the case with the tei module. As we have seen, this is a special module, which doesn’t define any elements and attributes itself, but instead a lot of classes, datatypes, and macros that are being used in all other TEI modules. Three of those other modules are being referenced in our current ODD file. Yet, only a very small number of elements they define are being included in our customisation, because the <moduleRef> elements have an @include attribute, where only those elements that should be included are enumerated as a white-space separated list. If you count them, our customisation only selects the 10 elements that are required for minimally valid TEI documents.

Notice, how the @include mechanism has a counterpart: it is equally possible to specify which elements not to include in a module by enumerating them in an @except attribute. This will only exclude those elements, but will include all others. Both mechanisms offer convenient shortcuts to either include or exclude large numbers of elements. It’s important to remember that you can only use either the @include or the @except attribute on a <moduleRef> element, but not both.

4.3. Inspecting a Customisation in Roma #

As we have introduced in section 2, the TEI is a highly sophisticated library, holding model and attribute classes, macros, and datatypes. Customising TEI requires some knowledge of how they are organised. Full documentation can be found in the TEI Guidelines, but fortunately, Roma is conceived as a convenient online store for selecting the exact TEI components you need, and doing so, it shows you around in the internals of TEI as well. Let’s start editing our current customisation where we have left it by hitting the “Customize ODD” button at the top right in the Roma screen:

Figure 8. Start customising an ODD file with the “Customize ODD” button.

This will take you to the main Roma dashboard. You can tell you’re editing the right customisation from the title at the top of the screen, which reads “Roma - ODD Customization (A TBE customisation).”

Figure 9. Roma main screen.

Below the title, you see 4 different tabs at the top of the screen:

• “Elements”: an overview of all available TEI elements, allowing you to select and customise those you need
• “Attribute Classes”: an overview of all available TEI attribute classes, allowing you to select and customise those you need
• “Model Classes”: an overview of all available TEI model class definitions, allowing you to select and customise those you need
• “Datatypes”: an overview of all available TEI datatype definitions, allowing you to select and customise those you need

Let’s check how the <moduleRef> elements we’ve seen in our current TEI customisation are being reflected in the Roma interface. When you select the “Elements” tab, you’ll notice that only a very small number of elements are ticked. Indeed, from the long list of available TEI elements, only 10 have been selected: <body>, <fileDesc>, <p>, <publicationStmt>, <sourceDesc>, <TEI>, <teiHeader>, <text>, <title>, and <titleStmt>. Notice, how the default ordering in Roma is alphabetical; you can also click the “by module” button at the top right of the Roma screen. This will order the elements (or attribute classes, or model classes, or datatypes) alphabetically: first per module, and next by name. This sorting “by module” gives you an idea of what TEI components are being defined in each of the modules. This is broader than elements: if you look at the other tabs, you’ll notice that a lot of attribute classes, model classes, and datatypes are being included automatically when a TEI module is included via <moduleRef> in a TEI customisation.

5.1. Selecting Modules and Elements #

In order to encode the textual phenomena we’d identified for our example text, a number of TEI elements have to be included in our TEI customisation. This can be done easily in Roma by ticking the corresponding boxes in the “Elements” tab.

Figure 10. The “Elements” tab in Roma.

Notice how the right-hand column in Roma informs you for any element which module it belongs to. A convenient way to include or exclude all elements from a module at once, is by selecting or de-selecting that module. In order to do so, you can click the module name. For example, let’s select the figures module by clicking the plus sign next to that module name:

If we order the elements by module (by clicking the “by module” button at the top right of the Roma screen) and scroll down to the figures module, you’ll see that all of its elements now have been included in your customisation. This includes some elements we didn’t identify in the document analysis for our document; if we are absolutely certain we only have to encode images, but no tables, formulas, or music notations, these elements can quickly be deselected by unticking the element name in the left-hand column:

Figure 11. De/selecting elements in Roma.

Did you notice how the <graphic> element is part of the core module, and not of figures? If you want to include the images themselves in your transcription of Alice, you’ll have to include the <graphic> element as well. Hint: you can quickly look up an element by entering its name in the search box at the top right of the Roma screen:

Figure 12. Filtering element names in Roma.

That’s all there is to including and excluding existing TEI elements with Roma! You can also remove an entire module at once, with the caveat that this will remove all its members (and possible modifications you’ve made to them) from your customisation. Since you might run the risk of losing work here, Roma issues a warning in order to prevent unwanted mistakes:

Figure 13. Warning when removing an entire module in Roma.

Now, save your customisation as an ODD file (click the “Download” > “Customization as ODD” button at the top right of the Roma screen). Its <schemaSpec> element will be updated to:

When we generate a TEI schema from this customisation (via the “Download” button at the top right of the Roma screen), this allows us to validate a transcription of a typical page of the document (the third image from the Alice scans above) as follows:

So far for selecting modules and elements. The obvious counterpart, adding new elements, will be dealt with later in this tutorial (see section 6). First we will focus on attributes.

5.2. Changing Attributes #

5.2.1. Changing Individual Attributes #

As shown in the previous encoding snippet, the <name> element definition (from the core module) comes with a @type attribute. By providing a keyword for this attribute, we can specify what type of name is being identified with the <name> element. By default, the @type attribute can contain any single keyword from an unspecified list: anything goes as long as it conforms to some syntactic rules, specified in the teidata.enumerated datatype (basically, only a few punctuation marks are allowed, and it should start with a letter). Apart from that, there is no limit on possible values for the @type attribute. However, to improve consistency in our Alice encoding project, we would like to trim down these possibilities for the @type attribute of <name>. We’re only interested in the categories "person", "place", and "animal". This can be done in Roma, by navigating to the definition of the <name> element. In order to do so:

1. load the TBEcustom customisation again in Roma if you haven’t done so already, and click the “Customize ODD” button,
2. move to the “Elements” tab and scroll down to the definition of <name>.

In order to edit its attributes, just click the “name” element in the list (make sure it is selected, before you can click it):

Figure 14. Navigating to an element definition by clicking its name in Roma.

Clicking an element in Roma opens an “edit” screen, where some aspects can be changed:

• “Documentation” here you can change the description of an element
• “Attributes” here you can change the attributes of an element
• “Class Membership & Content Model” here you can change the classes an element belongs to, and the elements or element classes it can contain

Figure 15. Element editing screen in Roma.

Since we want to restrict the values allowed for the @type attribute of <name>, hit the “Attributes” button. This produces an overview of all attributes defined for the <name> element, organised per attribute class from which they are inherited:

Figure 16. Display of an element’s attributes in Roma.

Scroll down to the bottom, where you will find the @type attribute listed (in the att.typed attribute class). Left of each attribute name, you’ll find a pencil icon for editing the attribute, and a cross icon for removing the attribute. Since we want to restrict the values for the @type attribute, just click the pencil icon next to it. This will show the current definition of that attribute. There you can determine whether the attribute should be mandatory or optional, what the datatype of its value(s) should be, and what kind of values it allows. The “Values” section is where we can restrict the possible values for the @type attribute for names to a closed list. In order to do so:

1. Click the drop-down box in the “Values” field, and change it to “Closed.”
2. For each value we want to allow for this attribute ("place", "person", and "animal"), enter the value in the text box below, and click the “+” sign next to it.
3. For each new value, a description can be provided by clicking the “+” sign next to “Description.”

Figure 17. Changing the attributes for an element in Roma.

The changes are being recorded immediately in Roma. Clicking the “Attributes” button in the top menu of the Roma screen brings us back to the attributes list for the <name> element. Now, let’s remove some attributes we don’t need in our encoding project. With Roma, it’s possible to remove entire attribute classes at once by clicking the “X” sign next to the attribute class names in the list. Let’s do so for att.datable, att.editLike, att.global.responsibility, att.global.source, att.naming, and att.personal. Also, the @subtype and @nymRef attributes can go, just click the “X” sign next to the attribute name.

If we save the customisation at this stage (by clicking the “Download” > “Customization as ODD” button), the ODD file gets updated to:

<schemaSpec xmlns="http://www.tei-c.org/ns/1.0" ident="T​BEcustom" start="T​EI" prefix="tei_" targetLang="en" docLang="en">

<moduleRef key="figures" include="fig​Desc figure"/>

<moduleRef key="header" include="tei​Header file​Desc title​Stmt publication​Stmt source​Desc"/>

<moduleRef key="core" include="p title emph lg l pb pub​Place publisher q quote name graphic"/>

<moduleRef key="textstructure" include="T​EI text body title​Page doc​Title doc​Imprint doc​Date doc​Author byline div"/>

<moduleRef key="tei"/>

<elementSpec ident="name" mode="change">

<classes mode="change">

<memberOf key="att​.datable" mode="delete"/>

<memberOf key="att​.edit​Like" mode="delete"/>

<memberOf key="att​.personal" mode="delete"/>

</classes>

<attList>

<attDef ident="subtype" mode="delete"/>

<attDef ident="nym​Ref" mode="delete"/>

<attDef ident="type" mode="change">

<valList type="closed" mode="change">

<valItem mode="add" ident="place">

<desc versionDate="2020​-04​-23" xml:lang="en">used for place names</desc>

</valItem>

<valItem mode="add" ident="person">

<desc versionDate="2020​-04​-23" xml:lang="en">used for person names</desc>

</valItem>

<valItem mode="add" ident="animal">

<desc versionDate="2020​-04​-23" xml:lang="en">used for animal names</desc>

</valItem>

</valList>

</attDef>

<attDef ident="cert" mode="delete"/>

<attDef ident="resp" mode="delete"/>

<attDef ident="source" mode="delete"/>

</attList>

</elementSpec>

</schemaSpec>

Example 3. Attribute classes removed and attribute values changed for the <name> element (download).

Notice how a new element is introduced: <elementSpec>. In a schema specification, this is where elements are being defined. It has a mandatory @ident attribute, which names the element. In this case, the "name" value tells us that this element specification defines a <name> element. Although this could be specified further by adding a @module attribute with value "core", this is not mandatory, since element names are unique across all TEI modules.

Defining a TEI element that already exists might seem a bit weird at first sight. Notice, however, the @change attribute with the value "change", which is expressing that this existing TEI element is being changed in this customisation. This is an important mechanism: via the @mode attribute, ODD lets you specify a number of actions on the declaration of elements and attributes (and many of their components):

"add"

a new declaration is added to the current definitions

"delete"

an existing declaration is removed

"change"

an existing declaration is changed partly: only the customised parts are changed; all other parts are copied from their TEI definition

"replace"

an existing declaration is changed completely: only the customised parts are copied; all existing TEI definitions are ignored

In our ODD file, the <elementSpec ident="name" mode="change"> element is telling that the existing declaration of <name> (in the core module) should be copied, except for the components that are overridden in this customisation. In this case, there are both class-related changes, that are grouped in a <classes> element, and attribute-related changes, that are grouped in an <attList> element. The <classes> element groups class membership declarations in <memberOf> elements. In this case, three class memberships are deleted: each <memberOf> element refers to the class with the value of a @key attribute, and next states that this membership should be removed, by the "delete" value for the @mode attribute. It’s interesting to notice that, even though we removed the att.canonical class in Roma, this is not reflected in a separate <memberOf key="att.canonical" mode="delete/> element in the ODD file. This is not strictly needed, since att.canonical is a member of att.personal, so removal of the latter superclass automatically implies that the subclass(es) are removed as well.

Apart from class deletions, the <elementSpec> element with the definition of the customised <name> element groups attribute declaration in an <attList> element. Each attribute is declared in an <attDef> element. Here, too, the attribute is identified with an @ident attribute, and the customisation action is given in @mode. Four attributes are deleted: @subtype, @nymRef, @cert and @resp (from the att.global.responsibility attribute class), and @source (from the att.global.source attribute class). It’s interesting to notice that Roma doesn’t just remove these classes via a <memberOf> element, as with the other attribute classes we had deleted, but instead removes their attributes individually. While both ways of removing attributes in ODD are equivalent, Roma probably opts to remove “standalone” classes as such, while members of “inherited” classes are removed individually.

The definition for the @type attribute, has the value "change" for its @mode attribute, meaning that its contents should override the existing definitions. Since we restricted the list of possible values to a closed vocabulary, a <valList> re-defines the value list of this @type attribute. Its @type attribute with value "closed", indicates that the attribute value list is a closed list. In order to indicate that only the parts defined in our customisation should be changed, a @mode="change" attribute is given on <valList>. The different values of this closed list are defined in a series of <valItem> elements, with the value of the attribute given in an <ident> attribute (in this case: "place", "person", and "animal", respectively). Inside <valItem>, the description of the attribute value is given in a <desc> element. Notice that, since these attribute values are new, the @mode attribute on each <valItem> element has the value "add", to tell the ODD processor that they should be added to the existing definition of the @type attribute. All other parts of the existing TEI definition of the @type attribute are being copied when transforming this ODD file to a schema or documentation.

Note

Notice, however, that a full attribute definition consists of more fields, like a description, declarations of datatype and occurrence indicators. These are discussed later in this module (section 6.2).

Summary

Elements are defined in an ODD file with the <elementSpec> element. The element must be identified in an @ident attribute, and the processing mode should be stated in a @mode attribute. Inside an element declaration, entire attribute classes can be removed by removing their membership of an attribute class. This is done inside a <classes> section, where each class membership is declared in a <memberOf> element. The value "delete" for the @mode attribute indicates that a class membership should be removed. Declarations for individual attributes are grouped in an <attList> element inside <elementSpec>. Each single attribute is given its own definition inside an <attDef> element. This element, too, carries the @ident and @mode attributes, respectively for identifying the attribute, and specifying the status of the declaration. To delete attributes, indicating the @mode as "delete" suffices. Changing attributes requires a "change" mode. Value lists for an attribute can be defined in a <valList> element, whose @type attribute indicates whether the value list is open-ended ("open") or closed ("closed"). The @mode attribute can specify whether a <valList> declaration merely contains some changes to the existing TEI declaration ("change"), or replaces the original definition ("replace"). A value list declares each separate value for an attribute in a <valItem> element, with the value given in an @ident attribute. The attribute value can be described in a <desc> element.

5.2.2. Changing Attribute Classes #

As mentioned before, TEI modules group attribute definitions into attribute classes. This facilitates the definition of elements that share the same attributes, by declaring them as members of an attribute class. For example, all TEI elements are declared members of the att.global attribute class, which defines the global attributes @xml:id, @n, @xml:lang, @rend, @rendition, and @xml:base.

As it happens, the @nymRef attribute we have deleted from the definition of the <name> element in the previous section, is defined in such an attribute class, namely att.naming, of which <name> is declared a member. This information may seem disparate, but is actually easy to find in Roma. Actually, we’ve been there before:

1. load the TBEcustom customisation again in Roma if you haven’t done so already, and click the “Customize ODD” button,
2. move to the “Elements” tab and scroll down to the definition of <name>.

Remember how the attributes for <name> were grouped per attribute class? Those attribute class names are clickable in Roma. One way of accessing the att.naming attribute class definition in Roma, is by clicking the link with the label att.naming in the attributes list:

Figure 18. Accessing the definition of an attribute class via the attributes list of an element in Roma.

Another way of navigating to the attribute classes, is by selecting the “Attribute Classes” tab at the top left of the Roma screen. As with the “Elements” tab, you’ll get a list of all attribute classes, with an indication of those that have been included in the current customisation, and an indication of the TEI module that defines them.

Figure 19. The “Attribute Classes” tab in Roma.

Clicking the link with the label att.naming attribute class here, will take you to the definition of this attribute class:

Figure 20. Attribute class editing screen in Roma.

The “Attributes” button will take us to the definition of the attributes inside this class:

Figure 21. Display of the attributes in an attribute class in Roma.

The attribute class contains a number of sections: “Class Attributes” define the attributes of this class, in this case @nymRef and @role. In “Class Membership,” a superclass can be given; here, the att.naming attribute class is declared as a member of the att.canonical attribute class. This means that elements declaring themselves as member of (the subclass) att.naming, will also inherit the attributes defined in (the superclass) att.canonical, namely @key and @ref. Finally, the section “Member Classes” names attribute classes that are defined as subclass of att.naming, in this case att.personal.

Now, instead of removing the @nymRef attribute only from the <name> element as we did in the previous section, we could as well delete it globally from all elements that are member of the att.naming attribute class. This can be done simply by clicking the “X” sign next to the @nymRef attribute name.

If we save the customisation again (by clicking the “Download” > “Customization as ODD” button at the top right of the Roma screen), this produces following ODD file:

<schemaSpec xmlns="http://www.tei-c.org/ns/1.0" ident="T​BEcustom" start="T​EI" prefix="tei_" targetLang="en" docLang="en">

<moduleRef key="figures" include="fig​Desc figure"/>

<moduleRef key="header" include="tei​Header file​Desc title​Stmt publication​Stmt source​Desc"/>

<moduleRef key="core" include="p title emph lg l pb pub​Place publisher q quote name graphic"/>

<moduleRef key="textstructure" include="T​EI text body title​Page doc​Title doc​Imprint doc​Date doc​Author byline div"/>

<moduleRef key="tei"/>

<elementSpec ident="name" mode="change">

<classes mode="change">

<memberOf key="att​.datable" mode="delete"/>

<memberOf key="att​.edit​Like" mode="delete"/>

<memberOf key="att​.personal" mode="delete"/>

</classes>

<attList>

<attDef ident="cert" mode="delete"/>

<attDef ident="resp" mode="delete"/>

<attDef ident="source" mode="delete"/>

</attList>

</elementSpec>

<elementSpec ident="name" mode="change">

<classes mode="change">

<memberOf key="att​.datable" mode="delete"/>

<memberOf key="att​.edit​Like" mode="delete"/>

<memberOf key="att​.personal" mode="delete"/>

</classes>

<attList>

<attDef ident="subtype" mode="delete"/>

<attDef ident="nym​Ref" mode="delete"/>

<attDef ident="type" mode="change">

<valList type="closed" mode="change">

<valItem mode="add" ident="place">

<desc versionDate="2020​-04​-23" xml:lang="en">used for place names</desc>

</valItem>

<valItem mode="add" ident="person">

<desc versionDate="2020​-04​-23" xml:lang="en">used for person names</desc>

</valItem>

<valItem mode="add" ident="animal">

<desc versionDate="2020​-04​-23" xml:lang="en">used for animal names</desc>

</valItem>

</valList>

</attDef>

<attDef ident="cert" mode="delete"/>

<attDef ident="resp" mode="delete"/>

<attDef ident="source" mode="delete"/>

</attList>

</elementSpec>

<classSpec ident="att​.naming" type="atts" mode="change">

<attList>

<attDef ident="nym​Ref" mode="delete"/>

</attList>

</classSpec>

</schemaSpec>

Example 4. Changed attribute class (download).

Now, the <schemaSpec> element in our customisation ODD file contains another element, besides <elementSpec>: <classSpec>. This is where classes are being declared. As with element and attribute definitions, the name of the class is given in an @ident attribute, and a @mode attribute indicates the processing mode. There is an extra, mandatory, attribute, though: @type, which indicates what kind of class is being defined. Possible values are:

"atts"

for the definition of an attribute class, which defines a number of common attributes

"model"

for the definition of a model class, which groups elements that can occur in the same context in a TEI document

The content of this class specification looks familiar: an <attList> element groups all attribute declarations defined by the (attribute) class. Since the att.naming class is being processed in "change" mode, it suffices to just redefine the @nymRef attribute of this class: all other attributes of the class are being copied unmodified in our customisation. Hence, all it takes to remove @nymRef from the att.naming class, is an <attDef> element with @ident="nymRef", and @mode="delete".

Actually, the deletion of the @nymRef attribute from the att.naming attribute class obsoletes our earlier deletion of the same attribute from the <name> attribute. However, it does no harm to have this deletion on both <elementSpec> and <classSpec> levels (they don’t contradict each other). The effect of this customisation can be seen by generating a TEI schema (via one of the schema output formats in the “Download” button at the top right of the Roma screen): this will only validate documents whose name-like elements don’t have a @nymRef attribute.

Note

Be careful, though, when changing class definitions, as this can have wide ranging (and sometimes unforeseen) effects! Always make sure to study the relevant parts of the TEI Guidelines. And make sure you can trace back when anything unexpected happens: save early, save often!

Summary

Attributes that are defined in an attribute class can be changed globally by changing the class specification in a <classSpec> element. This element must identify the name of the class in an @ident attribute, and the type of class in a @type attribute. As with other schema specification elements, the mode of operation should be stated in a @mode attribute. Inside the <classSpec> declaration of an attribute class, all attribute definitions are grouped in an <attList> element, with an <attDef> declaration for each separate attribute.

6.1. Adding Elements #

So far, our TBEcustom customisation includes a generic <name> element (from the core module) for identifying names in our Alice encoding project. Apart from this generic element, TEI defines a set of more specialised elements for encoding names, in the namesdates module. These elements add more semantic detail and leave more room for further (sub)typing. Let’s use Roma to have a look at what namesdates has to offer:

1. load the TBEcustom customisation again in Roma if you haven’t done so already, and click the “Customize ODD” button,
2. in the “Elements” tab, click the “by module” button at the top right of the Roma screen and scroll down to the elements of the namesdates class.

Figure 22. Grouping all elements of a TEI module in Roma.

In this long list of specific elements for names and dates, two look particularly interesting for our purposes: <persName> (as an alternative for <name type="person">) and <placeName> (as an alternative for <name type="place">). Let’s include them in our customisation: tick the boxes in Roma, and store the ODD file via the “Download” > “Customization as ODD” button at the top right of the Roma screen. As you probably have expected, this will add following instruction to the ODD file:

If we generated a schema of the TBEcustom customisation at this point, we would be able to rephrase the encoding of the different names in our Alice fragment as follows:

Of course, this dual approach to name encoding, with the specialised <persName> and <placeName> elements for person and place names respectively, and the general <name> element with @type="animal" for animals, is undesirable. Therefore, we’ll extend our TEI customisation with a dedicated element for encoding animal names. As before, the remainder of this section first outlines the necessary steps in Roma, and next discusses the resulting ODD file.

In Roma, new components (elements, classes, datatypes) can be added to a TEI customisation by clicking the “NEW” button at the bottom right of the screen:

Figure 23. The “NEW” menu for adding new TEI components in Roma.

We’ll be creating a new element for animal names, so click the “Element” button of the pop-up menu. This opens a form with three fields. Let’s fill them:

• “Name”: the name of the element. By analogy to <persName> and <placeName>, let’s make this <animalName>
• “Module”: the TEI module this new element will belong to. Since this is a specialised naming element, let’s select namesdates.
• “Namespace”: the namespace of the (non-TEI) element. As we’ve mentioned before, let’s make this http://teibyexample.org/ns/TBE

Figure 24. “Create new element” form in Roma.

After clicking the “Create” button, our new element is born! If an ODD file is generated at this point, it would be expanded with following instructions:

This tells that our customisation defines a new element <animalName> in the http://teibyexample.org/ns/TBE namespace, which will be made available in the namesdates module.

Yet, with empty <classes> and <attList> children, this element definition is still utterly useless. We have to define a number of essential properties:

• the attribute classes this new element belongs to
• the model classes this new element belongs to
• the content of this new element

These are important decisions to make, which require conscious thought, as well as an understanding of the TEI class system. Fortunately, we can learn by example: since we are modelling a new element for animal names to the existing <persName> TEI element, we can use the declaration of the latter as a source of inspiration, or just plainly copy it. Let’s have a look at the definition page for <persName>:

1. load the TBEcustom customisation again in Roma if you haven’t done so already, and click the “Customize ODD” button,
2. move to the “Elements” tab and scroll down to the definition of <persName>.

The “Documentation” button shows the description for the <persName> element.

Figure 25. Display of the documentation for the <persName> element in Roma.

The “Attributes” button shows us the attribute classes. If only the top-level attribute classes are considered, that aren’t defined inside other attribute classes, (the others are being included automatically when their superclass is included), this list can be reduced to:

• att.datable: groups attributes for normalisation of names or dates
• att.editLike: groups attributes for describing the nature of an encoded interpretation
• att.global: groups common attributes for all TEI elements
• att.personal: groups common attributes for names
• att.typed: groups attributes that allow (sub)classification of an element

Figure 26. Display of the attributes for the <persName> element in Roma.

The “Class Membership & Content Model” button shows us the model classes of which <persName> is a member:

• model.nameLike.agent: groups elements which contain names of individuals or corporate bodies
• model.persStateLike: groups elements describing changeable characteristics of a person which have a definite duration, for example occupation, residence, or name

This means that <persName>, and all other members of these model classes, can occur wherever TEI elements specify their contents in terms of these classes.

Figure 27. Display of the class membership for the <persName> element in Roma.

The content model of the <persName> element is represented graphically in Roma. It refers to the macro.phraseSeq macro, which represents a predefined sequence of character data and phrase-level elements. This means that <persName> can contain text intermixed with a whole range of sub-paragraph level elements (<abbr>, <expan>, <name>, <persName>, ...).

Let’s copy these same declarations to our new element. Return to the “Elements” tab and click the <animalName> element. In the description box, we can enter a prose description for the <animalName> element, for example:

Figure 28. Editing the documentation for the <animalName> element in Roma.

Clicking the button labeled “<animalName> <” on top left of the Roma screen, gets us back to the overview of the <animalName> definition. A click on the “Attributes” button shows us that its attribute list is empty, as we saw already in the generated ODD file. In order to declare its membership of the 5 attribute classes we had identified in the definition of <persName>, start by clicking the plus sign in the “Attribute from Classes” row. Next, filter or scroll through the list of attribute classes, and click the plus sign next to the ones we want to add.

Figure 29. Adding the <animalName> element to attribute classes in Roma.

Finally, return to the overview of the <animalName> definition, and click the “Class Membership & Content Model” button. In order to define how our <animalName> element will behave, click the plus sign in the “Model Classes” row and select the 2 model classes we had identified by clicking the plus sign next to their name.

Figure 30. Editing the class membership of the <animalName> element in Roma.

Next, its content can be defined by first clicking one of the “Groups,” “References,” or “Nodes” blocks. This will produce an overlay menu, with a graphical indication of the different types of ODD constructs that can be used for selecting individual nodes or combining them in groups, or referencing one of the predefined TEI macros or classes. We’ll be inserting a reference to the macro.phraseSeq macro, so we’ll click the “References” block.

Figure 31. Selecting a macro for the content model of the <animalName> element in Roma.

We want to include a reference to a macro, so “macroRef” is the block we’ll want to add. This is done by dragging that block into the graphical editor screen of Roma. Next, clicking the arrow in that “macroRef” block calls a dialog window where the macro.phraseSeq macro can be selected via the plus sign next to it. Finally, make sure to drag this populated “macroRef” block into the empty space of the blue “content” block in the graphical editor (you’ll hear a little “click” sound if it succeeds):

Figure 32. Adding a macro to the content model of the <animalName> element in Roma.

Now it’s time to inspect our ODD customization: store the ODD file via the “Download” > “Customization as ODD” button at the top right of the Roma screen. The resulting ODD file looks as follows:

We see how an extra <elementSpec> element is added to the ODD file, with the definition for our newly added <animalName> element. Its name is given in the @ident attribute, and @mode="add" indicates that this is a new element. The @ns attribute contains the namespace URI we specified for this element.

The description of our brand new <animalName> element is provided in a <desc> element. Its class membership is declared in a <classes> element; each of the attribute and model classes we had selected, is listed in a separate <memberOf> element, whose @key attribute identifies the relevant class. The content of the element is declared within a <content> element. Since we included the shortcut to the macro.phraseSeq macro, this is recorded in a <macroRef> element, whose @key attribute identifies the macro.

In order to give an impression of the convenience of macros, let’s see what this macro.phraseSeq macro resolves to when the ODD file is being processed:

We’ll not go into full details here, but you’ll be able to understand that this macro defines a sequence with zero (@minOccurs="0") or more (@maxOccurs="unbounded") combinations of plain text nodes (<textNode/>), or the elements from the 4 model classes identified in <classRef>. For full coverage of the definition of content models: see section 22.5.1.1 Defining Content Models: TEI of the TEI Guidelines.

6.2. Adding Attributes #

So far, we have customised our schema for the transcription of the Alice text in such a way that we can distinguish between person, place, and animal names, either with specific @type values of the generic <name> element (namely "person", "place", or "animal"), or by means of the TEI elements <persName> and <placeName>, and the non-TEI element <animalName>. We fine-tuned all elements belonging to the att.naming class by deleting the unneeded @nymRef attribute from this class.

For our specific analysis of Alice’s Adventures in Wonderland we would like to experiment with a basic way of adding further information on the ontological status of the referents of the names in this fictitious story: it could be interesting to analyse the characters in terms of the kind of reality they exist in. A possible place for such information could be the @type and @subtype attributes of the att.typed class. However, we would prefer a more specific label for this kind of information, and reserve these TEI attributes for possible different categorisations in the future. Therefore, we want to add a new attribute to our customisation. Similar to deleting attributes, adding new ones can happen on two levels:

• element level: attributes may be added to an individual element, which will apply to this element only
  → This is accessible in Roma via the “Attributes” button in an element’s definition (via the “Elements” tab), where you can click the plus sign in the “Element attributes” row. In ODD, it will affect the attribute definition inside an <elementSpec> element.
• class level: attributes may be added to an attribute class, which will apply to all elements that are member of this class
  → This is accessible in Roma from the attribute class’s definition (via the “Attribute Classes” tab), where you can click the desired class name, click the “Attributes” button, and add additional attributes to the class. In ODD, it will affect the attribute definition inside a <classSpec> element.

In this case, information on the ontological status of names’ referents not only applies to personal and place names, but also to our recently added animal names, names in general, and by extension all kinds of referring strings. This suggests the att.naming attribute class as a good place to add this attribute.

Let’s head over to Roma! Click the “Attribute Classes” tab for our TEI customisation, click the att.naming class, and next hit the “Attributes” button.

Figure 33. Editing an attribute class for a TEI customisation in Roma.

This calls an overview of the attributes in this class (notice how the @nymRef attribute still is excluded from our modification). Adding a new attribute to an attribute class can be done by clicking the plus sign in the “Class attributes” row. This produces a dialog window:

Figure 34. Creating a new attribute in Roma.

This form asks us first for the name of this new attribute. Before we start defining the attribute, some thought is needed on its design. Following examples could illustrate different possibilities:

Attributes could be designed as binary choices taking some form of truth value, as categories taking some kind of degrees on a scale, as neutral labels taking a list of keywords, or many more. As we are in the early stages of the encoding project, and feel this ontological classification is still experimental, we can anticipate that categories are likely to pop up, merge, or be adapted along the way. Therefore, it makes most sense to design it as a general semantic field, allowing for an open-ended list of keywords. Considering these requirements, a sensible name for this attribute could be “ontStatus.” Let’s fill that name, and click the “Create” button. Now, this (empty) attribute definition is added to the list of “Class attributes.” In order to define this attribute, click the pencil icon next to its name. This will produce a page similar to the one we’ve seen before (when restricting the values of the @type attribute for <name>). We’ll define this @ontStatus attribute as an "optional" attribute, by selecting this in the dropdown box next to “Usage.” In the “Description” field, we can provide a description, such as:

Figure 35. Editing documentation for a new attribute in Roma.

The other fields define the actual content of the attribute. For this example, suppose that an initial (experimental) categorisation for the ontological status of the people, places and animals in the Alice story could look like this:

• "realistic": the referent can / could occur in the extra-textual reality
• "mythological": the referent does not exist in real life, but belongs to a major mythology
• "fantastic": the referent belongs to an idiosyncratic fantasy universe

However, it is prone to be extended with other categories, and would probably allow more categories to be applied simultaneously, for names referring to ambiguous creatures or places.

This analysis obviously translates into a “semi-open” list: choose that option for the “Values” field. Attribute lists in ODD can have three types:

"closed"

only the values defined in <valList> are permitted

"semi"

the values defined in <valList> are treated as suggested values, but others are allowed

"open"

any value is allowed (as long as it complies with the datatype); values in <valList> are treated as mere examples

Suggested values can be entered in the text field of the “Values” field, and next pressing the plus sign next to the value. Let’s add the values mentioned above, as well as their description.

Figure 36. Defining attribute values for a new attribute in Roma.

Finally, the datatype for the attribute’s value can be declared in the “Datatype” field. The TEI datatype teidata.enumerated, which is explicitly designed to define a single word from a list of possibilities, seems the best fit.

Figure 37. Defining the datatype for a new attribute in Roma.

In the introduction to this section we stated that extending the TEI always leads to TEI document models that are broader than and hence possibly incompatible with the standard TEI model. For maximal separation of extension features from the standard TEI model, the TEI Guidelines therefore advice to define extensions in their own namespace. We already did so when adding new elements in the previous section. Let’s declare the same namespace http://teibyexample.org/ns/TBE in the “Namespace” field for our @ontStatus attribute:

Figure 38. Defining a namespace for a new attribute in Roma.

To save these changes as an ODD file, click the “Download” > “Customization as ODD” button at the top right of the Roma screen. We’ll notice how a defintition of the new @ontStatus attribute now is added to the <classSpec> declaration for the att.naming attribute class:

Since we added the @ontStatus attribute to the att.naming attribute class, the corresponding <attDef> declaration is added to the list of attribute declarations of the corresponding <classSpec> element. As before, the class specification’s @mode attribute is set to "change", indicating that only the declarations present in this ODD file will update the existing TEI definitions. Inside the <attList> section, the @nymRef attribute still is deleted, in accordance with our previous changes.

However, there’s a new <attDef> element for our @ontStatus attribute (identified in the @ident attribute), this time with the value "change" for its @mode attribute (since there was no existing definition for this element, this has the same effect as @mode="add"). The "opt" value for the @usage attribute indicates that the @ontStatus attribute will be optional in our customisation (required attributes would have "req").

Inside the attribute definition, the <desc> element contains the prose description of the attribute. The datatype of the attribute is defined in <datatype>. By means of a <dataRef> element, it is referring to the existing TEI datatype definition "teidata.enumerated" (which is given as the value for its @key attribute). This datatype basically restricts the possible values to strings consisting of words or a limited range of punctuation marks. Combined with the declarations in @maxOccurs, this means that the @ontStatus attribute for <animalName> can contain a white space separated list of word characters and some punctuation marks.

Finally, the list of possible values is given inside <valList>, which is declared as a semi-open list. Each of these values is given in its own <valItem> element, with a description of that value in <desc>.

6.3. Other Types of Extension #

Besides these common cases of TEI extension, involving the addition and deletion of elements and attributes, TEI can be extended in both more subtle and complex ways:

• existing TEI elements can be renamed
• content models of existing TEI elements can be broadened
• datatypes and occurrence indicators of attributes can be broadened
• existing TEI elements can be redefined to different model classes

Most of these types of customisations make use of the mechanisms covered in this tutorial. However, these kinds of modifications are considered advanced topics and are not treated in this introductory tutorial. For more information, you are referred to chapters 22. Documentation Elements and 23. Using the TEI of the TEI Guidelines.