Get the Most out of Oxygen Martin Holmes Author Cameron Butt Author Tye Landels Author Sarah Milligan Copy Editor Cameron Butt Encoder Tye Landels Encoder Data Manager Tye Landels Junior Programmer Joey Takeda Programmer Martin Holmes Associate Project Director Kim McLean-Fiander Project Director Janelle Jenstad The Map of Early Modern Londonhttp://mapoflondon.uvic.ca/includes.xmlVictoria, BC, Canada
Department of English P.O.Box 3070 STNC CSC University of Victoria Victoria, BC Canada V8W 3W1
2016University of Victoria978-1-55058-519-3 Janelle Jenstad london@uvic.ca

Copyright held by The Map of Early Modern London on behalf of the contributors.

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Further details of licences are available from our Licences page. For more information, contact the project director, Janelle Jenstad, for specific information on the availability and licensing of content found in files on this site.

Born digital.

Most MoEML documents, or significant fragments with xml:id attributes, can be addressed using the mol: prefix and accessed through the web application with their id + .xml.

The molagas prefix points to the shape representation of a location on MoEML’s OpenLayers3-based rendering of the Agas Map.

Links to page-images in the Chadwyck-Healey Early English Books Online (EEBO) repository. Note that this is a subscription service, and may not be accessible to those accessing it from locations outside member institutions.

Links to page-images in the English Broadside Ballad Archive (EBBA).

The mdt (MoEML Document Type) prefix used on catRef/target points to a central taxonomy in the includes file.

The mdtlist (MoEML Document Type listing) prefix used in linking attributes points to a listings page constructed from a category in the central MDT taxonomy in the includes file. There are two variants, one with the plain xml:id of the category, meaning all documents in the specified category, and one with the suffix _subcategories, meaning all subcategories of the category.

The molgls (MoEML gloss) prefix used on term/corresp points to a a glossary entry in the GLOSS1.xml file.

This molvariant prefix is used on ref/target attributes during automated generation of gazetteer index files. It points to an element in the generated variant spellings listing file which lists all documents which contain a particular spelling variant for a location.

This molajax prefix is used on ref/target attributes during the static build process, to specify links which point to MoEML resources which should not be loaded into the source page during standalone processing; instead, these should be turned into links to the XML source documents, and at HTML page load time, these should be turned into AJAX calls. This is to handle the scenario in which a page such as an A-Z index of the whole site would end up containing virtually the whole site inside itself.

The molstow prefix is used on facs attributes to link to the HCMC verison of the Stow facsimiles. Usually the first group is the year (1633) and then last is the image number (0001).

The molshows prefix is used on facs attributes to link to the copies of page-images from mayoral shows stored in the london account on the HCMC server. The first group is the year (1633), the second is the source repository, and then last is the image file name.

The sb prefix is used on ref/target attributes to link to Stow’s Books URLs at UToronto.

Our editorial and encoding practices are documented in detail in the Praxis section of our website.

 Added table of shortcut keys. Added sourceDesc information for born-digital documents. Standardized respStmts for JENS1, MCFI1, and HOLM3 and added TAKE1 as Junior Programmer. Added XInclude for listPrefixDef in the header. Revised index tags. Added section on wrapping code in Oxygen. Added global publicationStmt through XInclude. Put change elements inside revisionDesc into the correct (latest first) order. Added profileDesc containing document type information expressed in catRef elements. Created file and added content from encoding_practices.xml file. Get the Most Out of Oxygen
Introduction setup your workstation Oxygen basics

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.

setup your workstation Oxygen MoEML project file 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).

setup your workstation Oxygen code templates special characters unicode 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.

setup your workstation Oxygen schematron relax ng unicode validation 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.
setup your workstation Oxygen validation XInclude XML parser 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.
setup your workstation Oxygen find and replace 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.

setup your workstation Oxygen line wrap preferences in Oxygen 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.)

Oxygen shortcuts Oxygen code templates special characters keyboard shortcuts copy and paste Keyboard Shortcuts

There are a number of keyboard shortcuts in the MoEML Oxygen project file that quickly perform a number of common encoding tasks.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

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