<oXygen/> User Guide

Debugging Your Documents

The W3C XML specification states that a program should not continue to process an XML document if it finds a validation error. The reason is that XML software should be easy to write, and that all XML documents should be compatible. With HTML it was possible to create documents with lots of errors (like when you forget an end tag). One of the main reasons that HTML browsers are so big and incompatible, is that they have their own ways to figure out what a document should look like when they encounter an HTML error. With XML this should not be possible.

However, when creating an XML document, errors are very easily introduced. When working with large projects or many files, the probability that errors will occur is even greater. Determining that your project is error free can be time consuming and even frustrating. For this reason Oxygen provides functions that enable easy error identification and rapid error location.

Checking XML Form

XML with correct syntax is "Well Formed XML" and has correct XML syntax.

A "Well Formed XML" document is a document that conforms to the XML syntax rules.

  • All XML elements must have a closing tag.

  • XML tags are case sensitive.

  • All XML elements must be properly nested.

  • All XML documents must have a root element.

  • Attribute values must always be quoted.

  • With XML, white space is preserved.

Using the Check XML Form function checks your project for any deviation from these rules. If any error is found the result is returned to the Message Panel. Each error is one record in the Result List and is accompanied by an error message. Clicking the record will open the document containing the error and highlight the approximate location.

Example 4.4. Check XML Form Error Message

In our example we will use the case where an end tag is missing from a DocBook listitem element. In this case running Check XML Form will return the following error.

F The element type "listitem"
must be terminated by the matching end-tag "</listitem>".

To resolve the error, click in the result list record which will locate and highlight the errors approximate position. Review the "listitems", identify which is missing an end tag and insert </listitem>.

Validating Documents

A "Valid" XML document is a "Well Formed" XML document, which also conforms to the rules of a Document Type Definition (DTD) or XML Schema, which defines the legal elements of an XML document.

The purpose of a DTD is to define the legal building blocks of an XML document. It defines the document structure with a list of legal elements.

The Oxygen Validate XML function ensures that your document is compliant with the rules defined by an associated DTD, XML Schema or Relax NG schema.

Example 4.5. Validate XML Error Message

In our example we will use the case where a DocBook listitem element does not match the rules of the docbookx.dtd. In this case running Validate XML will return the following error.

E The content of element type
"listitem" must
match"(calloutlist|glosslist|itemizedlist|orderedlist|segmentedlist|
simplelist|variablelist| caution|important|note|tip|warning|
literallayout|programlisting|programlistingco|screen|
screenco|screenshot|synopsis|cmdsynopsis|
funcsynopsis|classsynopsis|fieldsynopsis| constructorsynopsis|
destructorsynopsis|methodsynopsis|formalpara|para|simpara|
address|blockquote|graphic|graphicco|mediaobject|
mediaobjectco|informalequation| informalexample|
informalfigure|informaltable|equation|example|
figure|table|msgset|procedure|sidebar|qandaset|anchor|
bridgehead|remark|highlights|abstract|authorblurb|epigraph| indexterm|beginpage)+".

As you can see, this error message is a little more difficult to understand, so understanding of the syntax or processing rules for the DocBook XML DTD's "listitem" element is required. However, the error message does give us a clue as to the source of the problem, but indicating that "The content of element type "listitem" must match".

Luckily most standards based DTD's, XML Schema's and Relax NG schemas are supplied with reference documentation. This enables us to lookup the element and read about it. In this case we would want to learn about the child elements of "listitem" and their nesting rules. Once we have correctly inserted the required child element and nested it in accordance with the XML rules, the document will become valid on the next validation test.

At the XML Schema validation Oxygen indicates the specification reference for the XML Schema errors. The error messages contain an Info field that when clicked will open the browser on the "XML Schema Part 1:Structures" specification at exactly the point where the error is described thus allowing you to understand the reason for that error.

Figure 4.17. Link to specification for XML Schema errors

Link to specification for XML Schema errors

Quick Document Browsing Using Bookmarks

The concept of bookmark is the same as in other IDEs: the user can mark a position in one edited document so that he can quickly return after further editing and browsing through one or more documents opened at the same time. Up to nine distinct bookmarks can be placed in any opened document. Configurable shortcut key strokes are available for placing bookmarks and for quick return to any of the marked positions.

The key strokes can be configured from Options-> Preferences->Menu shortcut keys.

A bookmark can be placed from Edit-> Bookmarks->Create, from Edit-> Bookmarks->Bookmarks quick creation and by clicking in the margin of the editing area, to the left of the line number area, reserved for bookmarks.

Quickly switching to a position marked by a bookmark can be done by Edit-> Bookmarks->Go to.