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
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:
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.)
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.
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
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.
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.
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.