Xerlin 1.1 User Guide

A full explanation of XML is beyond the scope of this document, however we will cover some of the basic XML concepts you will need to know in order to use Xerlin prodcutively. XML stands for eXtensible Markup Language. It is similar to HTML, HyperText Markup Language, except users can create their own tags to fit their application needs.

   <elementname attribute="value">content</elementname>
	  

Xerlin requires a computer system with the following:

Xerlin requires a Java Virtual Machine (JVM) which implements Sun's Java 2 Standard Edition. Recommended versions are JDK or JRE version 1.2.2 and later. Xerlin has been tested to work with Sun's JDK 1.2.2 and 1.3 on Windows, Linux x86, and Solaris (x86 and sparc) platforms. It has also been tested with IBM's JDK 1.3 on Linux. Other platforms with a working JVM of these versions should work fine, but haven't been fully tested. Sun's Java 2 SE is available from http://java.sun.com/j2se/. You need either the Runtime Environment, or the SDK.

Note: As of this writing, there is no Java 2 Platform for the classic MacOS (7, 8, or 9). However, MacOS X has a Java 2 Virtual Machine which we have not yet had a chance to test Xerlin with.

The latest release of Xerlin is always available at http://www.xerlin.org/. Click on the Download link in the navigation bar. Download the current release for your system. There is a Zip file for Windows users, and a Gzipped Tar file for UNIX users. You just need the binary release to run Xerlin. The source distribution is available separately for those developers who want to use it.

You can unpack the distribution anywhere you want on your system. Simply expand the zip or tar file and move the Xerlin-1.2 directory it creates where you want it.

To run Xerlin, simply double-click the Xerlin.bat application if you're on Windows, or run the Xerlin.sh shell script on UNIX (you may need to make it executable first). You can also start Xerlin from a command prompt with java -jar Xerlin-1.2.jar. The Xerlin splash screen should appear, and begin loading the application. If any major errors occur during startup, some kind of error message may appear in the command prompt terminal window.

If this starts up and gives you a blank window with menus at the top, you have successfully installed Xerlin. The next chapter will get you started in using Xerlin to create and edit XML files.

Xerlin can create new documents, or work with existing ones. In both cases, you must have a valid DTD describing the possible structure of your document as dicussed in the section called “DTDs and Schemas” To start a new document, select New File from the File menu, or click the New File button on the toolbar.

When you create a new document, Xerlin must first setup the DOCTYPE for the XML file. First, you must select a DTD file. Xerlin brings up the DTD Chooser panel shown in Figure 3.2 for you to select a DTD from a plugin or from your local filesystem.

Figure 3.2. DTD Chooser Panel

Select a DTD, or Browse your filesystem for one, then click OK

The DTD's shown initially are from DTD plugins installed in the Xerlin plugins directory (see Chapter 5). The labels given are the DTD's PUBLIC identifier given by the plugin config. When you've opened documents or selected other DTD's on your filesystem, those new DTD's will also show up on your DTD Chooser until you quit Xerlin. If a DTD doesn't have a PUBLIC id, the SYSTEM id is shown on the DTD Chooser instead. Select the DTD you want to use, and click the OK button.

If there are errors in the DTD file, an error message will be given such as in Figure 3.3 You will need to correct these errors in the DTD before you can edit a document using that DTD.

Figure 3.3. Error in a DTD

If you're using a DTD from your filesystem Xerlin will ask for a Public id. If you don't want to set a public id for the DTD, you can just click the None button. Next Xerlin will ask for the root element as in Figure 3.4 You can select one from the list, or type one if you know which root element you want. Once you've created the document, you cannot change the DOCTYPE, including the root element, from within Xerlin. Note that DTD plugins can setup the DOCTYPE without involving the end user.

Figure 3.4. Root Element Chooser

Once you have a new document (Figure 3.5) you are ready to start adding new elements to it.

Figure 3.5. New Example Document

To add new elements to your document, right-click on the item you want to add something to, and go to the Add menu as shown in Figure 3.6. Xerlin displays just the elements that are valid to add at the point specified by the element you right-clicked on. There are also menus for adding elements Before or After the given element. These menus are all built from the DTD at runtime, so you can only create documents which are valid according to the DTD.

Figure 3.6. Add Menu

When you add an element into another, it places it at the end of the parent element. Use the Add->Before and Add->After if you need to be more precise about where a new element should be placed.

You can also add comments and processing instructions from the Add->Special menu. These show up as "#comment" and "?pi?" in the Element Tree.

When you add a new item to the Element Tree, the element's attribute editor is added to the right-hand pane allowing you to set attributes, and text for the new node. Figure 3.7 shows the attribute editor for a new <p> using the Xerlin Example DTD.

Figure 3.7. Editing Attributes

There are two ways to move elements and restructure your document. On platforms which support Drag & Drop, you can drag an element from the tree and drop it into a place where the element is valid according to the DTD. You can drop it within the same document or on another document of the same type. Lines and rectangles are drawn on the tree as you're dragging over it to show where the element would be dropped if you release the mouse. You can also drag items into the library as dicussed in Chapter 4 If the drop location does not allow the item being dragged to be inserted at that point, an error message will appear for a few seconds in the status bar at the bottom of the document window.

The second and probably more reliable method for moving elements is to use Copy or Cut, and Paste. Use the copy and paste menu items available when you right-click on an element. These actions don't work from the menus for elements in the tree view with Xerlin 1.2. You can paste items into, after, or before another node. This works the same as the Add, Add->Before, and Add->After actions. Only valid pastes according to the DTD will be allowed as shown in Figure 3.8

Figure 3.8. Pasting Nodes

To remove elements, simply right-click on what you want to removed, and choose Delete. This removes the highlighted element and its sub-elements. If you accidentally delete something you didn't want to, Xerlin supports up to 10 levels of Undo. Undo also works for Cut, Paste, and Adding of elements.

To use a Library, you first need to create a new one, or open an existing one. To create a new one, simply choose the New Library item on the File menu. Xerlin will ask for a name for the library. This is just a symbolic name you can use to keep track of different libraries. This name is used at the title of the library window. Next you will be given a Save File dialog. Choose a filename and location for the library file. Libraries are saved automatically when you close it, or when you quit Xerlin, so the file location must be determined before creating the library.

When you first have a new library, the window is empty. You must add sections to it before you can add any elements to the library. These sections provide a way to organize many items into categories. To add a new section, right-click in the library window, and choose New Section as shown in Figure 4.1

Figure 4.1. New Section in a Library

After you have a section, you can add items by drag & drop as discussed in the section called “Moving and Removing Elements” or copy and paste into the section you want to put something in.

Once you have a library with your templates and other elements you want to reuse, you can use the items by copy & paste, or drag & drop. The same DTD-based rules apply to elements coming from the library as to elements from other documents. If there is more than one element in a library item, then only the first element is checked for validity with the destination. Also, Xerlin 1.2 does not enforce that the document an element came from and the document it's being pasted into have the same DTD or doctype.

The Library is automatically saved when you quit, or when you close the library window. If you specifically want to make sure your changes to the library are saved, you need to close the library window.

DTD Plugins provide a way to add DTDs to Xerlin's DTD Chooser, and special editing actions for specific DTDs. DTD plugins show up on the Help->About Plugins menu, but not on the Plugins menu itself. When you start a new document or edit an existing document with a PUBLIC identifier which is the same as one specified by a DTD plugin, the DTD and custom editors associated with that plugin are used. DTD plugins can also provide the SYSTEM identifer and the root element to use for that DTD.

The Xerlin Example plugin has a custom editor which appears where there is a color attribute on elements for that DTD as shown in Figure 5.1 This attribute would normally have a textbox where you can enter the hex value for a color, but with the example plugin, you get a button which allows you to use a graphical color chooser. The color you choose is converted to the hex notation and saved in the xml file in that format.

Figure 5.1. Custom Color Attribute Editor

Action plugins perform an action on the foreground document. For example, running an XSLT transformation on the document. Action plugins are listed in the Plugins menu.