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.
- Start a new schema specification.
- Save the current state of the specification.
- Specify metadata about the schema (name, authorship, licensing) and the language in which you want Roma to operate.
- Choose the modules which will be included in the schema.
- Add Elements
- Create new elements.
- Change Classes
- Change attribute classes and create new attributes.
- Select the language in which your elements, attributes, and documentation will be generated.
- Generate your customized schema in a choice of schema languages.
- Generate customized documentation in a variety of formats.
- Turn on help for each screen.
New: Start a new schema specification
- 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.
- 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.
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’.
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.
Changing attribute classes
Adding a new attribute
- 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.
Generating your schema
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.