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

1. Before you start

This exercise is designed to get you to familiarise yourself with both the oXygen editing environment and the TEI manuscript description module by taking a basic manuscript description and giving it some real structure.

2. Starting oXygen

Start up oXygen. Optionally you may wish to shut down some of the helper views that oXygen provides on the left and right of the main editing screen.

3. Loading a document

Once oXygen has loaded and you've dismissed any helpful tips it wants to give you, load a file (File -> Open) by 'ex2.xml'. If oXygen opens the file up in 'Author' mode (and perhaps complains about a missing CSS file), ignore the complaints, close down any error message windows, and then when you are able to click on the word 'Text' next to 'Grid' and 'Author' in the bottom left.

4. Our basic <msDesc>

As you will notice this contains a fully complete, valid, and well-formed manuscript description. Technically it validates against the ENRICH-WACMP schema, but consists only of the required elements and attributes. The <msDesc> element has not only the TEI namespace delcaration but the required xml:id and xml:lang elements. You can tell it is valid because the upper right-hand corner contains a happy green square. Most of this exercise will be trying to get back to the situation of having this happy green square! This <msDesc> element contains inside it only two children, the <msIdentifier> element (with a <repository> element) and a <p> element containing the prose of the manuscript description from your first exercise.

5. Making a real <msIdentifier>

  1. Begin by highlighting and deleting the <repository> element but not its contents. To do this move the cursor to before the start of the opening <repository> tag, hold down the shift key and move to the end of the opening tag, and then press delete. Only the text ‘London British Library Cotton MS. Titus C. xv’ should be left. When you deleted the opening tag, notice that closing </repository> tag gets instantly deleted. oXygen knows that you are editing XML, so if the correct options are turned on tries to help you by deleting the closing tag.
  2. You will undoubtedly notice that the text you have left inside the <msIdentifier> element is underlined in red. This is a bad sign. Our happy green square in the upper right-hand corner has also turned red. Our document is not valid. We can know the location of the error from the red line in the bar on the right-hand side, and the content of the error from the message in the status bar at the bottom. This tells us that ‘text not allowed here’, which is indeed the case, you can't have free-text inside an <msIdentifier>, it must be wrapped in child elements. Hovering your mouse over the red box in the upper right-hand side of the editor will also provide a tooltip pop-up indicating the nature of the error.
  3. Return to the bit of text you have and highlight the word ‘London’. The from the 'Document' menu select 'XML Refactoring' and then 'Surround with Tags'. You may notice a shortcut key (usually 'Control-E') which does the same thing more quickly. When you selected this menu item, a pop-up dialog box will have appeared with a drop-down menu listing all the elements that are valid to have at this point in your document. One can use the drop-down menu or start typing in the box the name of the element you want if you know it. Select <settlement> and press enter or click 'ok'.
  4. Use the same method to put 'British Library' in a <repository> element, 'Cotton' in a <collection> element, and 'MS. Titus C. xv' in an <idno> element. Another way to create an element is to just start typing it. Try that now and see what happens (but delete any stray additional elements you create).
  5. Your document should now be well-formed and valid. (There should be no red lines or error messages, and that box in the upper right-hand corner should be green. If that isn't the case, make sure you have deleted any stray punctuation in between the elements. If you want to format and indent your document, from the 'Document' menu select 'XML Document' and then 'Format and Indent'. Notice that it also has a shortcut key and a toolbar icon. Your <msIdentifier> should now look something like:
    <msIdentifier>
     <settlement>London</settlement>
     <repository>British Library</repository>
     <collection>Cotton</collection>
     <idno>MS. Titus C. xv</idno>
    </msIdentifier>
    and your document should be well-formed and valid. If it isn't, correct it before continuing.

6. Creating an <msContents> element

  1. First we need to move the correct paragraph into its proper location. Highlight the paragraph that starts 'Contents:', including its opening and closing <p> tags, and from the 'Edit' menu select 'Cut' (or press control-x). Move the cursor to directly after the closing </msIdentifier> tag, press enter to insert a new blank line, and then 'Paste' from the 'Edit' menu (or control-v) to paste this paragraph back into its new location.
  2. Move the cursor directly after the 'p' in the opening <p> element, and press backspace. Notice that the name of the element from the closing tag also disappears. Type 'msContents', and it should automatically appear simultaneously in the opening and closing tags.
  3. You document should be invalid now, because you cannot have a mixture of structured <msContents> and unstructured <p> elements. Also the <title> element isn't allowed by itself inside an <msContents> element.
  4. Delete the text ‘Contents: ’ from the start of the element.
  5. Highlight everything inside your <msContents> element (but not its opening or closing tags), and surround it with an <msItem> element using the technique you learned above.
  6. Highlight ‘ff. 1-132v ’ and surround it with a <locus> element.
  7. At this point oXygen should stop complaining about your <msContents> element, but still complain about those nasty unstructured <p> elements below.
  8. Before moving on, let's make this <msContents> slightly better by adding some machine-processable metadata. Move the cursor just after the 's' inside the opening <locus> tag and press space. From the drop-down menu which appears to assist you in putting in attributes allowed on this element, select 'from' and type '1r' as the value. Move to just after the closing quotation mark and press space again, this time select 'to' and give it a value of '132v'. You can, of course, just type in these attributes and their values as well, but oXygen goes out of its way to attempt to assist you in doing this.
  9. Add an attribute 'type' to the <title> element, with the value of 'uniform'. Optionally, format and indent the document.
  10. While the document still isn't valid, because of the remaing <p> elements down below, there should be no red lines inside your <msContents> which should look something like:
    <msContents>
     <msItem>
      <locus from="1rto="132v">ff. 1-132v </locus>
      <title type="uniform">Mandeville's travels</title>
     </msItem>
    </msContents>

7. Structuring a <physDesc>

Using the techniques you've learned above of wrapping an element around some text (control-e) or just starting to type the element in ('<'), adding attributes, and cutting and pasting, aggregate the physical description information into a <physDesc> element and its possible children. Since you are becoming more familiar with oXygen, we won't spell things out in such detail.

  1. After your closing </msContents> tag, create a new <physDesc> element.
  2. Inside this create an <objectDesc> element that looks like:
    <objectDesc form="codex">
     <supportDesc material="perg">
      <support>Parchment. <dimensions unit="mmtype="leaf">
        <height>215</height>
        <width>150</width>
       </dimensions>
      </support>
      <extent>ff. ii+132+ii.</extent>
      <collation>
       <formula>1-4/8, 5/8 (wants 5-8), 6-17/8</formula>
       <catchwords>catchwords in scrollwork</catchwords>
       <signatures>signatures</signatures>
      </collation>
     </supportDesc>
     <layoutDesc>
      <layout columns="1writtenLines="24 30">24-30 long lines. Frame <dimensions unit="mmtype="written">
        <height>150</height>
        <width>100</width>
       </dimensions>
      </layout>
     </layoutDesc>
    </objectDesc>
  3. The text ‘Rebound in 1962.’ is not useful for the <physDesc> element, cut and paste it just after the last paragraph below for now.
  4. As you do this notice that some attributes are required, and some have supplied value lists from which you are not allowed to stray. Mostly, these are customisations for this particular schema.
  5. After the <objectDesc> create a <handDesc> with information about the scribal hands. It should look like:
    <handDesc>
     <handNote script="unknownscope="major">One <term type="script">cursiva
         libraria</term> hand: headless 'a'; ascenders of 'b', 'd', 'h', 'l', 'w'
       looped; otiose bar through ascender of 'h'; long and short 'r'; sigma-shaped
       final 's'.</handNote>
    </handDesc>
  6. Although your document remains invalid, you should have no red lines in the <physDesc> section before continuing. If you do, make sure to fix them first.

8. The importance of <history>

Most of the text of the paragraphs below should now be gone. Use the remaining text to create a <history> element containing the crucially important origin date and place (<origDate> and <origPlace>). Your history element should look something like:
<history>
 <origin>
  <origDate notBefore="1400notAfter="1425">Early fifteenth century.</origDate>
  <origPlace>Hertfordshire.</origPlace>
 </origin>
 <provenance>Owned by Giles Ruford and John Addams (both of the sixteenth century) and
   given by Sir Edward Walker (d. 1677) to Sir Thomas Cotton (d. 1662), whose library
   was presented to the nation in 1700 by his grandson, Sir John Cotten.</provenance>
</history>

9. Additional Information

Remember that text saying ‘Rebound in 1962.’, well now is the time to use it. Create an <additional> element just after your <history> element which looks like:
<additional>
 <adminInfo>
  <custodialHist>
   <custEvent type="conservation">Rebound in 1962.</custEvent>
  </custodialHist>
 </adminInfo>
</additional>

10. Happy Green Square = Save your file!

You should now have a valid <msDesc> and returned to the state of having a happy green square in the upper right-hand corner. If not, fix it now! Also, make sure to save a copy of the completed file, as we will want to use it in our next exercise.

11. Other things to think about...

  1. Looking at the image of the manuscript, what things have we not included in this basic manuscript description?
  2. What TEI elements might exist to record this information?
  3. Why have we recorded some information in attributes and other information inside elements?
  4. What TEI phrase level elements might you use to mark up the information further?


Date: February 2010
Copyright University of Oxford