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

1. Exercise 1: OxGarage

Visit http://oxgarage.oucs.ox.ac.uk:8080/ege-webclient and check that you can make documentation in Word or ePub format using your working ODD file.

2. Exercise 2: laying out the source

Let's organize our work a bit. Open your working file in oXygen and rearrange the changes into a series of <specGrp> containers, one for each module you have changed (or another arrangement if you prefer). The body of your file may end up looking like this
<specGrp xml:id="tei-module">
 <moduleRef key="tei"/>
</specGrp>
<specGrp xml:id="header-module">
 <moduleRef key="header"/>
</specGrp>
<specGrp xml:id="core-module">
 <moduleRef key="coreexcept="ab"/>
</specGrp>
<specGrp xml:id="textstructure-module">
 <moduleRef
   key="textstructure"
   except="div1 div2 div3 div4 div5 div6"/>

</specGrp>
<schemaSpec ident="test">
 <specGrpRef target="#tei-module"/>
 <specGrpRef target="#core-module"/>
 <specGrpRef target="#textstructure-module"/>
 <specGrpRef target="#header-module"/>
</schemaSpec>

Check that this works to create a schema, and documentation. Look and see how the HTML comes out.

Now you can enhance the documentation by putting each of those <specGrp>, and the <schemaSpec>, into a normal TEI <div> with heading, and start adding prose. eg
<div>
 <head>The main TEI module</head>
 <p>I am not going to make many changes here.</p>
 <specGrp xml:id="tei-module">
  <moduleRef key="tei"/>
 </specGrp>
</div>
To make the prose sections more informative, you can summarize elements (and optionally their attributes) in the prose section, eg
<specList>
 <specDesc key="att.globalatts="xml:id xml:lang"/>
 <specDesc key="gi"/>
 <specDesc key="ptratts="target"/>
</specList>

Add a stanza like this to one of your sections, run the documentation to HTML again, and see the effect of the <specList>.

3. Exercise 3: changing documentation and examples

We can now look at tailoring the generated reference documentation to suit your project, by overriding the <desc> of any element or attribute. Add this fragment to your ODD somewhere, rerun, and check the effect:
<elementSpec mode="changeident="ptr">
 <desc>A hyperlink, with no description</desc>
 <attList>
  <attDef ident="targetmode="change">
   <desc>The URL you are pointing at. Always use https:
       protocol for our project</desc>
  </attDef>
 </attList>
</elementSpec>
Notice that the summary generated by <specList> also changes.
We can also change the examples. Edit your ODD again, and add
<elementSpec mode="change" ident="ref"> <exemplum xml:lang="en"> <egXML xmlns="http://www.tei-c.org/ns/Examples"> <ref target="http://www.blondie.net/">Blondie, avec ses yeux si bleu</ref> </egXML> </exemplum> </elementSpec>
Now check how this comes out. It should replace the TEI example. If you change the value of xml:lang to ‘fr’ and re-run, you will not see the change unless you choose French documentation.

You can have as many examples as you want, in as many languages as you like.

Finally,some people like to actually rename TEI element names. This is possible, but not entirely recommended. Try this and see what happens:
<elementSpec ident="pmode="change">
 <altIdent>para</altIdent>
</elementSpec>

4. Exercise 4: Understanding <equiv>

In the previous exercise we ‘renamed’ a TEI element to make it more readable. What if we want a short cut, or ‘syntactic sugar’ for a particular use of a TEI element? A good example of this would be mimicking the HTML way of doing lists, with separate elements for <ul> and <ol> (unnumbered and ordered lists).

First use the <altIdent> technique to rename TEI's <item> to the HTML name <li>, and delete the existing <list> element in the usual way.

Now add a new element <ul> which is to map to TEI's <list type="unordered">:
<elementSpec ident="ulmode="add">
 <desc>Unordered list</desc>
 <content>
  <rng:oneOrMore>
   <rng:ref name="item"/>
  </rng:oneOrMore>
 </content>
</elementSpec>
Notice that the content model references <item>, not <li>, as internally the schemas use the original name, not the one in <altIdent>.
Now do the same thing for <ol>, make the schema, and test a file containing a list of the form
<ul>
 <li>cats</li>
 <li>dogs</li>
</ul>
The new <ol> and <ul> elements are currently free-standing, so the next stage is to explain how they map to normal TEI. We do this with <equiv>. Stage one is to add an instruction to the ODD, eg:
<equiv filter="mymap.xslmimeType="text/xslname="ul"/>
which says that the mapping of <ul> is explained in the file mymap.xsl. Create an XSL filter, looking like this:
<xsl:stylesheet
  xpath-default-namespace="http://www.tei-c.org/ns/1.0version="2.0">

 <xsl:template name="ul">
  <list xmlns="http://www.tei-c.org/ns/1.0"
   type="unordered">

  <xsl:apply-templates
    select="@*|*|text()|comment()|processing-instruction"/>
</list>
 </xsl:template>
</xsl:stylesheet>

You can create a new XSL stylesheet to transform your instance files by running make-acdc.xsl on your ODD file, and then use the result to transform your instance XML.

5. Exercise 5: Building an ODD from scratch

Your final target is to write an ODD which can validate this file (newsample.xml):
<people>
 <person sex="1born="2010-11-06">Adam</person>
 <person sex="2born="2010-11-07">Eve</person>
</people>
checking that dates are valid, and that sex can only have the values 1 or 2

For extra points, can you write another ODD file which uses parts of your new one, and builds on them?

Of course, there are sample solutions for this in spoilers/new.odd and target="spoilers/new2.odd"/>, but try first!



TEI@Oxford. Date: 2010-07
Copyright University of Oxford