Design Notes for an XML Editor

This document contains a mixture of requirements analysis and design notes for XML editing. The lack of semi-ubiquitous editors for XML documents that are easy to use is seen as stemming from two causes: a lack of the appropriate GUI component, and limitations in XML itself. The limitations in XML can to a great extent be overcome by the design of the editor. When the required GUI components become available (most ideally for the Java platform) then XML will in all probability become the standard format for virtually every kind of document and data file.

Originally published in Aug 2000.

Motivation

Personally, as one of the early pioneers of “outlining programs” in the 70’s, I would like to see XML become so ubiquitous that for all intents and purposes it replaces plain text. The reason: outline structures have so many advantages over their plain text counterparts. Unlike in the 70’s, today there is a readily-understood example to point to: directory-trees. Imagine if all of your files were contained in one long list! To reorganize, you had to click, scroll down, shift and click again, then cut, move to a new position, and paste. What a pain! Much easier to drag a directory to a new location and simply drop it there, along with all if its contents. Imagine, too, how long that list would be. You’d be scrolling forever to find anything. Instead, the directory hierarchy lets you group things into logically related categories, so you expand and collapse the directory display and find things readily.

The same advantages offered by directory trees beome available when processing structured documents. And XML is now the lingua franca of structured documents. Ideally, then, every document or data file you work on would be in XML — including the source code documents for your applications! (See Encoding Source in XML: A Strategic Analysis.) In such a world, XML would be as ubiquitous as plain text is today. I think that ubiquity is achievable, but only if XML is as easy to edit as plain text is today. (Once upon a time, the paucity of editors made it easier to continue using punched cards. I think we are in a similar situation today vis-a-vis XML.)

The Current State of the Art

At the moment, there are two main categories of XML editing options — each of which leaves something to be desired.

In the first category, there are editors that render HTML pages or their equivalent. These editors require huge stylesheets for any document you plan to edit. The stylesheets have to specify font, color, indentation. The editors are complex, and they are expensive. And the stylesheets only work for a single document.

In the second category, we have hiearchy editors (of which the split- pane version is one variety). These editors typically do not interpret any tags at all, so elements like <b> and <i> become parts of the hierarchy, rather than inline display-controls. If only for that reason, such editors tend to be rather unappealing. But there are two other reasons that such editors lack appeal, stemming from limitations in the available GUI components, and limitations in XML itself.

The Goal

But there is a middle ground between these two editing extremes that is ripe for development — a middle ground that will provide the benefits of hierarchical-structure editing (outlining) that does not require the complexities inherent in stylesheet processing. This article is aimed at defining the requirements for that solution.

As an example, you could author an article in XML using logical tags like <heading> and <para>. You would have the ability to collapse and expand entries and move them around easily — in short, all of the benefits associated with “outliner” applications. But when authoring you would be dealing with the logic of the presentation, rather than its format.

You might then have a standard stylesheet that converted the document into HTML for display on a web page — or you might simply leave it in XML, as XML-based browsers become more prevalent. For publication, an XSL/T translator could convert your tags into the kind the magazine publisher wants (most likely, the publisher would do that).

My Kingdom for a (Multiline Tree) GUI Component

Java and XML would seem to be a marriage made in heaven. XML is a platform-neutral standard for data. Java is a platform-neutral standard for writing programs. What could be better than an editor for XML that was written in Java?

That proposition would be valid, were it not for one thing — the lack of a multiline tree display. At the moment, all of the tree display components (like those that display directory trees) only provide for a single line of information for every entry in the tree. For a data file, that limitation could be livable. But for a generic document, the situation is hopelessly restrictive. You wind up having to use two panes for the editor — one of which shows the element hierarchy, and the other of which shows the text for an element you select.

And that, sadly, is what every XML editor written in Java is forced to do. (The only alternative to date is a huge. garish nesting of multicolored boxes that attempts to depict the hierarchy graphically.) The result is considerably less than usable.

For an elegant display, a tree component is needed that is not limited to a single line per node (entry) in the tree. Java really needs a tree component that can display multiple lines — a multiline tree. Unfortunately, though, the development of such a widget is far from trivial. (It is well over a man-year of effort, in all probability approaching two.) But for truly elegant XML editors, it will be a necessity.

XML has Limitations, Too

When it comes to editing documents, XML has two major limitations:

• XML does not identify elements that are “inline” — that is, tags that “mark” part of a string of a text (inline tags), rather than something which “contains” text (container-tags, or structure tags).
• XML does not have a standard for “inline content” — that is “mixed content” containing text and inline tags, which can be followed by container-tags, but *only* by structure tags (not text or other inline tags).

Effect of the Limitations

Because XML does not distinguish between inline and container tags, it’s “mixed content” model is always text + tags. There is no separation between content (text + inline tags) followed by structure (container tags).

Virtually every document in existence uses that content/structure delineation, however. A header consists of text (plus optional formatting and link tags) followed by structure (subheadings).

For most all XML documents then, text that falls between structure elements must be considered invalid. For example:

  <heading>Title of this <i>Important</i> Section
     <section>...text of subsection 1...</section>
     ...text here is bad...
     <section>...text of subsection 2...</section>
  </heading>

Note that the badly-placed text cannot be assigned any logical home in the document hierarchy. It must be considered invalid. But XML’s “mixed content” model allows it there because, once you allow text in an element, you have to allow it everywhere within the scope of that element.

Note:
Schematron is an assertion-based schema mechanism that makes it possible to validate in the desired way. Because you can state as an assertion that no text or inline tags follow structure tags, the XML can be written in the natural form that is most desirable. But for other schema mechanisms like XML schema, the problem holds.

To get around that problem within the context of XML’s mixed content model, documents are defined with extra elements that contain content (text + inline elements), like the <title> element shown here:

  <heading>
     <title>Title of this <i>Important</i> Section</title>
     <section>...text of subsection 1...</section>
     ...text here is bad...
     <section>...text of subsection 2...</section>
  </heading>

Now, XML is capable of identifying the badly placed text, because <heading> is no longer defined as a “mixed content” element. (The <title> element has assumed that role.)

But this solution to the validation problem results in a new problem for XML editing: The structure is rendered more complex, and consumes more vertical whitespace that it otherwise would. When every structure tag in the document adds an extra blank line to the display (like the <heading> tag in the example above), the result becomes unusable. Imagine, for example, if your directory tree had two lines for every directory — one for the container node, and one for its name. Instead of looking like this:

   <dir>home
     <dir>projects
        <dir>editor
        <dir>xml
     <dir>personal
        ...

your directory tree would look like this:

  <dir>
     <name>home
     <dir>
        <name>projects
        <dir>
           <name>editor
        <dir>
           <name>xml
    <dir>
        <name>personal
        ...

That ain’t pretty.

Overcoming the Limitations

The middle-way editor would recognize a small number of standard inline tags:

1. <b>, <i>, <u>, <tt>, <a>–html anchors (&/or XML links)
2. <font>
3. <sub>, <sup>

Most every modern-day editor would “do the right thing” with tags in the (a) category. That is, they would display text in bold, or italic, or what have you. But note that even editors running on old mainframe consoles could handle them reasonably (given the display limitations) by displaying the tags in the text. So instead of seeing:

This Important Heading

you would see:

This <i>Important</i> Heading

Similarly, some editors might support WSYWIG displays for , <sub>, and <sup>. Or they could simply fall back on the “display the tag in the editor”.

Note:
Really, really cool headers would understand tables. But a lot of useful editing can take place even without that feature.

Given a small set of displayable inline-tags, the editor’s “style sheets” do not need to be anything more complex this:

  <code>=<tt>

which says: define the (new) tag <code> as equivalent to <tt>. That is: Treat <code> as an inline element and use <tt> behavior to display the text it marks. [Here I’m trying to avoid use of the word “contains” in order to keep a clear separation between “container elements, which contain things” and “inline elements, which mark things”.)

Such “stylesheets” could be defined for particular file extensions, or globally for the editor as a whole. The default set might include these:

  <strong>=<b>
  <code>=<tt>
  <em>=<i>
  <def>=<i>

(The last one in that list is a favorite of mine. It lets you identify a term that is being defined in the current paragraph. Then the term is both italicized at that point and easily identify later for inclusion in the index.)

Given the ability to recognize inline tags, the editor can now identify structure tags — all tags other than inline tags. It can then do the kind of “inline content” validation that XML lacks. That is, it can verify that text and inline tags occur only in their proper place (immediately after a start-tag, and before any other structure tags it contains).

Notes:

• The idea of having the editor do the validation was originally proposed to me by Warner Ornstine. I tried for a long time to find a way around it, and have reached the conclusion that, at this point in time, there is no other way.
• The system isn’t fool-proof, because other applications do not have the right kinds of validation mechanisms. So they could still generate text in the wrong place. But if editors began to enforce “inline content” validation, pressure would likely mount to augment XML’s validation mechanisms to do likewise.
• Also, the editors become somewhat more difficult to construct. But again, those difficulties will only disappear when XML is extended to identify inlinable tags.

Using the Minimal-Styles Editor

Suppose, for a moment, that the editor does encounter an error when reading an XML file. Suppose it finds text after an element that it presumed to be a structure element. Let’s say it sees something like this:

  The term <def>xyzzy</def> refers to a magic incantation...

If the editor has not been told that <def> is equivalent to <i>, it will then report an error, because text has been found after the <def> element.

Immediately upon seeing the error, the editor can present the user with three choices:

1. Confirm that it is an error
2. Define <def> as an inline tag and add it to the global “stylesheet”
3. Define <def> and add it to the stylesheet for that extension.

In fairly easy, interactive fashion, then, the appropriate “stylesheets” can be created as documents are edited.

Note:
I need a synonym for “stylesheets” that represents the truly simple thing the inline-equivalences are. For lack of a good name, I keep putting “stylesheets” in quotes, to distinguish them from the complex entities usually denoted by the term.

Summary

With the ability to recognize inline tags, and therefore identify structure tags, a minimal hierarchical editor can do a reasonable job with most any document.

Copyright © 2017, TreeLight PenWorks

Please share!