Tutorial: Oxygen XML Editor

If you are working on a CDRH project which uses XML files, you will need to install the Oxygen XML software. Oxygen will help you write XML more quickly, and can tell you if something in the file needs more attention.

Oxygen Editor logo surrounded by network of technologies such as databases, XSLT, and schema editing

The Oxygen XML Editor is a very powerful tool, but you will only
be using the XML portion of its abilities!

Get Oxygen

1. Locate Oxygen

If you are using a CDRH computer, Oxygen may already be installed. Search the application folder for Oxygen to check. If you are working on a non-CDRH computer or cannot find the software, you'll need to download a version of it.  Head to https://www.oxygenxml.com/xml_editor/software_archive_editor.html . The current version is Oxygen XML Editor Version 22.0 but check with center staff to make sure you are getting the correct version. Now that you have Oxygen installed, start it up! (This will take a while, so please be patient.)

2. Activate with a key

To complete this step, you will need to contact a member of the CDRH staff. We will send you a key to activate your copy of Oxygen. Once you have the key, open up the Oxygen XML Editor application. This should pop up automatically upon starting Oxygen, if not go to the "Help" menu and select "Register..."  You will get this dialog:

license activation dialog

3. When Oxygen opens, it may ask you if you want to get daily tips. Just say no. It also will open with a number of optional sidebars open. You should close all of these sidebars by clicking on the red dot in the upper left corner, leaving only the main window open. When editing text, you usually want the main window to be as big as possible. You can later turn back on any sidebars that you think you might want, by clicking on Window / Show View.

Set Your Preferences

In order to make sure that we are all creating similar XML files, we need to make sure that Oxygen is set up with the same preferences for everyone. Follow along below to change your settings:

Editor Settings

Under Options / Preferences, click the down arrow on Editor and then Edit modes. You will want to click on Text and turn on the Line wrap, by clicking the box to the left. If you do not do this, when you have paragraphs of text, instead of wrapping and fitting in your window the text will not wrap and you will have to scroll to the right to view your text, and nobody wants to do that.

Oxygen editor text settings

Here is an example of what the text will look like if you don't have Line wrap on. I think you will agree that no one wants that:

Oxygen schema interaction displaying element information

Next, turn off all of the pesky indents. "But I like indents," you say. I will show you how to look at indented files later, but for now, just turn them off. Do so by clicking the down arrow next to Editor and then on Format. Make sure all of the check boxes are unchecked here.

Oxygen format settings

But wait, there are more. Under Editor / Format / XML, at the bottom of the page uncheck the boxes next to Indent (when typing) in preserve space elements and the box by Indent on paste.

Oxygen format XML settings

Next, let's look at Spell Check in the Editor / Spell Check menu. Do you want the spell check on or off? If you are working with modern, printed source materials, go ahead and turn it on. Do this by checking the box next to Automatic spell check. If however you are working with older hand-written materials (think Lewis and Clark Journals!), you will probably want it off. Do this by unchecking the box next to Automatic spell check, as seen in the image below. Somewhere in the middle -- say modern hand-written text -- it's your choice whether to have the spell check on or off.

Oxygen editor spellcheck settings

Going hand in hand with the spell check is the AutoCorrect, which can be found in the Editor / Edit modes / Author / AutoCorrect menu. Turn the AutoCorrect off by unchecking the box next to Enable AutoCorrect.

Oxygen editor autocomplete settings

One of the nice features of Oxygen is that it wants to help you with encoding -- so let it. Under Editor / Content Completion, check the three boxes at the top --  Auto close the last opened tag, Automatically rename / delete / comment matching tags and Enable content completion.

Also check the boxes by Close the inserted element, If it has no matching end tag and Add element content. But please don't click on Add optional content. Instead you want it to Insert the required elements, as shown below. Also turn on Case senstive search and Show all entities.

It is your choice whether or not to turn on Cursor position between tags, but most people do like it, so I would suggest turning it on. You can always turn it off later if you find you don't like it.

Oxygen content completion settings

Next, let's look at the Editor menu itself. There is just one thing that you should check here and that is Undo history size. It should already be set at 200, but if it is not, please set it to a large number like 200, unless you never make mistakes! You can also do some messing around with colors here, if you do not like the defaults. This is totally up to you. Other color selections can be found under the Appearance menu.

Oxygen editor preferences

The other thing that is totally up to you is the font. If you are going to be looking at your XML documents for long periods of time, you probably want to set your font to something you find pleasing to the eye. So, play around with this and see what looks good to you. Here you can see that I have mine cranked up to size 15 because I'm old and look at XML files all day:

Oxygen font preferences

Lastly, there are a number of keyboard shortcuts that will be useful to you. The one that you will use all the time is command e. Command e will bring up a list of all tags that can be used. This is super handy, as you do not want to have to memorize every tag that can be used in your document. Also, if you highlight a section of text and hit command e, it will put your tag around the chosen text for you. Of course, command s, command c, and others work like they do in most other programs, but oxygen has many more. For the complete list, go to Editor / Menu Shortcut Keys. Please note that these may differ slightly between Mac and PC.

Oxygen editor shortcut settings

Now you are done setting up your preferences. Remember to click Apply and OK when you are done. So, let's look at some features of Oxygen.

Tour of Features

Using the Author tab

Located at the bottom of the main Window, you will see three buttons. The one that is highlighted by default is Text. This is the one you should use for all of your encoding. However, if you are just proofreading something and are not interested in seeing the encoding, the Author tab will allow you to look at only the text, as seen in the image below:

Oxygen Author view

This is how that same page looks in the Text tab:

Oxygen code highlighting

Tools / Compare files

If you would like to compare difference in two files, you can do so using Tools / Compare files. First, open two files. Then, go to Tools / Compare files and select the files to compare. Here is an example comparing two texts of Mansfield Park. You can see at the bottom, that there are 8 differences in the files, and I can use the red error indicator at the right to jump to those lines with differences.

Oxygen diff functionality

Window / Tile editors vertically

Sometimes you will want to have two windows open at the same time. This is handy for when you want to copy information from one window to the other or when you want to use one file as an example of how the second document should be encoded. To do this, open two documents and then go to Window / Tile editors vertically. You can also choose tile editors horizonally if you like that better. Remember to only have two files open when you select Window / Tile editors, otherwise you will get as many tiles as you have files open. You can open additional files in that tile later. Of course if you want a bunch of tiles open, then go ahead and have them all open before clicking on Window / Tile editors.

Oxygen display

Window / Show View / Outline

Remember back when you said "but I like indents"? Oxygen has other ways to show you encoding structure. The one I would recommend is Window / Show View / Outline. You can fold and unfold the outline using the arrows and you can even move whole sections of your document around using this sidebar. You may also indent the entire document when you are done by using command shift p or clicking on Format and Indent button in the row located above the file tabs. Please remember to undo this before saving unless instructed otherwise.

Oxygen outline view

Oxygen has tons of other features. If there is something that you want to do, just ask. It may be possible. But this should be enough for you to get started. Happy encoding using Oxygen XML editor.