1. Before you start

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

2. 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 browsing to the
your working directory and opening the file 'msDesc.xml'.

3. Our basic <msDesc>

As you will notice this contains a fully complete, valid, and
well-formed manuscript description. Technically it validates
against the ENRICH schema, which is a pure subset of the TEI
designed for standardising manuscript descriptions
internationally. However, this one 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. The msDesc contains inside it
only two children, the <msIdentifier> element (with the
required <repository>) and a <p> element containing
the prose of the manuscript description from your first exercise.
The materials directory also contains ‘f101-19a.jpg’ which
is an image of this manuscript if you are curious.

4. Making a real <msIdentifier>

Begin by highlighting and deleting the
<repository> element and its contents. To do this
move the cursor to before the start of the
<repository> tag, hold down the shift key, move to
the end of the closing </repository> tag, and then
press delete. When you do so notice that closing
</msIdentifier> tag gets underlined in red, that a
red line appears across from it on the right-hand bar, and
there is a red box in the upper right-hand corner. These are
all signs to you that there is an error and where it is.
Hovering your mouse over the red box in the upper right-hand
side of the editor will provide a tooltip pop-up indicating
the nature of the error. Alternatively, there should be an
error message in the status bar at the bottom. In this case
oXygen is complaining because the ENRICH schema requires
there to be either<repository> or a
<msName>

Return to the paragraph and delete the phrase 'Stored
in'.

Just after that highlight from the word 'Lithuania'
through until the end of the word 'Department.' including the
period. 'Cut' this text by pressing (usually) 'control-x',
and then after moving back up to the <msIdentifier>
paste it by pressing 'control-v'. oXygen should still
complain about you putting text here because it expects some
structure

Highlight the word 'Lithuania', and then select the menu
item 'Document -> XML Refactoring -> Surround with Tags'
(note that the shortcut key for this is 'control-e'). This
should pop up a window which allows you to choose any element
valid at this point to surround this bit of text with. Type
'country' and notice how it completes the word as you type
it. Pressing enter will inside the element around the text
'Lithuania'.

Delete the comma after Lithuania, press enter to move
'Vilnius' to a new line, highlight 'Vilnius', press
'control-e' and type 'settlement'. Press enter to insert this
element.

Delete the comma and press enter to move the rest of the
text down to a new line.

Use this same technique to add a <institution>
element around the text: 'Lithuanian National M. Mazvydas
Library'; and a <repository> element around 'Rare Book
and Manuscript Department'. Delete any unnecessary commas or
periods.

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.

Move to just before the closing </msIdentifier>
tag and press enter to insert a blank line inside it. Type
the open angle bracket '<' and notice what happens.
oXygen should provide you with a drop down list of elements
which it is valid to insert at this point. Choose
<idno> and notice that it inserts the element and
leaves you inside the opening tag in case you wanted to add
some attributes. Move down and cut and paste 'F101-19' in
between the starting <idno> tag and its closing
</idno> tag. Delete the stray colon that you did not
cut and paste.

Your <msIdentifier> should now look something
like:

<msIdentifier><country>Lithuania</country><settlement>Vilnius</settlement><institution>Lithuanian National M. Mazvydas Library</institution><repository>Rare Book and Manuscript Department</repository><idno>F101-19</idno></msIdentifier>

and your document should still be well-formed and valid. If
it isn't, correct it before continuing. When it is you can
choose the menu item 'Document -> XML Document -> Format and
Indent' to tidy up the indenting of the elements.

5. Creating an <msContents> element

Immediately after the closing </msIdentifier> tag,
type an angle bracket: '<' to get oXygen to present a
drop-down list of elements valid at this point. Select
<msContents>. Notice that the <p> below is
now underlined in red, because the ENRICH schema doesn't
allow a vague pararaph and structural divisions to co-exist
in this manner.

Move in between the opening and closing tags of the
<msContents> element and again type '<' to
see a list of possible elements. In this case choose
<summary>.

Go to the paragraph down below and copy and paste
everything from 'An original copy of a' all the way to 'Bug
(Bugk) river.' into the <summary> element you have
just created. This is a prose description of the intellectual
content of the manuscript.

Press enter between the closing </summary> tag and
the closing </msContents> tag and then add a new
<textLang> element by typing '<'. Notice how
oXygen (usually) automatically adds the required
mainLang attribute and places your cursor and
just the right place to type in the ISO language code 'lat'
for Latin. Type it in.

Move to just after the closing double-quote of the
mainLang attribute. Press space. oXygen should
provide a drop down menu of all other attributes valid on
this element. Scroll down and choose 'otherLangs', and since
the descriptive paragraph below tells us it contains Polish
as well as Latin, add the code 'pol' as the
otherLangs attribute value.

Cut and paste the text 'Latin. There are postscripts in
Polish.' into the middle of the <textLangs>
element.

After the <textLangs> element but before the
closing </msContents> tag, add in an <msItem>
element by typing it in. Inside the <msItem> element
create an <incipit> element in a similar manner. Cut
and paste the text 'In nomine Domini amen. Ne orror
obliuionis…' in between the <incipit> tags, including
the final ellipsis.

While the document still isn't valid, because of that
<p> down below, there should be no red lines inside
your <msContents> which should look something like:

<msContents><summary>An original copy of a charter where Alexander (Alexander), King of Poland and Grand Duke of Lithuania, transumes and confirms the privilege of January 26, 1380, by which Vytautas (Vitholdus), Grand Duke of Lithuania, gives permission to establish a monastery of the Augustinian Order in Brest (Bresth) and founds plots of land and Kostomoloty (Koszthomlothy) village near the Bug (Bugk) river.</summary><textLangmainLang="lat" otherLangs="pol">Latin. There are postscripts in Polish.</textLang><msItem><incipit>In nomine Domini amen. Ne orror obliuionis…</incipit></msItem></msContents>

6. 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 ('<'), separate the physical description
information into a <physDesc> element and its possible
children, something like below:

Pay particular attention to the required attributes on some of
the elements. These are not required in TEI generally, but here
we are using the ENRICH schema, which holds us to a higher
standard. Thus, if these elements are present, we must provide a
form attribute on <objectDesc>, a
material attribute on <supportDesc> and a
columns attribute on <layout>.

7. The importance of <history>

Most of the text of the paragraph 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:

Here we have also added a paragraph stating that this is an
original of the charter (rather than a contemporary copy).

8. Making this a real TEI file

What we need to do now is take the <msDesc> we've created
and build a TEI file around it. This will also help us to
understand how the description fits into the concept of a
complete digital edition.

9. Wrapping it in <TEI>

Highlight your entire <msDesc> element using
either the keyboard or the mouse, making sure not to
include the processing instructions or xml declaration at the
top.

Press (usually) ‘control-e’ to surround this with an
element. Looking at the drop-down menu in the dialog box you
should have an option for
‘TEI#http://www.tei-c.org/ns/1.0’. Select it!

Notice that not only the <TEI> element but its
namespace declaration has been added.

As you can see, although the file is well-formed, it is
invalid because it doesn't validate against the schema. To be
specific, in needs a <teiHeader> element, optionally a
<facsimile> element and/or a <text> element.

10. Adding the <teiHeader>

Inside the <TEI> element, but before the
<msDesc> element, add a <teiHeader>
element

The <teiHeader> requires a <fileDesc>, add
it

A <fileDesc> requires a <titleStmt>,
<publicationStmt>, and <sourceDesc>. Add the
<titleStmt> and inside that a <title>
element. Add in a title for this document, perhaps 'F101-19:
An electronic edition'. If you move outside the
<title> and type '<' you can see a list of
other elements allowed inside <titleStmt>, look at the
options but delete the '<' before moving on.

Outside the <titleStmt> add a
<publicationStmt> and also look at what elements are
allowed here. Inside the <publicationStmt> add a
<publisher> element with the content 'Lithuanian
National M. Mazvydas Library'. The are other elements one
could add here, or we could have just given this information
in a <p> instead.

After the <publicationStmt> element, add a
<sourceDesc> element to describe the source, inside
put a single, empty, <p/> element. This is just a
placeholder, we will replace it in a minute.

If everything has gone well, then you should have no red
lines inside your <teiHeader> (though overall the
document will still be invalid because we don't have a
<text> element). It should look something like:

Note that we haven't added any of the other (optional)
aspects of the teiHeader that are not required. You may wish to
explore these at some point.

11. Adding our <msDesc>

We now want to move our <msDesc> that we created earlier
to the <sourceDesc>

Delete the empty <p/> element inside the
<sourceDesc>

Highlight the <msDesc> you made and using the edit
menu, or keyboard shortcuts, cut and paste it into the
<sourceDesc> element

Your document should now have no red lines inside the
<teiHeader> section of your document (some further
down is fine for now).

12. Adding a <facsimile> element

We're not going to do much with the <facsimile> element,
but it is good to include since this allows a way to reference
graphics associated with the text. In our case we will just use
the <graphic> element. (We could also have added this to
our <msDesc> using a <surrogates> element inside
the <additional> section.)

Go to after the closing </teiHeader> tag and
insert a blank line.

Insert a <facsimile> element

Inside this, add an empty <graphic/>
element

As part of the <graphic/> element add a
url attribute with a value of 'f101-19a.jpg'.
This could take any URL pointing anywhere on the internet,
however in this case the graphic file is in the same place as
the other materials.

Your <facsimile> element should now look something
like:

<facsimile><graphicurl="materials/f101-19a.jpg"/></facsimile>

It is important to note that adding this
<facsimile> element does not 'do' anything with regard
to linking the text to the image or parts of the image. It is
simply providing the information in a standard place so that in
processing or rendering the document one can have access to it.

13. Adding the text

Your file should now be completely valid against the ENRICH
schema at this point. If it isn't, try to find what it thinks is
wrong and fix it before proceeding! Although you can make a valid
TEI file with only a <facsimile> element to form an
electronic facsimile and no <text> element, we do not tend
to view these are real digital editions. To get improve this
edition we must add a <text> element!

Move to just after the closing </facsimile> tag,
and hit enter to add a new line

Add a <text> element

Inside this add a <body> element

Move in between the starting and closing tags of the
<body> element and go to the menu item 'Document ->
File -> Insert File', and select the file 'F101-19_text.xml'.
This file contains the text of the charter already marked up
in XML. This markup has been provided by someone else, and we
might have encoded some things differently, see what you
think.

Your file should be valid!

14. Save your file!

Just a reminder to make sure you have saved your file before you
finish! Perhaps save it as ‘exercise2.xml’.

15. Other things to try ...

Looking at the image of the manuscript, what things have we
not included in this basic manuscript description?

What TEI elements might exist to record this
information?

What TEI phrase level elements might you use to mark up the
information further?

Explore the markup we've added by inserting the
'F101-19_text.xml' file. What is marked up, and what is
not?

Experiment with adding more markup to the file.

Try out the oXygen 'Author' mode on this text. It has a
customised CSS stylesheet which displays the manuscript
description for editing.