This document is a brief introduction to editing XML documents with Vex.
Vex is started by running the vex
executable in the
Vex installation directory. When Vex first starts, it asks you to
select a directory to use for a workspace. The workspace is
a special directory that contains projects, which in turn contain
the files you will be editing. Initially, it is OK to select the
default location for the workspace directory, which is a directory
called workspace
under the Vex installation
directory.
You can specify a workspace on the command line using the -data command line switch as follows.
vex -data workspaceDirectory
The Vex main window is shown below.
The centre empty area is known as the editor area, and it is where documents are shown while they are being edited. The panes around the editor areas are known as views. By default, three views are shown. The Navigator view displays the contents of the workspace directory. Normally documents are opened by double-clicking them in the Navigator. The Outline view shows an outline of the document that is currently being edited, while the Properties view shows the attributes of the element at the current location in the current document, or properties of objects in another view that has focus.
The editor area and views can be resized as needed by dragging their borders. Views can even be moved by clicking on their title tab and dragging the view to a new position. New views can be displayed by selecting Window > Show View > Other... (although the most important views for document editing are already shown by default). Whatever changes you make to the layout of the window will be preserved when Vex is restarted.
If you have an existing DocBook or XHTML document, you can open it by choosing File > Open External File.... If you want to create new files, you must create them in a project in your workspace. These concepts are explained below.
If you see XML tags when you open your document, Vex has opened
it in the Text Editor. By default, Vex opens files with the
extensions .xml
, .htm
,
.html
, and .xhtml
using the Vex XML
Editor and all others with the Text Editor. To fix this, rename
your file to have one of the extensions listed above.
Alternatively, you can tell Vex to recognize new filename
extensions by selecting Window > Preferences, then
choosing the Workbench > File Associations page, and
finally by associating the desired filename extension with the Vex
XML Editor.
The normal way to work with documents in Vex is to organize them into projects in your workspace. You can create a new project as follows.
By default, the project will be created in the workspace directory you specified when you started Vex, but this need not be so. Projects can be created anywhere in the filesystem by specifying the directory name when creating a project. The specified directory may be new or may already exist; in either case it is registered as a project in the Vex workspace.
Please note the following subtle points about projects and the workspace. First, projects must be explicitly registered with Vex. Simply creating a subdirectory in the workspace directory is not enough to have the project recognized by Vex. Second, for performance reasons, Vex caches in memory a snapshot of all projects and their files. Any changes you make directly in the filesystem, such as changing one of the files with a text editor, will not be recognized automatically by Vex. If you do make changes directly to a project directory, you must refresh your workspace by right-clicking the appropriate folder in the Navigator view and selecting Refresh.
Vex comes with sample documents to help you get started. Many of the documents are DocBook documents from the Linux Documentation project. These samples are installed as follows.
The import operation creates the project vex-samples in your workspace containing the sample documents.
New Vex documents are created as follows.
Vex opens an empty editor for your new document into which you can start entering content. The following steps guide you through entering some simple content.
body
.h1
is the only remaining element.
Press Enter to insert the h1
element.p
tag using the Insert Assistant.p
tag, meaning it creates a new, empty
p
tag below the current one.