Module 8 Sections

Table of Contents

Export

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.