Get the Most Out of oXygen

roseList documents mentioning Get the Most out of oXygen

Introduction

This page contains useful information for advanced encoders using oXygen. These instructions are not comprehensive, but outline a few key features. For an introduction to oXygen, see this document prepared by MoEML programmer Martin Holmes.

Using the MoEML project file

If you check out the MoEML codebase from Subversion as described in Access Files from the Subversion Repository, you will find that there is a file in the root of the checked-out folder (alongside PERS1.xml) called moeml.xpr. This file is an oXygen project file. Load this file into oXygen Project / Open Project..., and you should see the list of all the files and folders in the project available to you automatically.
Using the moeml.xpr project file brings some other advantages. For instance, you will find that the keystroke shortcut for entering a curly apostrophe described below is automatically configured, and you can also run the diagnostics.xsl file in utilities to perform consistency checks on the entire collection (although this is now done automatically by our Jenkins build server whenever anyone commits to svn).

Add Code Templates for Special Characters (Apostrophes, etc.)

oXygen can remember code templates, or shortcut keys for special characters. This can be useful for typing characters that re-occur frequently but are difficult to type. For example, the website uses curly apostrophes (’), Unicode character U+2019, which must be hard-coded (manually typed in the string of text, rather than rendered dynamically). Documents with straight apostrophes will not validate against our schema. Other useful characters to have in a code template may be the en dash (–) or the em dash (—). Typing such characters is made easier by setting up a code template in oXygen as follows.
First, find the character in your character map (or in a pre-existing document) and copy it to the clipboard so you can paste it when you need it. The curly apostrophe, en dash, and em dash can be copy-pasted from the text above, for example.
In oXygen, click on Options/Preferences, then type Code Templates into the filter box at the top. You will see a list of the existing code templates (if any). Click on New, then fill in the following details:
  • Name: Apostrophe
  • Description: Curly apostrophe (U+2019)
  • Associate with: XML Editor
  • Content: [Paste the apostrophe in here]
Then press OK.
Now, you can insert a curly apostrophe into documents as follows:
Press Control + Shift + Space. You should see the code template selector appear. Use the arrow keys to select the desired code, and press OK to use it.

Set Up Schematron Validation

All of our TEI files must of course validate against our TEI schema, which is a RELAX NG schema. This controls the structure and content of our files, by setting out the rules for which elements and attributes can appear in which places, and making sure that (for example) dates are encoded in the proper format. However, the RELAX NG schema has some limitations on the kinds of constraints it can impose. In order to apply some extra, more project-specific rules and strictures to our files, we also use a second schema which is written in a different language called Schematron. So at the top of every XML file, you’ll see two processing instructions pointing at schemas, one pointing at the RELAX NG schema (london_all.rng) and one pointing at the Schematron schema (london_all.sch). The RELAX NG schema is handled automatically by Oxygen, but in order to make the Schematron schema work properly, you will need to make a couple of changes to the oXygen preferences. If this is not done, validation of XML files will fail.
  • Click on Options/Preferences.
  • In the filter box at the top left, type XML Parser and press return. XML Parser [P] should be selected.
  • Under Schematron/Schematron XPath Version, select 2.0.
  • Under ISO Schematron, check Allow foreign elements.

Adjust Validation Settings for Files with XInclude

Almost all of our XML files contain XInclude elements. XInclude is used to pull in content from another document; it enables us to keep a single copy of some important pieces of XML in one location and pull it into many other documents automatically. You can see some examples and a brief explanation of XInclude in Website structure: Simple Documents. By default, when Oxygen validates a file containing an XInclude element, it tries to follow the XInclude tag and pull in the extra content before doing the validation. This would be desirable, except that Oxygen is not able to follow some of the XInclude paths we use, because they include XPointers. Therefore we have to turn off this behaviour for the validation to succeed:
  • Click on Options/Preferences.
  • In the filter box at the top left, type XML Parser and press return. XML Parser [P] should be selected.
  • Under XInclude Options, uncheck Enable XInclude processing.

Find and Replace Encoded Text

oXygen has a powerful search and replace function, but it should be used with caution to avoid errors.
To search in a certain file, right-click on that file in the project view and select Find/Replace in Files. To search and replace in all files, select the highest file in the tree, london. This action opens a search and replace window. To search for a string of text, simply type that string into the search bar and click Search. Oxygen will open a list of the occurrences it finds at the bottom of the screen. It also lists the number of occurences and the files in which they appear. Double-click on an occurrence to open that file.

Wrap XML Code

Use the Line wrap function in oXygen to wrap your XML code neatly, so that it does not disappear off the right of your screen with a horizontal scrollbar. To activate the Line wrap function, click on Preferences... in the Options toolbar. A new window will open with a table of contents on the left-hand side. Find the Text subsection, nested inside Editor > Edit modes > Text, and check the Line wrap checkbox.
It is absolutely essential that encoders do not use pretty-print, also known as the Format and Indent function in oXygen. Although this function promises to wrap your TEI code neatly and indent it for you, in practice, it will add extra spaces in the middle of mixed-content elements, resulting in the introduction of spaces where they should not appear. (See related documentation on encoding spaces truthfully.)

Keyboard Shortcuts

There are a number of keyboard shortcuts in the MoEML oXygen project file that quickly perform a number of common encoding tasks.1
Action▼ How to do it▼
Add element around selected text Ctrl+e
Save Ctrl+s
Validate Ctrl+shift+v
Comment/uncomment selected text Ctrl+shift+,
Pulls up a menu of special characters and common entity tags that MoEML uses (including curly apostrophe, long s, personography entry, and more) Ctrl+shift+space
Undo Ctrl+z
Redo Ctrl+shift+z
Cut Ctrl+x
Copy Ctrl+c
Ctrl+v Paste
Find/Replace (use with caution!) Ctrl+f
Toggle line-wrap Ctrl+shift+y
See suggested elements Left bracket (<) and wait for one second
See suggested attributes When in the element, press space after typing the element name and wait for one second
See suggested attribute values Place cursor between the quotation marks and wait for one second

Notes

  1. These shortcuts are for a Linux OS; depending on your operating system and keyboard, the commands might be slightly different. For a full list of oXygen keyboard shortcuts, see oXygen > Options > Menu Shortcut Keys↑