Set up and materials for tutuorials

This page guides you through the processes for setting up the oXygen XML Editor and downloading the exercise files used in the tutorials; it also provides shortcuts and troubleshooting tips for using oXygen XML Editor.

Getting started with oXygen

Before you begin the tutorials, you should download oXygen XML editor. You will also need a trial license, which can be found here.

Tutorial zip files

Please also download our zip file of resources, templates, and other materials. These will be referenced throughout the tutorials. You can edit the files as practice at any time, but please make sure that you do not move any of the files within the folder. XML depends upon links between different files and folders, so moving anything outside of the folder or to another location within the folder will cause problems. If you want to move the files to your desktop or some other location, move the whole folder.

Using oXygen

Here are some tips and tricks for using oXygen (note: keyboard shortcuts are for oXygen running on Mac OS; for other operating systems, you can view keyboard shortcuts under Options > Menu Shortcut Keys):

  • If your schema is properly associated, you should get a drop-down list of elements when you put a less-than sign into your documents. You should also get a drop-down list of attributes when you put a space after an element name. This auto-completion prevents validity errors resulting from typos and saves you time. If you don’t get the drop-down list or the list disappears, you can hit control+space (on a Mac) to get the list back up again.
  • ⌘+E encloses selected content in a tag. If you wanted to put a person’s name in <persName> but forgot to do so, you can just select the person’s name, hit ⌘+E and type <persName> into the box that appears. If the schema is properly associated, this feature should also have a drop-down box of possible elements.
  • ⌘+L takes you to a specific line number in a document.
  • ⌘+⇧+, (command+shift+comma) will surround selected content in a comment (<!-- YOUR COMMENT HERE --> is the syntax for comments). If you select commented content, this shortcut will also un-comment this material.
  • oXygen will auto complete end-tags when you type a start tag. If you want to make an empty element, simply put a forward-slash after the element name in the start-tag. This will auto-delete the end-tag.

Character and entity references

There are certain characters that are very important to XML, and therefore you cannot simply type them as content in your documents. You must instead use entity references. These allow you to state that a certain character is being transcribed, without actually typing that character. So, for example, you can’t type the “<” character as content in your documents, because the parser will assume that you are starting a new tag. It will then get confused when the rest of the XML element is not present, which will cause an error.

Here are the replacements for common characters and entities in XML:

  • For “<” use "&lt;"
  • For “>” use "&gt;"
  • For “&” use "&amp;"
  • If you need to use an apostrophe or quote mark in an attribute value, use "&apos;" and "&quot;"

Error message demystification

oXygen’s error messages are more decipherable than the error messages of other XML editing applications. However, this does not mean that they are necessarily easy to decipher. This is a guide to understanding what oXygen is trying to tell you:

Well Formedness:

  • The value of attribute “att” associated with an element type “element” must not contain the character “<”: You may have deleted a quote mark surrounding your attribute value.
  • The element “element” must be terminated by the matching end-tag </element>: You are either missing the end-tag, or possibly missing a character (such as a pointy bracket or slash) in the end-tag.

Validity:

  • element “element” not allowed anywhere: The element that is causing the error is not in your schema. Check to see that you haven’t misspelled the element name.
  • element “element” not allowed here: The element listed is not allowed in that specific place. So, for example, if you put a <head> at the end of a chapter or a <p> inside of <persName>, this error message will result.
  • text not allowed here; expected element [list of element names]: You have text that should be surrounded by an element. It is likely that you are missing some mid-level element, like <p>, <l>, or <item>.

Please be aware that oXygen will sometimes reference an element that is not a part of the problem in an error message. This is often because there is no better way to describe the problem. So, for example, if you put a stray </orgName> end-tag within <p>, the error message will read “The element <p> must be terminated by end-tag </p>.” This is in part because it is reading an end tag, and assuming that it must belong to <p>. It will recognize that the <p> is not ending correctly, but will not pick up on the fact that the real problem is that <orgName> isn’t properly started (i.e. doesn’t have an opening tag).

Troubleshooting

If you are getting the error message “IllegalStateException - cannot validate without schema,” you have probably renamed or moved files and folders containing your schema or documents. If you have this problem, please undo any file moving or renaming, and the problem should be fixed. Remember: do not move individual files outside of or within the exercise folder.

If you don’t get the above error message, but are not getting pop-downs or validation errors when editing your documents, make sure that you have these lines (or lines resembling these) at the top of your document:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>

Support

If you are having issues that aren’t addressed here, oXygen has a wonderful community of users on their support forum site. Before posting a new question thread, try searching for the specific error you are getting or issue you are experiencing. Often, you are not alone and the question has been answered in the past.