Review of XMLmind XML Editor v3.0

By Tony Self

Introduction

XMLmind is a great introductory tool for technical writers entering the world of structured authoring and DocBook. It successfully hides the esoterics of XML markup from the author, so that the focus can be on the words, rather than the code. At no cost (yes, absolutely free) for the Standard edition, and USD220 for a single user licence for the Professional Edition, XMLmind offers excellent value. The software is available for Linux, Windows and Mac. There are two main problems with XMLmind XML Editor: it does not currently support DITA schemas, and it does not incorporate a (Notepad-like) text editor in case you do need to patch up your code.

How It Works

One of the challenges in creating an XML editor is the fundamental problem that you can't really create a document in XML. You can only create a document in an XML. There are hundreds and hundreds of XML applications; DocBook is one of them, DITA another, and XHTML yet another. There is a wide range of really good XHTML editors on the market, but for most other XML applications, the editing tool of choice will be a generic XML editor. These generic editors are normally text editors. They allow you to edit the tags and attributes and content of the XML document's code.

The other problem facing developers attempting to create an XML editor is that XML is a storage format, not a presentation format. So the old concept of WYSIWYG (What You See Is What You Get) editing can't easily be applied to the majority of XML applications, with XHTML being the obvious exception.

Happily, a trickle of editors is now arriving which provide a richer editing environment for XML applications related to documentation and journalism. XMLmind XML Editor, or XXE, is one of those new editors. XMLmind have addressed the first challenge (too many XML schemas) by only supporting DocBook, Simplified DocBook, DocBook Slides, and XHTML. They have addressed the second challenge by using Cascading Style Sheets (CSS) to render the XML code in the editor, to provide a WYSIWYG-like environment called the styled view.

The editing environment doesn't really show you what your document is going to look like, because your content will later be transformed into one or more delivery formats, such as HTML, PDF, or even RTF. XXE provides transformations to these common outputs directly from a menu, which is a very useful function, particularly for those starting out in XML editing.

XMLmind XML Editor - Styled View

Most good XML editors provide real-time validation. This means the structure and syntax of the XML code is checked to ensure it conforms with the XML schema for the document. XXE incorporates such validation.

Criteria

There are many ways to evaluate software tools, but in this article, I have looked at the software from a technical writing and Help authoring perspective. I have tried to answer questions such as:

Is this a potential documentation tool?
Is this software suitable for writing documentation in DITA, DocBook, or a custom schema?
Will the tool allow the author to effectively transform the documents into common formats such as HTML and PDF?
How easy is it to learn to use the software to a productive level?

To help assess the tool against some of these criteria, I have written this article using XXE (in Simplified DocBook). If you are reading this, then the tool must be adequate at least!

Suitability for Documentation

As an document editor, XXE is not as neat and clean as Word, Framemaker or Dreamweaver, but neither should it be expected to be. It is very easy to get started in the tool, even by stumbling around and trying things. It is important to be reasonably familiar with DocBook before starting a document in earnest, though, as you need to be able to identify which tags to use in which situation.

Creating new documents, and opening existing documents, is straight forward. XXE has a multiple document interface, so you can easily tab between currently open documents.

XXE has a lovely vibe to it. It is not intimidating, it is reasonably intuitive, and it is well featured. It has a spell checker, which I found to be quite eccentric, as the dictionary contained an eclectic mix of words. Nonetheless, it can check in generic English, US English, English English, Canadian English, and German, Spanish, and the common French dialects. The spell checker was XML-aware, in that it provided a Skip Element option, as well as the familiar replace, replace all, ignore, etc.

When editing DocBook documents, there are five views:

Table: XXE DocBook Views

No style sheet	Shows the Tree view, displaying tags and their contents in a structured tree.
DocBook (or Simplified DocBook)	The styled view, a WYSIWYG-like view, showing the content rendered by a pre-defined CSS stylesheet.
Visible inclusions and locations	I coundn't work out what this view was for, and the Help didn't help!
Images displayed as thumbnails	The WYIWYG-like view, but with the images displayed at 25% of their original size.
Document structure	Shows an outline view of the document (at section level).

Most editing will be done in the styled DocBook (WYSIWYG-like) view, but the other views sometimes come in handy. (The documentation does, however, recommend only using the styled view.

The Help system is barely adequate, and really just documents the interface elements. There are no conceptual topics, and no index. However, a comprehensive set of user (and programmer) documentation, including a tutorial, can be downloaded from the XMLmind site, in XHTML, PDF, or DocBook formats. I would recommend taking the time to work through the tutorial before starting with XXE. (But then, how many technical authors actually read the manuals!)

One useful bit of user assistance is the Show Content Model facility, which displays documentation detailing the technical use of the current node in the schema you are using. For example, if you choose the Show Content Model option when the cursor is within a paragraph (or <para> tag) in a DocBook document, the details of use of the <para> element will be displayed in a Help window.

XMLmind XML Editor - Content Model Help

This can be quite handy when working with DocBook, although you have to learn the syntax of content models for the information to be really useful.

An undo/redo facility is an essential feature, and XXE has it. Likewise, normal editing functions such as cut, copy and paste are there. Text can be readily copied from other applications, coming into XXE as plain text, and there is some limited support for drag and drop. A search and replace facility is also provided.

There is a Print option, which was initially intriguing. Would it print the styled view, or the raw code view? Well, it allows you to print both. If the current view is the styled view, then that's what's printed, and if the current view is the Tree view, then the code tree prints. The styled print is perfectly adequate for proof-reading and editing. The Tree view prints just as it displays on screen, which is not as tagged text, but as a structured tree showing tags and their contents.

From time to time, I found I was stumped, and needed to delete the paragraph I was working on and try again. For example, when adding a table, I found myself with a column with missing cells. Obviously, I had added rows to the table the wrong way. To fix the problem, I had to jump to the Tree view, to locate the missing elements and add them.

Writing in DITA and DocBook with XXE

Practically speaking, XXE only supports DocBook and XHTML, although it is technically possible to edit documents in other schemas, including DITA. When editing DITA documents, only the tree view is displayed, which is impractical to efficiently edit in. As a DocBook editor, though, XXE is a very sound tool.

XXE - Tree View (no style sheet applied)

The XXE interface is broken up into three panes: the Document pane, the Edit pane, and the Tools pane. Tagging of document elements is done through the Edit pane on the right of the Document pane. The Tools pane has tabs for editing element tag attributes, search and replace, spell check, inserting special characters, and XML validation. In addition to the three panes, there are comprehensive menus, toolbars, and status bars.

Inserting elements in a DocBook document is typically managed through the toolbar on the Edit pane, with buttons for Insert (adjacent), Insert Before, and Insert After, as well as Replace, Convert and Wrap. Being totally aware of the DocBook schema, XXE provides a list of valid elements when you choose to insert or replace an element.

A Node Path status bar dynamically displays the current position within the document structure, which helps reinforce a mental picture of the document's tagging structure. You can click on one of the elements in the node path to highlight the corresponding element in the document pane; a tidy little feature.

XXE - Note Path status bar

Validation is a powerful and most vital part of XML technology, as it ensures that documents truly conform to the XML schema. XXE dynamically checks the document for validity, and even though the editor makes it difficult to insert a invalid element, it is possible to accidentally delete a required element. As soon as this happens, XXE displays a red warning icon in the status bar at the bottom of the screen. Clicking on the icon displays an explanation of the validation breach, which is hyperlinked to the area of the document concerned. The error messages are sadly difficult to interpret, and I sometimes had to refer to other references to resolve the problem.

XMLmind XML Editor - Validation

As in HTML, tables in DocBook can be quite complicated from a coding point of view. XXE has a great table editor, which made it very easy to create and manage table rows and cells.

Documents written in DocBook are often quite lengthy, and it may be convenient to break the document up into separate files. For example, you may choose to break your document into chapters, and have one DocBook file per chapter. Alternatively, your project may have multiple authors, with each author working on a separate part of the document. XXE supports modular documents, and the process is as easy as the master documents feature in Microsoft Word, and may be more reliable!

Although the tool has a few idiosynchrasies, such as sometimes closing without warning, I found XXE to be generally stable, and I had little difficulty in producing a valid DocBook document without concerning myself with code or tags.

Transformations

DocBook and DITA are storage formats, and not presentation formats. So to deliver a document to an end-user, the DocBook or DITA code has to be transformed into a delivery format such as PDF, RTF, or HTML. The Standard edition of XXE only provides in-built XSL-T transformations to HTML, but the Professional edition (which costs USD220) provides additional XSL-FO transformations to RTF and WordprocessingML (Microsoft Word 2003's XML format). If you purchase a third-party add-on called RendexX XEP Engine, you can additionally produce PDF and PostScript output. (RenderX XEP Desktop costs USD300.)

One of the happy benefits of working with open standards like XML and DocBook is that there are a range of free tools for things such as transformations. Many of the free transformation tools are command line utilities, and can take a bit of mucking around to get working. For this reason, integrated transformations make the authoring experience a lot neater.

In XXE, to produce HTML output, you simply select the Convert Document option from the DocBook menu, and choose Convert to HTML. You can choose from one long HTML page, one long HTML page with a Table of Contents at the top, or multi-page HTML output, broken up by <section>. Curiously, the output is HTML, not XHTML. Using a CSS style sheet, it is straightforward to customise the look-and-feel of the output.

Productivity

I found XXE to be easy to learn, and I could start creating DocBook documents almost straight away. The system seems to have the right balance between features and usability for DocBook authoring. If this tool had DITA support, it would be a must-have software for structured authoring of technical documentation.

XMLmind XML Editor is a very useful and productive DocBook editor. If you're thinking you should get started writing in DocBook, then download and install this tool today.