3. Getting Started - The Basics

There are a few steps that need to be taken before you can get documents up on the web site. These are outlined below:

Obtain a suitable XML editor
We recommend the cross-platform oXygen editor, for which we have a site licence; see the document on How to use oXygen at OUCS
Obtain a Subversion client
We recommend Syncro SVN, the client which comes with oXygen. Details are given in the document Using the Syncro Subversion client
Obtain a Subversion account
Accounts can be setup by visiting https://svn.oucs.ox.ac.uk/admin/useradmin/
Write your document!
This part is up to you! If you are unsure how to start, open an XML file and save under a different name. After removing the original content of the file, you can now use this file and add your own content as necessary.

Before submitting your file to Subversion, you should check your document's syntax. Most XML editors have facilities to check the validity of your document against your schema. Make any corrections necessary before submitting the file to the main Subversion repository. Also bear in mind that your document should be fully accessible and SENDA compliant.

3.1. A Few Definitions

Elements and Tags
XML documents have lots of elements, one example is the title element. This begins with a start-tag <title> and is closed by the end-tag </title>. Any text between the start and end tags is therefore defined as the title of the document. Most XML tags work in this way: a start tag, some text, followed by an end tag. There are some elements that are self closing (i.e. they have no end tag); where appropriate these will be highlighted later in this document.
Content and Data
Any text between tags is the content of the element. This can be of two forms: the actual information or data; and other elements. Where the two occur together this is termed mixed content.
Attributes

All elements can have additional properties beside the element name and content. These properties are the attributes of an element and they consist of name-value pairs. For example a <div> element can have the attribute id="xxx", where xxx represents a name or number. In the example below, the id is 'email':

<div id="email">  <head>Configuring your email client</head>  <p> text....</p> </div>
XML structure and nesting tags

XML is very strict on its element structure, especially compared to HTML. In XML, tags usually have to be started and ended. They must be nested properly and used in the correct place within the document hierarchy. This generally means that you cannot open a new tag e.g. <p> without closing the previous <p> tag. (N.B. there are exceptions to this rule e.g. self-closing tags).

3.2. Dissecting the OUCS XML Template

Viewing the OUCS template code in your editor shows the document structure. The complete page structure is shown below:

<TEI.2>  <teiHeader>   <fileDesc>    <titleStmt>     <title>Markup for OUCS documents</title>     <author>Sebastian Rahtz</author>    </titleStmt>    <editionStmt>     <edition>      <date>May 2009</date>     </edition>    </editionStmt>    <publicationStmt>     <authority>webmaster@it.ox.ac.uk</authority>    </publicationStmt>    <sourceDesc>     <p>This is the master version of an original document.</p>    </sourceDesc>   </fileDesc>   <revisionDesc>    <change>     <date>$LastChangedDate: 2014-04-23 10:28:49 +0100 (Wed, 23 Apr 2014) $</date>     <respStmt>      <name>$LastChangedBy: publish-button $</name>     </respStmt>     <item>$LastChangedRevision: 157843 $</item>    </change>   </revisionDesc>  </teiHeader>  <text>   <body> <!-- Your text goes in here.... -->   </body>  </text> </TEI.2>

First comes the declaration that the file is a TEI document <TEI.2>. This is effectively the start tag for the document, all other elements must be correctly arranged or nested inside the <TEI.2> tags for the document to be valid TEI XML.

The first element inside <TEI.2> is the <teiHeader> element. Everything within this element is part of the document's Metadata (Metadata is data about the document, e.g. its title, author, creation date etc.). OUCS documents have a number of fields in the <teiHeader>; some have to be manually completed, such as the title of the document, while others are automatically added on document submission e.g. Last changed by information. Usually, when writing your own documents, you should complete the following metadata elements:

  • title
  • author
  • date

It will also be necessary to complete an extra sections in the header recording who is responsible

  • authority

The end of the metadata is marked by the closing </teiHeader> tag.

After the metadata comes the body of the document. This can be split into three sections:

<front>
contains any prefatory matter (headers, title page, prefaces, dedications, etc.) found before the start of a text proper.
<body>
contains the whole body of a single unitary text, excluding any front or back matter.
<back>
contains any appendices, etc., following the main part of a text.

The majority of OUCS documents only use the body section for the text. This is shown in the next example:

<teiHeader>... </teiHeader> <text>  <body>   <p>Your text goes in here....</p>  </body> </text>

If you do want to include front and/or back additions to your document, the sections are coded in the following manner:

<text>  <front>   <titlePage>    <docTitle>     <titlePart type="main">Markup for OUCS documents</titlePart>    </docTitle>    <docAuthor>Ian Senior</docAuthor>    <docDate>May 2005</docDate>   </titlePage>  </front>  <body>   <p>Your text goes in here....</p>  </body>  <back>   <div id="appendix">    <head>Appendix</head>    <p>More text in here...</p>   </div>  </back> </text>

Up: Contents Previous: 2. How does the OUCS system work? Next: 4. Coding your document