Creating a Customization with Roma
author: Syd Bauman
language: en
availability: Copyleft 2006 by Syd Bauman

Before you start

In this exercise, you will use Roma, a web tool available from the TEI web site and also included on the TEI Ubuntu CD, to make an XML schema. If you are not using the TEI Ubuntu CD, you will need access to the internet and a web browser such as Firefox or Opera. Once you have your schema you will also need an XML-aware editor to use it (e.g., oXygen).

These instructions only cover part of Roma's functionality. They describe the steps needed to

- select modules,
- delete elements,
- delete attributes, and
- constrain attribute values

. These instructions do not cover some other capabilities of Roma, including adding elements; changing an element’s class membership, contents, or description; changing an attribute's permitted values (other than to a closed list of values); changing the language of Roma interface itself or of the elements & attributes generated.

Getting started

- Open the Roma application. If you are on-line, you can point your favorite web browser to http://www.tei-c.org/Roma/, or, if you are working from the CD, to http://localhost/Roma/ (on the TEI Ubuntu CD the recommended web browser is Mozilla Firefox, available on the toolbar; but you can also use Konqueror or even Lynx if you prefer).
- You should get to the Roma start screen, which says something like “Roma: generating validators for the TEI” at the top. Check the “Build schema” radio button (the top button, may be selected by default) and then the “Submit” button.

Notice that if you already had a customization file (typically a .odd file), you could have uploaded it to make further changes, rather than starting from scratch.

Subsequent pages have a row of tabs for each of the major tasks involved in making a customization (“Modules”, “Add elements”, “Change classes”, and “Language”) for creating various outputs from a customization (“Schema” and “Documentation”) and for acting on your customization (“New”, “Customize”, and “Save”). Several of these tabs are explained briefly in the instructions that follow.

The Customize page allows you to change 5 parameters:

Title
- The name of your customization; used as the <title> in the TEI header of the ODD file, and also as the <title> and <h1> of the HTML documentation
Filename
- Used as the base filename for the output schema (with .rnc, .rng, .xsd, or .dtd appended), the output documentation (with _doc.html appended), and the saved ODD file (with .xml appended). It's a good idea to avoid characters that may confuse operating systems like slashes, back-slashes, colons, spaces, etc.
Language
- Allows you to select which language Roma uses on some of its web pages. Not all parts of all pages have been translated.
Author
- The name of the author of the customization; used as the <author> in the TEI header of the ODD file, and also in a <meta> element of the HTML documentation.
Description
- The contents of this parameter are put inside a <p> inside the <body> of the ODD file, and thus show up as text near the top of the HTML documentation.

After changing any parameters, it is necessary to press the “Submit” button in order for Roma to record the changes. Note, however, that the page may not change when the submit is performed.

Customizing

Modules

Click on the “Modules” tab (usually a blue tab near the top, under 2 lines of headings). This should bring you to the Modules page.

On this page there are two lists: on the left are all available TEI modules; on the right are the modules currently selected for your schema. By default the four required modules are listed on the right. You can add modules from the list on the left by clicking on the word “add” next to the desired module name. You can remove modules from the list on the right by clicking on the word “remove” next to the module you no longer wish to include. Note that Roma will permit you to remove three of the four required modules (core, header, textstructure), but you will end up with an invalid schema. (It is not possible to remove tei, because Roma cannot generate a schema at all, valid or invalid, without it.)

Elements

It is often the case that the modules chosen contain many more elements than are desired. Removal of elements is performed on a module by module basis. First click on a module name from the List of selected Modules (the right column), e.g. core. This should take you to the appropriate Change module page.

On this page each element defined by the module is listed along with a radio button indicating whether it is to be included or excluded, a place to change its name, its brief description, and a link to a further page where its attributes are specified.

For any element you do not want in your schema, simply select the Exclude radio button. For example, if you know that the material you are encoding does not contain any poetry, you will probably wish to click the Exclude radio buttons for <l> and <lg>. You can include or exclude all elements in the list by clicking the appropriate column heading.

It is necessary to press the “Submit Query” button (white near the bottom of the page) before switching to a different tab, lest all the changes you've made on this page be lost. The only indication that your changes have been recorded is a message near the top of the page. Press the “Modules” tab or the “back” link to go back to the list of modules.

Attributes

For each element in the Change modules page there is a “Change attributes” link on the right. Clicking on this link will bring you to a page for changing or adding attributes called Added Attributes. Note that Roma will happily allow you to think you are changing the attributes for an element that has been excluded, but this will have no effect on your customization.

For each attribute, its canonical name is provided on the left, and radio buttons for inclusion and exclusion just as for elements follow. There is a field that permits you to change the name of the attribute, and a brief description of it.

Clicking on an attribute's name from the left column brings you to a page that permits you to customize that attribute for the given element. (It is mis-named the Add some attributes page because it is the same page that is used for actually adding a new attribute — in this case the fields have been populated with the values for the attribute you are changing.) If you want to change an attribute for all elements on which it occurs, you would need to change it in its class (Roma permits this, but it is not covered in this document).

The page for attribute modification permits you

- Choose whether the attribute is required or optional
- Select its content, e.g. data.enumerated for a list of particular values
- Choose a default value (should be left blank unless you know your software handles these)
- Choose whether a list of values is open (values other than those listed are permitted) or closed (only the listed values are permitted). This should have no effect unless there is a list of values.
- Specify a list of values: a comma-separated list of XML Names.
- Write a more detailed or specific description of the attribute. This description will appear in the reference documentation for your schema.

Remember to click on the “Submit Query” button at the bottom of the Add some attributes page after you have modified the attribute to your liking. This should bring you back to the Added Attributes page.

Clicking “Submit Query” on the Added Attributes page does not bring you back to the Change module page. The only way I know of to get back is to click on the “Modules” tab and then the module name again.

Saving your ODD file

Clicking the “Save” tab downloads the ODD file that Roma has generated to your local system. The default name is the filename specified in the Customize page with .xml appended. Some people like to change the .xml to .odd. Either way, you should always save your ODD file, or you will have to go through all this work again anytime you want to modify your customization.

Your browser will download files to its default location or ask you where they should be put. For our purposes today you should put this (and other Roma-generated files) in your TEI_exercise/support/ folder, which you can place wherever you like.

Outputs

To generate reference documentation in HTML, select the “Documentation” tab. Leave the output type at the default “html”, and click “Submit”. Put the downloaded file into your TEI_exercise/support/ folder. To read it, open it with your web browser.

To generate an output schema select the “Schema” tab. Here you can change the desired schema language of the schema Roma will generate and download when you click “Submit”. For our purposes, leave the default, RELAX NG compact syntax. Put the downloaded file into your TEI_exercise/support/ folder. To use it to constrain an XML document you are already editing with oXygen, choose “XML Document > Associate schema…” from the “Document” menu. From the “Associate schema…” dialog box select the “RELAX NG Schema” tab and the “Compact syntax” radio button; then select the file you just downloaded by clicking on the plain folder next to the URL box.