Oxygen
<oXygen/>
1. Opening a Document
To open a single document,
- Click the Open button on the top bar.
- Click File, then Open.
The first time you open <oXygen/>, you will see a blank screen with frames on either side. On the left side is the project manager, with a list of folders and sample documents.
A project is a group of files that <oXygen/> saves together, like multiple files that are part of one website, making it easier to manage the collection at once.
To open a project that already exists, click the Open Project button above the project manager.
To open a file within a project, click the + next to the folders to find the file you want, then double-click the file.
To create a new project, click the New Project button.
To add new files to a project, open the file and click the Add Edited File button.
2. Creating a New Document
To create a new blank document: Go to "File", then click New...
This will bring up a list of many document types. Choosing a certain type of document tells <oXygen/> to supply the correct code in the header to define the document as the correct type. Choosing the correct type means that <oXygen/> will be able to correctly use its help features to guide you in writing the document. You will notice that in addition to XML-related documents, <oXygen> can also create HTML, standard text documents, and various other files like Javascript. You can use some of <oXygen/>'s features even in plain text to help speed up the writing process.
In the new file dialog, click on the "From templates" tab to see a list of XML templates that <oXygen/> already knows about.
Choosing one of these options creates a file already associated with an existing DTD such as DITA or DocBook, so you don't have to write your own DTD.
Back on the "New" tab, choose XML document and click OK. This will bring up another window, asking you to choose a schema or DTD for your document. Clicking the drop-down list gives you a list of several common DTDs online that you can use, or if you have a file on your computer that you want to use, click Browse for local file next to the drop-down list.
If you know the URL of the file online that you want to use, click Browse for remote file next to the drop-down list. This will ask you to enter a direct URL, as well as username and password if needed, or you can enter a server URL to search on a server for files to use. Once you have found a file, click OK.
Back in the first window, <oXygen/> should load the information from the DTD or schema. Choose the root element (the highest level element) from the Root Element drop-down list. Click OK. From the DTD or schema, <oXygen/> will have the information it needs to tell you what elements are allowed while you're writing, so you end up with a valid XML file.
3. The Working Environment
3.1. Outline Window
Start by opening a sample document in <oXygen/> XML Editor. At the bottom of the project manager under "Outline," you should see documents that begin with "Personal."
Double click on personal.xml to open it. Below the project manager you see the Outline window.
This shows you the hierarchy of the elements in your document. In the main window, click somewhere inside the <name> tag. You will see that in the outline window the hierarchy expands to show where the element you clicked on is. Alternatively, you can click the name of an element in the outline and <oXygen/> will highlight the element in the main window. The gray words next to the element name in this window show you what the content and attributes of the element are.
The buttons at the top of the outline window, from left to right, have the following functions:
Personnel
- Show/hide attributes in the outline.
- Configure (change the order of), and add or remove attributes.
- Show/hide text (content) in the outline.
- Change the display mode for the outline.
- no selection update means the outline never expands on its own.
- selection update on document change means the outline updates and expands automatically only when you click in the main window or edit the document.
- selection update on caret move means the outline will update and expand every time you move the cursor (a.k.a. caret) in the main window, even with the arrow keys.
Model
At the bottom of this window are tabs. The "Model" tab shows you the content model for the element you have selected, including child elements and attributes and their restrictions. The "Stylesheet" tab will list stylesheet elements similar to the attribute tab.
Elements
Below the attributes window is the Elements window. This lists the possible child elements for the selected element. In the main window, click on the <name> tag. The elements window will update to show you two child elements, family and given. These are the only two elements defined as children for <name>. Double-clicking on the name of an element in this window will insert start and end tags for that element where the cursor is in the document.
Below the elements window you see more tabs.
- The "entities" tab lists all of the entities defined for this document. In this example only the standard XML entities allowing you to add reserved characters like & and ' are defined. The "XSLT..." tab shows information for XSLT/XQuery input, if you are using either of these in your document.
- The "Schema Components" tab lists all of the defined elements if you are looking at an XML schema. Clicking the name of an element will highlight it in the schema for you.
3.2. Main Window
At the top of the main document window, you will see tabs for each document you have open (marked in green). The colored dot next to the name of the file indicates what type of file it is, for instance: red is XML, green is a stylesheet, blue is a DTD, etc. When you edit a file, you will also notice that a "*" appears next to the name. This means that there are changes that need to be saved. Save the file, and it goes away. Click the X on the tab to close a document.
On the left you will see a bunch of numbers counting up from 1 (marked in blue). These are counting the lines of text in your document. It is useful when <oXygen> or another validator says you have an error in "line x." To the left of the numbers is a light blue bar. If you click inside this bar, a number will appear. Click again and more appear, for a maximum of 9. These numbers mark a line of text to help you remember where something is. You can even hit ctrl and the number to jump to that number.
On the other side of the black numbers, you will see small blue arrows (marked in orange). These mark the positions of starting tags for elements that are more than one line long. As you move the cursor through the document, gray bars will appear next to these arrows, indicating the length from start tag to end tag of the element the cursor is inside of. Clicking on one of the blue arrows will collapse the entire length of that element, making it easier to read your document. It even tells you how many lines are hidden next to the element name. Click again to show the hidden area.
Tip: In very long documents, it can be difficult to remember where things are. If you want to remember where something is, mark it with one of the blue numbers. Then you can hide a big chunk of the text, and when you want to quickly go to that spot, hit ctrl+number to automatically expand the tree.
3.3. Errors
If you've tried writing a document in <oXygen>, you have probably noticed that it checks for errors as you write. If you have errors in a document, a red square will appear in the upper-right corner of the main window. Holding the mouse over this spot will tell you what errors it found. Below the square you will see red marks corresponding to the lines where it thinks there are errors. <oXygen> also underlines errors with a red squiggly line. Clicking the red marks will highlight the area marked by the squiggly line, and a message at the bottom of the window will explain what <oXygen> thinks the problem is. You can get the same message by holding the mouse still over the highlighted text. In the lower-right corner you will see two blue arrows and an X. Clicking these takes you to the next or previous error in the document. Clicking the X tells <oXygen> to ignore all errors until you make more changes to the document.
For more detailed instructions, you can utilize the oXygen tutorial on Box.