Customizing the TEI with Roma

Roma: a web application for TEI customization

The Roma web application provides a way to specify what you want in an ODD specification without having to write the XML code. It does not cover everything which is possible in the ODD language, but should provide a convenient interface for most tasks, and for TEI customization in particular.

You can start a Roma session by choosing from a set of suggested minimal ODD specifications, or by uploading an existing ODD XML file. This allows you to do some work with Roma, save the state of the ODD specification, and then reload it for more changes in a later session. Figure 1, Roma: opening dialogue shows the initial dialogue.

The main Roma screen lets you choose between nine activities, each represented by a separate tab, which are listed here and described in more detail below:

New: Start a new schema specification.
Save: Save the current state of the specification.
Customize: Specify metadata about the schema (name, authorship, licensing) and the language in which you want Roma to operate.
Modules: Choose the modules which will be included in the schema.
Add Elements: Create new elements.
Change Classes: Change attribute classes and create new attributes.
Language: Select the language in which your elements, attributes, and documentation will be generated.
Schema: Generate your customized schema in a choice of schema languages.
Documentation: Generate customized documentation in a variety of formats.
Help: Turn on help for each screen.

New: Start a new schema specification

The opening page for Roma offers several options:

Build schema: This option allows you to start building your schema customization by starting with a very minimal schema and adding modules to it. This is a good starting point if you want to build a fairly small, tightly constrained schema.
Reduce schema: This option allows you to start building your schema customization by starting with a very large schema including all of the TEI modules, and then removing what you don't need. This is a good starting point if you want to build a very extensive schema including most of the TEI modules.
Create customization from template: This option allows you to build a schema starting from one of the templates listed in the accompanying menu; these serve as convenient starting points from which you can then make further modifications, such as adding or deleting modules or elements.
Open existing customization: This option allows you to upload an existing customization file, either one that you may already have saved, or one that you have received from someone else. You can then make further customizations to this file and save the revised version.

When you've made your choice, click ‘Submit’. The image below shows the starting dialogue for Roma.

Figure 1. Roma: opening dialogue

Customize

When you have chosen one of the options listed above and clicked ‘Submit’, your next step will be to enter some basic metadata about the schema specification you're creating:

Title: this is the title by which you refer to your schema; it will appear in the accompanying documentation and in the TEI header for your customization file.
Filename: this is the filename for your customization file (the name under which it will be saved on your computer)
Prefix: this is the prefix that will be used within the schema to designate TEI pattern names
Language: this allows you to choose a language for the Roma interface (it does not affect the language of the resulting schema or documentation)
Author name: the name of the author of the schema customization
Description: a brief description of the schema you're creating, perhaps with some explanation of what it is intended for. This description will appear as a descriptive paragraph at the start of your customization file.

Once you have filled in the metadata fields, click ‘Submit’ to save the information. The image below shows the interface for the Customize window.

Figure 2. Roma: schema customization summary

Language selection

The Language tab in Roma allows you to select the language(s) in which your schema will be expressed: the language used for element and attribute names, and the language for the reference documentation that is generated for your schema. You may choose different languages for these two components (for instance, element and attribute names in German, and reference documentation in Spanish). Click the appropriate buttons to select, then click ‘Submit’.

Module selection

The Modules tab in Roma allows you to select which modules will be included in your schema, either by removing modules from a large schema (if you chose ‘Reduce...’ in the opening screen) or by adding modules to a small schema (if you chose ‘Build...’). The full list of available TEI modules is listed on the left, and at the right there is a ‘List of selected modules’ which is the list currently selected for your schema. You can add to this list by clicking the ‘add’ link next to any module. To remove modules from the list, click the ‘remove’ link. The image below shows the module selection interface.

Figure 3. Roma: selecting modules

If you want to make more detailed customizations by including or excluding specific elements in a module, click on the name of the module. This will take you to a window that allows you to choose which elements from that module should be included or excluded. You can also change the name of any element by editing the ‘Tag name’ field. You can edit the attributes for an element by clicking on the ‘Change attributes’ link to the right. When you've finished your selections, click ‘Submit’, and then click the ‘back’ link at the top of the page to return to the module selection page. The image below shows the element editing interface.

Figure 4. Roma: changing elements in a module

When you have finished selecting modules, if you are happy with the resulting schema you can save it and generate a schema and documentation (see below).

Save your schema specification

When you have finished specifying your schema choices, or when you come to a stopping point, you should save your schema specification. Click the ‘Save’ tab and choose ‘Save file’ at the prompt. The schema specification will be saved to your local computer as an XML file with the filename you chose when you initially set up the specification parameters. To make further changes, you can upload this file at the opening Roma page.

Adding a new element

The ‘Add Elements’ tab allows you to add a new element to your schema (for instance, to describe a textual feature for which there is no element provided in TEI). To define a new element, you must specify a name for the element, and provide a brief description of what it is for. This description will be included in the element specification and in the generated reference documentation for your schema. You must also choose a model class in which this element will appear. The model class determines the contexts in which the element may be used. The names of the model classes indicate the kinds of functions their members possess; for instance, the model model.frontPart includes elements that may appear within <front> as part of the front matter of a document. Brief documentation of the purpose of each model class will appear as a pop-up window if you mouse over the class name. You must choose at least one model class, and you may choose more than one. You should be careful in choosing model classes, since it is possible to choose incompatible classes with bizarre results. (The ‘Sanity Checker’ tab is intended to help you detect incompatible choices.)

After choosing the model class(es) for the new element, you can also choose one or more attribute classes to which it will belong. These will determine what attributes the element will have. All elements carry the global attributes (xml:id, n, xml:lang) by default. As with the model classes, the names of the attribute classes indicate something of their function; the att.damaged class includes attributes needed to describe damage to a portion of text (extent, hand, agent, and several others). Brief documentation of the purpose of each attribute class will appear as a pop-up window if you mouse over the class name.

You can express the content of the new element by using one of the macro classes in the menu given, or by writing your own element specification in RELAX NG XML syntax in the box at the bottom of the screen.

When you have finished defining the element, click ‘Submit Query’ to save it. The image below shows the interface for adding elements.

Figure 5. Roma: adding a new element

Changing attribute classes

You can change or remove attributes from a given attribute class using the ‘Change Classes’ tab. A list of all attribute classes is given, with a brief description of each one. You can see the members of each class and their details by clicking on the name of the class; the image below shows the class details interface.

Figure 6. Roma: display of class details

If you click on the ‘changeAttributes’ link for a given attribute, you will be able to choose whether this attribute is to be included or excluded from the attribute class in question in your schema.

Figure 7. Roma: changing attribute classes

If you want to change other aspects of the attribute, clicking on the name of the attribute will allow you to edit the attribute definition, including its permitted values and whether or not it is required. The image below shows the editing interface; note that the heading reads ‘Add a new attribute’, but since we are editing an existing attribute the attribute name and class name are already filled in.

Figure 8. Roma: editing class attributes

When you have made your changes, click ‘Submit Query’ to save them. You can return to the list of attributes by clicking ‘go back to list’ at any time.

Adding a new attribute

To add a new attribute from within the ‘Change Classes’ tab, click first on ‘Change Attributes’ and then on the ‘Add new attributes’ link at the top of the list. This will allow you to define new attributes to be added to the attribute class selected. The following options are given:

Class name: this tells you which class you're adding the attribute to
Is it optional?: indicates whether or not a value is required
Contents: this field allows you to specify the datatype for the attribute and the permitted number of values
Default value: this allows you to specify a default value for the attribute (though this will only have effect if you are generating a DTD; other schema languages do not permit defaulted attributes)
Closed list: this indicates whether the values permitted for the attribute are strictly limited to the values given (in the ‘List of values’ below) or whether those values constitute only a set of preferred choices, with other values permitted as well.
List of values: you may enter here a list of permitted values for the attribute.
Description: this is a brief description of the purpose of the attribute, which will appear in the reference documentation.

When you have completed the information for the new attribute, click ‘Submit Query’ to save it. The image below shows the interface for adding a new attribute.

Figure 9. Roma: adding a new attribute

Generating your schema

Once you have completed your customization (and saved the resulting customization file using the ‘Save’ tab), you can next generate a TEI schema that reflects your customizations by clicking on the ‘Schema’ tab. You can choose from four options: a RELAX NG schema in either the compact syntax or the XML syntax; a W3C Schema; or a DTD. When you have made your choice, click ‘Submit’. You will be prompted to save a file; the filename will be the one you chose when you entered the metadata at the very start of the process, with a suffix reflecting your choice of schema languages a moment ago. Save this file to your computer. The image below shows the interface for schema generation.

Figure 10. Roma: generating documentation (choice of formats)

Generating custom documentation

In addition to generating a custom schema, Roma can also generate a customized version of the TEI reference documentation (the documentation of elements and attributes which constitutes Appendixes A, B, and C of the TEI Guidelines, and which many XML editors use to display context-sensitive documentation). The customized version will reflect your module choices and removal of specific elements and attributes, modification of attribute and element definitions, and new elements or attributes you may have defined. It thus constitutes a much more tightly focused set of documentation which reflects the realities of your own specific schema.

To generate the custom documentation, click on the ‘Documentation’ tab and choose the output format you prefer (HTML, PDF, TEI, or TEI Lite). When you click ‘Submit’, you will be prompted to save the resulting file. The image below shows the document generation interface.

Figure 11. Roma: generating documentation (choice of formats)