Loading...
 
Search icon Looking for something?


Introduction to the oXygen 11 XML Editor
Published
2010, Q1 (April 06, 2010)
By Sheila Loring, Senior Member, Carolina Chapter
Photo of Sheila Loring
Sheila Loring


Introduction

XML (Extensible Markup Language) is a set of rules that lets you define words, or elements, to describe and organize your content. For example, you might have a book element that requires a cover page, one or more topics, and an optional index. You can restrict each element to require that certain elements be arranged in a particular order. A topic might require a title followed by paragraphs, lists, tables, and figures in any particular order.

I want to introduce you to authoring the oXygen XML editor. This article focuses on Darwin Information Typing Architecture (DITA) support.

XML authoring issues

Authoring in an XML editor can be frustrating for several reasons:
  • Some authors prefer to write in a text or code view. Inserting content through menu items and palettes often slows down the authoring process, especially for advanced users. Extensible Stylesheet Language Transformations (XSLT) developers also typically prefer working in code view.
  • Other authors are accustomed to using palettes or menu items to insert content.
  • Some authors prefer to have both options. Cross-references are easier to insert through a dialog box; authors simply select the file containing the target element. Then authors don't have to remember the exact location of the element or its ID attribute value. Authors more familiar with XML might prefer to type elements.

oXygen provides authors with all of the preceding options.

Author view

In the Author view, the content is displayed instead of the actual XML markup. oXygen formats the content with Cascading Style Sheets (CSS). For example, a title element is formatted in a large, bold font. Step elements are preceded by step numbers, just as you would expect to see in a desktop publishing application or web browser.

Figure 1. A DITA file displayed in the Author view
Figure 1. A DITA file displayed in the Author view


If you don't like oXygen's onscreen formatting, you can modify the CSS. (For DITA files, the CSS files live in C:\Program Files\Oxygen XML Editor 11\frameworks\dita\css_classed.)

The Author view provides several ways to insert elements.

When you click after an element and press Enter, a contextual drop-down list is displayed (Figure 2). The list only shows the valid elements based on the location of your cursor in the structure. You arrow down to select the element you want to insert, or you type the element and press Enter when the element is displayed in the list.

Figure 2. Element drop-down list
Figure 2. Element drop-down list


Elements are displayed in a palette (Figure 3). Double-click the element to insert it on the page. Again, only elements that are valid at the insertion point are displayed.

Figure 3. Elements palette
Figure 3. Elements palette


The DITA menu item displays a drop-down list from which you insert DITA elements (Figure 4). The DITA menu is not contextual; when you insert a list in an element that doesn't permit lists, oXygen inserts the list, creating an invalid document. You can then drag the element to a valid location.

Figure 4. DITA menu
Figure 4. DITA menu


The DITA toolbar icons let you insert most elements displayed in the DITA menu (Figure 5).

Figure 5. DITA toolbar icons
Figure 5. DITA toolbar icons


Displaying tags

oXygen lets you control the display of elements and attribute in the Author view. The tags display onscreen and in printed documents.
Full tags with attributes displays the element name and attribute (Figure 6). This option is helpful if you don't want to look in the attribute palette to see the attributes assigned to an element. But the tag names and attribute values take up a lot of screen real estate.

Figure 6. Full tags with attributes
Figure 6. Full tags with attributes


Full tags displays tags for all elements (Figure 7). This option is a happy medium between full tags with attributes and the following options.

Figure 7. Full tags
Figure 7. Full tags


Block tags displays tags for block elements (such as taskbody and steps elements) (Figure 8). Inline elements (such as the italics element shown in Figure 7) and comments are not tagged.

Figure 8. Block tags
Figure 8. Block tags


Inline tags displays only tags for inline elements (Figure 9).

Figure 9. Inline tags
Figure 9. Inline tags


Partial tags displays only collapsible triangles for what oXygen calls "simple tags" (Figure 10). I haven't found this setting to be particularly helpful, but someone might appreciate it.

Figure 10. Partial tags
Figure 10. Partial tags


No tags displays no tags (Figure 11). Select this option before printing the document; otherwise, the tags are printed along with the content.

Figure 11. No tags
Figure 11. No tags


Inserting cross-references

As with the other elements, there are many ways to insert cross-references. When you type the cross-reference in the Text view, you have to remember the exact location of the target file. This is fairly easy if the file is close to or in the same directory as the current file. But if the target file is several folders away, it's quicker to insert the cross-reference in the Author view.

To insert a cross-reference in the Author view, follow these steps:
  1. Click where you want to insert the cross-reference.
  2. Select the Link icon and then Cross Reference. The Insert Reference dialog box is displayed (Figure 12).
  3. Select the target of the cross-reference and select OK to insert the cross-reference. (The target element must already have an ID attribute value.) The target may exist in the current file, another open file, or a file you open through the dialog box.

Figure 12. Inserting a cross-reference
Figure 12. Inserting a cross-reference

Inserting tables

Tables consist of several levels of elements that you can type in the Text view. It's quicker, however, to insert tables in the Author view.

To insert a table in the Author view, follow these steps:

  1. Click where you want to insert the table.
  2. Select the Insert a DITA Table icon. The Insert Table dialog box is displayed (Figure 13).
  3. Select the table options (such as the title and number of rows and columns).
  4. Select OK to insert the table.

Figure 13. Inserting a table
Figure 13. Inserting a table


Placeholder text is displayed where you type content in the table cells (Figure 14). The placeholder text disappears when you type text in the cells.

Figure 14. Table
Figure 14. Table


To resize the table columns, click and drag the borders. A dialog box is displayed asking you to verify proportionate resizing or fixed column widths. The colwidth attribute value displayed above the table is then updated (Figure 15).

Figure 15. Resizing columns
Figure 15. Resizing columns


Inserting conrefs

Content references (or conrefs) provide a way to single-source content in DITA. Compare them to text insets in FrameMaker. You insert a link to an element and the content from that element is displayed in the current document. When the content in that element is updated, the content reference is also updated.

To insert a conref in the Author view, select the Insert a DITA Content Reference icon and then select the conref target (Figure 16). The target already must have an ID attribute value.

Figure 16. Inserting a conref
Figure 16. Inserting a conref


The conref is displayed in a blue box (Figure 17).

Figure 17. Conref
Figure 17. Conref


Creating keys and keyrefs

oXygen 11.1 supports the DITA 1.2 specification. Now you can take advantage of keys—powerful ways of redirecting links and reusing content. A key is an alias that you set up in a DITA map file and then point to in topic links. In this example, two authors have each created a DITA map that references the same topic. One author wants the related topics link in that topic to point to a web page. The other author wants the related topics link to point to another topic in the book. The authors can redefine the link using a key in their DITA maps without modifying the topic itself. (See http://dita.xml.org/resource/keyref-overview-dita-12 for details).

You create the key in the map file. Working with map files is easier in Text view or the DITA Maps Manager. For this example, we'll work in the DITA Maps Manager and insert the key at the end of the map. (Your documentation group may standardize the location of keys.)

To insert a key for a web page in the Author view, follow these steps:

  1. In the map, click where you want to insert the key and select the Insert a Topic Reference icon. The Insert Topic Reference dialog box is displayed.
  2. Select the keydef element.
  3. Type the URL in the href field.
  4. Select html from the Format drop-down list.
  5. Select external from the Scope drop-down list.
  6. Type the key in the Keys field.
  7. Select Insert and Close to insert the key in the map (Figure 18).
In the other author's map file, the keydef would point to the topic itself.

Figure 18. Creating a key
Figure 18. Creating a key


Next, you create a reference to the key in the shared topic. In this example, we'll insert a related topic link that references the key.

To create a key reference in the Author view, follow these steps:

  1. Make sure the map in which you defined the key is open. The map must also contain a topicref to the shared topic.
  2. In the topic file, click in the related-links element.
  3. Select the Link icon and then select Key Reference. The Insert Key Reference dialog box is dislayed (Figure 22).
  4. Select the key you want to reference.
  5. From the Element name drop-down list, select the element that will reference the key (in this example, link.)
  6. Select OK to insert the link.

Figure 22. Inserting a keyref in a topic
Figure 22. Inserting a keyref in a topic


NOTE: Because oXygen 11.1 supports DITA 1.2, conref ranges, conkeyrefs, and conref actions are also supported. See the oXygen online help for more information.

Text view

The Text view (or code view) lets you type the elements and attributes. As in the Author view, you have the option of selecting the element or attribute from a contextual drop-down list. Let's say you want to create a table with a border. You can't remember the name of the attribute that applies the border. You also can't remember which elements the table element requires (another good reason to create the table in Author view).

To create a table in the Text view, follow these steps:

  1. Click where you want to insert the table.
  2. Type <table followed by a space. The valid attributes are displayed in a drop-down list (Figure 23).
    Figure 23. Attributes drop-down list
    Figure 23. Attributes drop-down list
  3. Arrow down, select frame, and press Enter. The frame attribute is inserted. A drop-down list of frame attribute values is displayed (Figure 24).
    Figure 24. Attribute values drop-down list
    Figure 24. Attribute values drop-down list
  4. Arrow down, select the type of border, then press Enter. The attribute value is inserted.
  5. Type the end > to close the element. The table element and frame attribute value are inserted along with the closing table tag. The cursor is dislayed between the opening and closing table tags. Notice that the table element is underlined. This indicates that the table requires additional elements (Figure 25).
    Figure 25. Table element
    Figure 25. Table element
  6. Type the beginning < for the next element. A drop-down list of valid elements is displayed (Figure 26.)
    Figure 26. Table elements drop-down list
    Figure 26. Table elements drop-down list
  7. Select the element and press Enter to insert the element.
You can also begin to type the attribute or attribute value and press Enter when the name is displayed.

Help understanding elements and attributes

oXygen can also display a description of each element and attribute (called annotations) (Figure 27). This feature is helpful when you're beginning to author in XML. For example, when you place your cursor over a concept element, a description of the element is displayed as a tooltip. Because the descriptions can be obtrusive, I recommend turning off this feature when you no longer need guidance. (To turn off annotations, select Options > Preferences > Editor > Content Completion > Annotations > Show annotations as tooltips.
Figure 27. Concept annotation
Figure 27. Concept annotation

Updating the closing element

The closing element is also automatically inserted when you type the beginning element. For example, when you type the table element, the closing table element is inserted. The cursor is automatically displayed between the elements so you can immediately begin typing content. In the Text view, oXygen automatically updates the closing element when you change the opening element. Let's say you type <p>, and oXygen inserts the closing </p> element. When you change the opening <p> element to <codeblock>, oXygen changes the closing element to </codeblock>. If you mistype the opening element, however, the closing element is also misspelled. For example, when you change the opening element to <codebolck>, the closing element is spelled </codebolck>. The misspelled element is underlined to point that the document is invalid.
Figure 28. Auto-updated closing element
Figure 28. Auto-updated closing element

Commenting code

To prevent XML from being processed, type <!-- --> around the code. oXygen provides several commenting shortcuts. Select existing code and press Ctrl+Shift+Comma or right-click the selected code and select Toggle Comment. Reverse these actions to uncomment code. These shortcuts are really handy when you're testing XSLT. Manually typing and deleting comment markup is tedious.

Indenting code

In the Text view, oXygen indents code, so the code is easier to read (Figure 29). Based on how you configure the preferences, oXygen will indent the code automatically when you open a document. When you turn off this option in the preferences, you can indent code at any time by selecting the Format and Indent icon or pressing Ctrl+Shift+P. I prefer to turn off this option in the preferences. Simple or short documents are easy enough to read without indents. It's also a control issue of mine.
Figure 29. Indented code
Figure 29. Indented code
Figure 30. Unindented code
Figure 30. Unindented code
One caution: When you import indented XML into FrameMaker, the indents create white space. The white space makes for an unattractive layout, and you won’t want to create PDFs with the extra white space displayed. This is a problem with any XML editor. You can use the DITA-FMx plug-in to automatically remove the white space. DITA-FMx is a must for any DITA/FrameMaker implementation. Or read Simon Bate’s white paper on the topic.

Creating new documents based on templates

oXygen lets you create new documents based on pre-configured templates. Basic elements are already inserted in new documents based on templates. For example, when you create a new document based on the DITA Concept template, the concept, title, shortdesc, conbody, and p elements are already inserted. You add or remove elements as necessary in your document.
Figure 31. Document based on Concept template
Figure 31. Document based on Concept template
The templates can also be customized. To leave out the shortdesc element from new documents based on templates, remove the element from the template. In oXygen 11.1, the DITA templates are located in oXygen's frameworks\dita\templates\topic folder.

Creating output

oXygen includes predefined types of output. For example, in DITA documents, the XHTML and PDF output types are available by default. You can also define other output formats, such as HTML Help, JavaHelp, Eclipse Help, DocBook, troff, and more. After you've assigned a default output format to a document or map, select the Apply Transformation Scenario icon, and your document or map is converted to the selected output.

Other features

I’ve provided the essentials for creating content and output in oXygen. Other important features include the following:
  • Spelling checker
  • Change tracking
  • Find/replace across multiple files and directories
  • Inserting equations with MathML
  • Microsoft Office/Office Open XML (OOXML) support
  • Open Document Format (ODF) support
  • XSLT and XQuery debuggers
  • Relational database support
  • Integration with the Documentum content management system (CMS)
  • Comparing and merging documents
  • Comparing documents and directories
  • Integration with Subversion 1.7 document management servers
  • Cross-compatibility with Windows, Mac OS X, Linux, and Solaris)

Pricing

oXygen is affordable for such a flexible, feature-rich product. Pricing begins at $64 (for an academic/non-commercial license) to $449 (for an enterprise license). For comparisons of the features, visit http://www.oxygenxml.com/feature_matrix.html.

Support

The oXygen web site includes a user’s guide, articles, active forums, mailing lists, and videos. Tech support is responsive and knowledgeable. XML Press has also published the <oXygen/> XML Editor Version 11 User Manual.

New features

oXygen 11.2 was recently released. Important new features include the following:
  • Better use of schema information to provide smart editing
  • Improved DITA-specific support
  • New Author extension APIs
  • The latest DITA Open Toolkit
  • Support for formatting only the added/changed parts of the document while editing in Author mode, the rest remaining unchanged
  • Support for oXygen Author as a Java applet in a browser and integration with web applications.
Sheila Loring can be reached at sheila dot loring at gmail dot com. End of article.

More articles like this...
Comments powered by Disqus.
RSS