Getting Started With Vex

This document is a brief introduction to editing XML documents with Vex.

Starting 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

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.

Opening an Existing File

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.

Projects and the Workspace

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.

  1. Right-click in the navigator view and select New > Project...
  2. Select Simple / Project and click Next >
  3. Select a name for your project, for example "mydocs", and click Finish.

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.

Importing the Vex Samples

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.

  1. Right-click in the Navigator view in the top-left of the Vex window.
  2. Select Import....
  3. In the resulting window, select Vex Samples and click Next >.
  4. In the next window, click Finish.

The import operation creates the project vex-samples in your workspace containing the sample documents.

Editing Documents

New Vex documents are created as follows.

  1. Right-click in the navigator view and select New > Other...
  2. Select Vex Document and click Next >
  3. From the Document Type dropdown, select -//W3C//DTD XHTML 1.0 Strict//EN.
  4. From the Root Element dropdown, select html.
  5. Click Next >
  6. In the folder tree control, select the desired location for the file, for example the "mydocs" project. Enter a name for the file in the File name control and click Finish.

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.

  1. Right-click in the editor area and select Insert > head.
  2. Right-click again and select Insert > title. Note how the path at the top of the editor shows your current location in the document: /html/head/title
  3. Enter a title for your document, e.g. "My Title".
  4. Press the down arrow twice. You should now be at the bottom of the document. You can confirm this by looking at the top of the editor, which should show the path /html.
  5. By now you're probably thinking that right-clicking to insert elements will quickly become tedious. This time, press Ctrl-Space to display the Insert Assistant. You will see a list of the elements that are valid to insert at the current caret location. Press Enter to insert the only possible completion, body.
  6. Press Ctrl-Space again. You will see a much large set of potential elements to be inserted. To filter the list down, press h. Notice that the list is now filtered to show only those elements starting with "h". Now press 1 and notice that h1 is the only remaining element. Press Enter to insert the h1 element.
  7. Enter a title for your document.
  8. Press the down arrow to move the caret out of the h1 element and back to the body of the document.
  9. Insert a p tag using the Insert Assistant.
  10. Enter some text.
  11. Press the Enter key. Vex performs a split of the current p tag, meaning it creates a new, empty p tag below the current one.
  12. Enter more text as the second paragraph document. LogoBuilt On Eclipse