Creating a Customization with Roma

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.uk/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_seminar/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_seminar/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_seminar/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.