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.
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.
A presentation style can be applied to many documents after the fact, producing a set of documentation with a very consistent look.
The same set of documents can be run through multiple presentation styles, producing for example both a Web site of HTML pages and a printable PDF document with the same content.
Authors are free to focus on the content of their documents without fiddling with presentation styles.
The basic technology to implement a structured document approach using open standards and free software is available.
XML is widely accepted as a format for structured content. There are many choices of document languages (the particular tags used for denoting document structure), from the simple but limited (Simplified DocBook, XHTML) to complex and robust (DocBook, DITA).
CSS can be used to specify simple presentation styles for XML documents.
XSLT can be used for document structure transformation, and for converting XML documents to HTML for Web presentation.
XSL-FO can be used to format structured documents into PDF and PostScript for high-quality, printable output.
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.
In this section we describe how to install and create your first document with Vex.
Install Java on your computer. For details see Sun's Java web site.
Download Vex from Sourceforge.
Unpack the .zip or .tar.gz into a directory.
From the command line, run java
-jar vex-app.jar
. Alternatively, in Windows, double
click on vex-app.jar
from
Windows Explorer.
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.
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.
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.
As you create a document, you apply structure by inserting elements. There are several ways to insert an element.
via the Edit > Insert
menu
via the Insert
button on the toolbar
by pressing Ctrl-Space
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.
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.
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
.