This document will show you how to configure and use the oXygen XML editor to write and edit OUCS documents.
1. Obtaining the Software
You will need a copy of the oXygen XML editor installed on your computer. This document assumes you have Version 10 (or a later version).
Once installed, you will need to obtain a copy of the licence from the OUCS registration system (https://register.it.ox.ac.uk/self/software/). This needs to be pasted into the oXygen registration screen before you can use the program.
1.1. Starting oXygen
Once oXygen has been installed and the registration key accepted the program will open. You will see the following screen:
Figure oximages/oxygen-interface.png [oXygen interface]
The next stage is to download and apply the OUCS TEI setup into oXygen.
2. Obtaining and Installing the OUCS Templates
C:\Program Files\Oxygen XML Editor 10\, on Macintosh it will be in the Applications (or maybe your home) directory. In there is a directory
frameworks. Unpack the zip file there (replacing some files existing
You are now setup to access OUCS templates and can work in either WYSIWYG
Author) or code (
Text) mode depending on your own
3. Making a working copy of some or all of the OUCS web site
Before you begin editing or making new OUCS documents you need to make a local copy of the part, or parts, of the OUCS web site that you are interested in. This is covered in the Syncro Client Guide and will not be covered here. Once you have a local working copy of the OUCS site you can begin to write or edit OUCS documents.
Please note: Saving files back to the central repository is also covered in the Syncro Client Guide and not repeated here.
4. Using oXygen
Once you have applied the OUCS Template files described in the previous section, you can
open oXygen. To make the most of oXygen and its abilities to integrate with the OUCS
Subversion system, you will now need to configure the built-in Subversion client called
Syncro Client. Which is found under the
Client] menu option. Full details on how to configure this to access both local
and server repositories are given in the Syncro Client
Guide. The rest of this document will assume that you have read and configured
your system to use the Syncro Client.
4.1. Making a new document
To start a brand new document go to the top menu and select
New dialogue menu opens with two tabs:
Figure oximages/templates.png [New file dialogue box opens on New tab]
From Templates tab and scroll down the list until you find a
TEI P4 - OUCS. Click on this name to open the
template in the main oXygen work window. This document contains all the basic page
structures needed for an OUCS XML web page. By default this file will open in Text
If you want to use the
Author (WYSIWYG) view you need to switch the file
to it. Near to the bottom of the working window, there are three words,
Author. One of these will
be highlighted in a box. This box indicates which view you are currently using on the
Text is boxed you will see the code view of the file.
Figure oximages/textbutton.png [Position of text button]
If you wish to change to view you need to select the
Figure oximages/authorbutton.png [Position of the Author button]
Author button will result in a new window appearing
telling you about white space. Just click on the
OK button to continue.
The Author view of your new file will now appear. Part of this is shown in the screen
shot below. You can now start to add your new content.
N.B. In the rest of this document when
Author is used it refers to the
WYSIWYG view of the file.
Figure oximages/author-start.png [Author view of opened template]
Author view you will see that the oXygen syntax checker will
date field above
is empty and this is causing the error you see in the following two fields. Add a date
into the <date> field to correct this problem. You should also give your document
a title and also an author. Fill in both the <title> and <author> elements
with the appropriate information.
This same error is also noted in the
Text view. However in this view it
is the <fileDesc> field that appears to be wrong. Again filling in a date will
remove this error.
Figure oximages/author-start2.png [Shows examples of completed meta data]
Once the metadata (title, date, author) is complete, you can move on to writing the actual content your readers will see.
Anything written inside the <text> element will appear on your web page (providing you have correctly structured your XML of course!). If you are new to writing for our web site, you should read the Simple guide to XML. Those more experienced in web coding will find that the Guide to XML covers TEI XML in more detail. Whether you are experienced or not, you must make sure that any content you supply follows our Accessibility Rules. e.g. images must have 'alt' (alternative text) for instance. See the Guide to XML for lots of accessibility advice.
4.1.1. The Edit Toolbar
Author mode oXygen provides an
similar to those seen in word processing packages:
Figure oximages/edit-toolbar.png [Edit toolbar similar to those of word processors]
Edit toolbar allows you to add in familar word processing
features like images, lists, tables etc. To use a feature all you need to generally do
is click the appropriate toolbar button. If you are in an appropriate place for that
feature it will be inserted into your document. If the context is not correct, oXygen
will display an error message.
To add bold, links etc. to text you should select the appropriate text and
click on the
Italic) button to apply the
presentational effect. Links are added by clicking the
a button. You
will see the element appear in your text as two triangles with the cursor inbetween
them. Type in your link text making sure that it is meaningful when viewed outside of
the context of the sentence i.e. 'Click Here', 'More', and other meaningless link
phrases must NOT be used. The URL for the link is added to the curly brackets
that are present in front of the first triangle. However, you cannot enter this
directly into the curly brackets but you must use the
(see next section).
Adding an image is slightly more involved but very similar to adding one to
a normal word processing document. Clicking the
hills and sun button
will open up a browse screen where you can navigate to where the image is located.
Select the image and click
Open. The image will now appear in your
document. N.B. to appear on our web site, you need to add the image to your local
repository and submit it to the main Subversion repository.
Insert Tabledialogue box appears:
Figure oximages/table.png 
Generate Table Headercheckbox is ticked
OKto create the table
It is also possible to add and remove columns or rows as well as merge and split them using the other table buttons present on the toolbar.
Adding paragraphs can also be done through the
paragraph button. It should also be noted though that you
can add paragraphs, new list items, and other elements by hitting the
<Return> key. This causes oXygen to open up a
box from which you can either add e.g. a new paragraph or choose a different element
from the list to add to that point in your file. The dialogue box is shown below:
Figure oximages/splitting.png [The splitting dialogue box]
4.1.2. Elements and Attributes Panels
When writing your document, oXygen tries to help you by displaying what elements you
can use at a particular point in your content. On the righthand side of the oXygen
interface you will see two boxes, one called
Attributes and another
Elementsbox. Please also remember to use the scroll bar on the longer lists, your required element maybe hiding! If you move your mouse over each element in the list a popup will appear giving you a little bit of information about each element:
Figure oximages/rollover1.png 
For a fuller description of elements and examples of their use, please see the Guide to XML document.
Attributes box is also useful but used far less frequently.
Attributes are most useful when you need to add an
rend (class) to one of the XML elements. Both the
n attributes use the names provided by the author.
rend however is more specialised and used to add CSS classes to
elements in the final web page. A list of rends and what they do, can be found in the
Guide to XML.
When you need one of the elements to be applied to your text:
Elementsbox to find the element you need. (N.B. if it is not displayed you cannot apply that element at that position in your document.)
Authorview your text will have two small triangles surrounding it indicating it has been applied. It may also show extra formatting e.g. coloured, bold etc., depending on the type of element applied:
Figure oximages/triangles.png [Shows triangles surrounding text in Author mode]
Textview you will see the actual element applied around your selected text. All elements are coloured blue:
Figure oximages/text-view.png [Text view of the document]
Applying an attribute to an element is slightly different:
Attributesbox will list all that can be added to the element
Valuearea of the id attribute found inside the attributes box. The Attribute and its
Valuefield will turn blue
Valuefield becomes white again
Attributesbox will list all that can be added to the element
idto the element, click in the
Valuearea of the
idattribute found inside the
Attributesbox. The attribute and its
Valuefield will turn blue
Valuefield becomes white again
Figure oximages/attribute2.png 
Authorview. You need to look at the
Attributesbox to see that one has been added to a particular element.
Sometimes you cannot easily get to an element e.g. the list element does not show up
on the page while the individual list items do. In such circumstances you can either
Text view and edit it there or, in
Attributesbox as previously described.
4.2. File Validation
oXygen has the ability to check your code as you type. This is a very useful feature of the program as it means errors are highlighted as you work e.g.
Figure oximages/errorhighlight.png [Errors highlighted in both modes]
oXygen/ also indicates errors throughout the document via the vertical strip at the side of the main content window. When you have errors you will see both a red square at the top and red bars down the strip. Clicking on one of the error bars takes you to where oXygen/ thinks the error is located.
Figure oximages/error.png [Error indicators shown in vertical column]
When the file content is all valid XML, the red box will turn green and there will not be any red bars in the column..
Figure oximages/validfile.png [Valid file indicated by green box in vertical column]
4.3. Viewing your work
It is always useful to see what your page looks like as you work. There are two options available to you:
The first option is covered in the Syncro Client documentation and will not be repeated here.
The second option where you can view your work locally will give you a good idea of how your page will appear on the real web site - but not entirely. The major difference is that your major divisions will not be show as separate pages. You will see your work as one long page, broken down into sections.
Author modes the method to transform
your work into a web page is the same.
Figure oximages/scenariosbuttons.png The first button is the
Start Transformationbutton. This will either provide a list of possible scenarios if this is the first time you have used it or it will use the last transformation configuration you used. The second
Spannerbutton will allow you to pick from a list of possible transformation scenarios. The third button is the
Debug Scenariobutton but this is outside the scope of this document.
Spannerbutton. This will open the
Configure Transformation Scenariodialogue box. Here you will see several different scenarios that you could apply to your XML file.
Figure oximages/scenarios.png 
The default OUCS style is called
OUCS Normal. Selecting this option will
transform your XML and the output will look very similar to the normal OUCS web page
style with the exception that it will appear as one complete page and not
split into different pages as will be the case on the real site. Choosing the
OUCS LTG transformation will make your page look like a page from the
LTG sub site. Similarly if you go for the
OUCS one column transformation,
the resultant page will just show your content in a single column with no side column
navigation area present.
To transform your XML file into the standard OUCS style:
[OUCS Normal]from the list and click on the
Please Note: If the document has XML errors in it the transformation will fail. Please make sure you have a valid document before proceeding.
Below are three different views of the same document produced with the OUCS Normal, LTG and One column transformations:
Figure oximages/normal-transform.png [View showing result of OUCS Normal transformation]
Figure oximages/ltg-transform.png [View showing result of LTG transformation]
Figure oximages/single-col-transform.png [View showing result of single column transformation]
If you need other transformation scenarios please contact the Information Services Team.
4.4. Publishing to the Internet
Unless you have special access you can only publish files through the Preview web site.
Publishing a file
p-file(means publish file). Click this button to publish the file
Publishing a directory of files
p-dirbutton (means publish directory) a new page opens listing all the unpublished files in that directory
Make the above changes to the websitebutton
4.5. Available Templates
oXygen now has built-in OUCS templates for your use. These are:
The Information Services Team are happy to make more templates for you. Please contact the Information Services Team if you need a specific template constructing.