<oXygen/> XML Editor 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".

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 document function ensures that your document is compliant with the rules defined by an associated DTD, XML Schema, Relax NG or Schematron schema. XML Schema or Relax NG Schema can embed Schematron rules. For Schematron it is possible to select the validation phase.

Example 4.5. Validate document 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 document 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.26. Link to specification for XML Schema errors

Link to specification for XML Schema errors