I recently ran into a couple of useful tools for documenting XML. The first is a tool that (among other things) can import an XML schema and display it as a UML class diagram. This could be useful when documenting existing systems. The program is called hyperModel, and was written by Dave Carlson, author of Modeling XML Applications with UML: Practical e-Business Applications, and the Clinical Cloud.Solutions website. It can be downloaded without charge from here. The license for the program is not displayed on the website, but it is in the download. It does not appear to contain any pitfalls. Here is an example of a simple XML schema I had lying around:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
            targetNamespace="http://www.TheXMLAdventure.com/schemas/pdfdoc/docindex.xsd" 
            elementFormDefault="qualified">
  <xsd:element name="library">
    <xsd:complexType>
      <xsd:sequence maxOccurs="unbounded">
        <xsd:element name="book">
          <xsd:complexType>
            <xsd:sequence minOccurs="1" maxOccurs="1">
              <xsd:element name="title" type="xsd:string" />
              <xsd:element name="topic" type="xsd:string" 
                           minOccurs="1" maxOccurs="unbounded" />
              <xsd:element name="file" type="xsd:string" />              
              <xsd:element name="url" type="xsd:string" 
                           minOccurs="0" maxOccurs="1" />
            </xsd:sequence>
            <xsd:attribute name="ca-ip" type="xsd:boolean" 
                           default="false" />
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

From the XML schema, the program generated the following UML diagram:

The second tool is the XML to HTML Verbatim Formatter with Syntax Highlighting by Oliver Becker. It is an XML stylesheet that reformats an XML document into an HTML page with syntax highlighting. All you have to do is add a processing instruction to the front of your document, like this:

<?xml-stylesheet href="/xmlverbatimwrapper.xsl" type="text/xsl"?>

This has saved me a lot of time. The tools I use to edit XML, such as VIM and XML Copy Editor, have syntax highlighting. It makes it immeasurably easier to follow the document. But when I cut text out of the editor and paste it into a Word file or a Wiki page, the syntax highlighting is lost. I consider the increase in readability so important that I used to go and manually change the colors of the various XML elements to recreate the highlighting. As you might imagine, that is no fun at all. I had thought of writing an XML stylesheet to do the highlighting, but never got around to it. Then I discovered Oliver's stylesheet, and I'm glad I waited, because it does an excellent job.

The last tool is for users of the Confluence Wiki. When inserting XML code in a Wiki page, you can use the CodeBlock macro to display it. To use it, highlight the XML text, then on the toolbar, select "+" (Insert More Content), "Other Macros", and "CodeBlock". The macro gives you formatting options for several languages and color schemes, as well as whether you want line numbers or for the block to be collapsible.

In edit mode, the code block looks like this:

In display mode, it looks like this: