Text only | Skip links
Skip links||IT Services, University of Oxford

1. Before you start

In this exercise, you will use Roma, a web tool available from the TEI web site and usable with any web browser: Firefox or Internet Explorer or Opera for example. Once you have created your schema, you will also need an XML-aware editor: oXygen in our case.

Our goal is to make a schema which we can use to mark up Punch pages. We don't need all of of TEI Lite, much less the full TEI, but we do need bits of various modules. We'll also have to tinker with some of the modules, to make our schema more helpful with daily editing.

2. Making your own schema

  1. Open the Roma application, by pointing your favourite web browser at http://www.tei-c.org/Roma/ or if for any reason that isn't working, there is a development version at http://tei.oucs.ox.ac.uk/Roma/
  2. The Roma start screen allows you to create a new customization, or to upload an existing customization for further work. We will start from scratch, which means ticking the first radio button ("Build schema (Create a new customisation by adding elements and modules to the smallest recommended schema)"). Press the Start button at bottom left of the screen to continue.
The next and subsequent screens show you a row of tabs which you can select to carry out a part of the customization process:
New
start making a new customization
Customize
set the name, description etc. for the customization and also the interface language
Language
set the languages to be used for names in the generated schema and for the documentation
Modules
select the TEI modules you wish to operate on
Add Elements
define new (non-TEI) elements for use in the generated schema
Change Classes
modify existing attribute class definitions
Schema
generate a schema in DTD, RelaxNG, or W3C Schema language
Documentation
generate human-readable reference documentation in HTML or PDF
Save Customization
generate an ODD file defining the current customization
Sanity Checker
run a consistency check of the modifications made to a schema

At the foot of each screen is a red Save button: remember to press this before moving on to the next tab, or your changes will have no effect.

We won't explore all of these options in this tutorial.

  1. Change the name of the schema to tei_ipp
  2. If you want to change the interface language, select the language of your choice (but the rest of this exercise assumes you are working in English.
  3. Select the Modules tab to proceed.
The modules screen shows two lists: on the left are all available TEI modules; on the right are the modules currently selected for your schema. You can add modules from the list on the left, and remove modules from the list on the right, by clicking the appropriate word next to the module you wish to operate on.
  1. For this exercise, we will need the following extra modules:
    • figures
    • corpus
    • namesdates
    Click the word add next to the name of each module.
  2. The modules chosen contain many more elements than we need, so we will now remove some of them, simplifying the view in the XML editor. Click the name of a module in the List of selected modules (the right-most column) to see a list of the elements this module defines.

Each element listed has a name, a radio button indicating whether it is to be included or excluded, a tag name, a description, and a link to a further screen where its attributes are specified. You can toggle inclusion or exclusion of all elements in the list by clicking the appropriate column heading. You can click on Exclude to remove all elements from the module.

Now work down the list clicking the radio button to restore or add elements. We make suggestions for the elements you will need to have in your schema for this and the following exercises, but feel free to add others if you wish. Remember to press the Submit button when you have finished with each module. Press the Modules or back links to go back to the list of modules.
from the core module
delete everything except <cit>, <date>, <desc>, <emph>, <foreign>, <gap>, <graphic>, <head>, <hi>, <item>, <l>,<label>,<lg>,<list>, <mentioned>, <milestone>, <name>,<note>, <p>, <pb>, <ptr>, <quote>, <ref>, <said>, <soCalled>, <sp>, <speaker>, <stage>and <title>
from the header module
delete everything except <availability>, <change>, <distributor>, <edition>, <editionmStmt>, <encodingDesc>, <fileDesc>, <idno>, <keywords>, <profileDesc>, <projectDesc>, <publicationStmt>, <revisionDesc>, <samplingDecl>, <sourceDesc>, <teiHeader>, and <titleStmt>
from the textstructure module
delete everything except <TEI>, <back>, <body>, <div>, <front>, <signed>, and <text>.
from the figures module
delete <formula>.
from the namesdates module
... well, it's up to you which elements you will need here. But you should probably retain at least the following: <affiliation>, <birth>, <death>, <education>, <event>, <forename> <listPerson>, <occupation>, <persName>, <person>, <placeName>, <state>, <surname>, and <trait>.

We are now ready to generate a schema. Click the Schema tab, and then press Submit, taking the default option of a RELAXNG compact schema. Your browser will ask whether you want to save or open the generated file: save it to your Desktop. Then complete this stage by going to the Save Customization tab of Roma and saving your work as a file on your desktop. Do not close the web browser, as we'll use it again shortly.

3. Using your schema in oXygen

You can use oXygen and the file you just made to check that your schema is correct. Proceed as follows:
  • Open the file you made earlier in oXygen.
  • Delete the line at the top of your file that looks like:
    <?oxygen RNGSchema="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/teilite.rng" type="xml"?>
  • Then go to the menu Document, then XML Document and then Associate Schema. Choose the RELAXNG tab, and locate your schema file (using the middle folder icon on the right to browse).
  • If all goes well, oXygen will insert some code to mark the schema location, and attempt to validate the file. Try inserting some new elements, and you should see a much-reduced collection.

4. Enhancing your schema

Our schema now includes only the elements we want for the Punch project, but we would like to constrain it further. For example, we have used the type attribute on the <div> element to categorize each component of an issue by means of a code. It would be useful to make sure that this code is always present, and also to make sure the values used all come from the same fixed list.

Go back to Roma. (If you have closed the browser, you will need to restart Roma and reload the session you saved earlier). Go to the Modules tab and click on textstructure in the right-hand column. Find <div> and click on Change attributes on the right-hand side. This will show you all the attributes of <div>. Click on type, and you will be able to change its properties:
  1. Change the Is it optional radio button to make it compulsory
  2. Change the radio button for Closed list? to make it a closed list
  3. In the box for List of values, type
    cartoon,verse,drama
    (ie a list of possible values, separated by commas).
  4. Click on Submit Query
Now save the schema as before and reload your file in oXygen. There should be validation errors, because some <div>s in the file have no type attribute specified. Supply a value and validate again: try giving an illegal value to check that your list of legal values is being respected.

Now we will add a completely new element. As you've probably noticed, Mr Punch is very fond of combining a quotation from some other newspaper with a sarcastic comment, and using the result to fill up space on the page. The TEI already has an element for the combination of a quotation and a bibliographic reference (<cit>); we will define a new element called <citCom> for the combination of that with an optional comment.

  1. Re-open Roma if necessary.
  2. Select the add Elements tab.
  3. Enter citCom as the name of the new element, and supply a brief description for it.
  4. This element can appear anywhere within a <div> element, so make it a member of the model.divPart model class by checking the tick box next to that name.
  5. We want this element to have a type attribute, so make it a member of the att.typed attribute class by checking the tickbox next to that name.
  6. In dropdown list labelled Contents select User content: we want to define our own content model for this element.
  7. Complete the <content> element in the box below by adding the following set of declarations:
    <rng:ref name="cit"   xmlns:tei="http://www.tei-c.org/ns/1.0"/>
    <rng:oneOrMore>
     <rng:ref name="model.pLike"/>
    </rng:oneOrMore>
    which says that a <citCom> must have a <cit> followed by one or more members of the model.pLike class.
  8. Save your changes, generate your schema, and use Oxygen to check that your new element is now available for use.

Note that your new element is defined in a new namespace because it is not a TEI element — it is unique to the IPP.

5. Documenting your schema with Roma

One of the major benefits of Roma is that after you have customized your schema it can produce two ways of documenting the changes you have made.
  • Select the Save Customization tab to save an ODD file
  • Select the Documentation tab to convert the ODD file into human-readable documentation in HTML or PDF.

The ODD file indicates how your schema differs from full TEI, what modules you have included, what elements you may have added and changed, and so forth. You should keep this file along with with your generated schema, in case you need to generate a new schema with additional elements or constrain it further. Other people can generate the schema for your documents in different schema languages if needed. Moreover, this document, like other ODD files, is an ordinary TEI document which you can edit using OxyGen fir example see.

The HTML or other documentation generated by Roma looks like a subset of the standard TEI reference manual. Because the TEI is itself maintained as a very large ODD file, Roma has access to all the information in the Guidelines about all of the elements, attributes, classes, or macros you've chosen to include in your customization, and can include it in your user project manual.

6. Other things to try with Roma

  1. How do you go about renaming an existing element? What happens in the ODD when you do?
  2. Once you have an ODD, you can generate project-specific documentation. Where would you put this prose in the ODD file? Try generating some test documentation with additions you have made.
  3. Experiment with starting with different exemplar customization Roma offers. Which do you think would be best for your project?
  4. Save the ODD for the TEI ALL Plus schema — how does this add in schemas from other namespaces?
  5. Try modifying the schema specification in your ODD using oXygen. If you remove one of the <elementSpec mode="delete"> lines what happens? Try improving the documentation of the changes you made in the schema. Try adding some usage examples.


James Cummings. Date: 2009-07
Copyright University of Oxford