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.
- 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.
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
idis '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).
Viewing the OUCS template code in your editor shows the document structure. The complete page structure is shown below:
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
Last changed by information. Usually, when writing your own documents,
you should complete the following metadata elements:
It will also be necessary to complete an extra sections in the header recording who is responsible
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:
- contains any prefatory matter (headers, title page, prefaces, dedications, etc.) found before the start of a text proper.
- contains the whole body of a single unitary text, excluding any front or back matter.
- 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:
If you do want to include front and/or back additions to your document, the sections are coded in the following manner: