Home
Download
Screenshots
User's Guide
Reference
API Documentation

VEX Users Guide

Vex is a visual editor for XML. It makes it easy to edit structured documents as it is to use a wordprocessor. This guide explains what a structured document is and how to use VEX to create one.

Structured Documents

The vast majority of documents created today are created using wordprocessors. You may have noticed that it is often very difficult to create good looking documents using a wordprocessor, or to change the look of a document once it has been created. The main reason for this that wordprocessors combine document content (the words, sentences, headings, etc.) and presentation (the fonts, spacing, and colours used.) If you don't like the default presentation style provided by the product, you have to plan one prior to creating any document. Changing the presentation style after the fact becomes onerous. Users of your presentation style can arbitrarily introduce formatting changes that don't fit in with the overall style. And you can forget about using the same document to produce both a good-looking web page and an attractive printed document.

By separating content from presentation we can realize the following benefits.

The basic technology to implement a structured document approach using open standards and free software is available.

However, there are no free software tools that pull these technologies together into a simple, user-friendly interface. Most users who cannot afford the expensive commercial packages in this space are forced to use text editors and command-line tools to achieve the benefits of structured documents. Non-technical writers are often turned off by the prospect of editing raw XML text.

Vex aims to fill this void.

Getting Started

In this section we describe how to install and create your first document with Vex.

  1. Install Java on your computer. For details see Sun's Java web site.

  2. Download Vex from Sourceforge.

  3. Unpack the .zip or .tar.gz into a directory.

  4. From the command line, run java -jar vex-app.jar. Alternatively, in Windows, double click on vex-app.jar from Windows Explorer.

  5. Click File > New > Article . An article is one of the predefined templates that ships with Vex. Articles are short, general documents that use the Simplified DocBook is an XML language.

Vex creates a new tab for your document, called (untitled). If you try typing some text now, Vex will beep to indicate that the text is being rejected. The reason for this is that your are within the <article> tag (as seen in the lower right corner of the Vex window), and Simplified Docbook does not permit text to be entered directly into that element. This is an example of how Vex constrains documents to a particular structure.

We'll begin by giving our document a title. Click on the Insert button on the toolbar. You will see a list of the elements that are structurally permitted at the current point in the document. Select title and type a title for your document.

Note that the box in the lower-right of the window now indicates we are in a <title> element. Before we can being typing the body of we must move out of the title element by pressing the right arrow key. Note in the lower-right we are now back in the article element. Click on the Insert button again. Notice that the list is slightly different than before. For example, Simplified DocBook does not permit two article titles, so we are not permitted to select title again. Instead, select para and type some text for your document.

Finally, try saving your document by selecting File > Save. If you look at the resulting document in a regular text editor you'll notice it is stored as nicely formatted XML.

Editing With Vex

There are some subtle differences between editing a structured document with Vex and using a regular word processor. This section describes some of these differences.

Selection

The act of selecting a block of text to replace or to surround with an element is performed the same in Vex as in most word processors: by moving the caret while holding the Shift key or by dragging the mouse between two positions. The main difference is that in some cases, Vex will expand the selection so that it does not span only a portion of an element.

To see this in action, place the caret in the middle of an inline element containing some text. While holding the Shift key, move the caret towards the end of the element. As the caret passes the end marker for the element, note that the starting point of the selection jumps to the start of the element. If you move the caret back inside the element (while still holding Shift), you'll notice that the start of the selection jumps back to its original place.

This selection behaviour is Vex's way of preserving the structure of the document. It is based on the assumption that normally you want to manage entire elements.

Inserting Elements

As you create a document, you apply structure by inserting elements. There are several ways to insert an element.

Vex is aware of the DTD that specifies the structure of your document, and will not allow you to insert an element that violates this structure. The list of elements that are available to insert are therefore dependent on the current location of the caret. Similarly, Vex will not allow you to enter text where it is not permitted by the DTD.

If some content is selected when an element is inserted, the selected content is placed within the inserted element. This is handy when you have forgotten to apply an element, or when you wish to rapidly enter text first and apply structure later.

Finally, when inserting an element using Ctrl-Space, you may quickly select the desired element by typing the first few letters of the element name.

Unwrapping and Morphing

Occasionally, you may find that you wish to delete an element but leave the element's content in place. Vex provides this shortcut in the unwrap command. To unwrap an element, simply place the caret within the element (but not within a sub-element of that element!) and select Edit > Unwrap.

A similar operation is to replace the current element with a different one. In Vex this is known as morphing . To morph an element, place the caret within the element, then select a replacement element from the Edit > Morph menu, or by clicking Ctrl-M.

As when inserting elements, Vex prevents unwraps and morphs that would otherwise invalidate the document structure.

Splits and Joins

Users indicate the end of a paragraph to a word processor by pressing the Enter key. Vex has no built-in concept of paragraphs; instead, this behaviour is simulated by using a split. When you press the Enter key, Vex attempts to make two copies of the current element, splitting the element content between the two. Pressing Enter at the end of a paragraph results in a new, empty paragraph, just as in a word processor.

A related concept is a join, where two elements of the same type are joined together into one. You join two elements (such as two paragraphs) by placing the caret near the boundary of the elements and pressing Backspace or Delete.


SourceForge.net Logo