Writing DocBook XML With A GUI Editor

Rather than writing DocBook XML documents by hand using a text editor like notepad or vi, it is often conveinent to use an XML editor with a point-and-click graphical user interface (GUI). This tutorial covers the use of one such editor, XMLMind's XML Editor (XXE), to create DocBook XML documents.

Operating System Requirements

XXE is Java-based and will run on almost any platform that supports Sun Java version 1.4 or better. This means you can edit your DocBook XML documents using Windows, Linux or Mac OS. If your computer does not have Java installed you will need to visit http://java.sun.com and download the J2SE Java Runtime Environment (JRE) for your operating system.

Downloading The Editor

The personal edition of XMLMind's XML editor is available as a free download and comes with a very liberal end-user license. You can find XXE on XMLMind's product page at: http://www.xmlmind.com/products.html. If you plan to convert your documents to HTML, PDF or Rich Text you may also want to download the FO Converter at this time.

Installing XMLMind's XML Editor

Using the Windows setup binary is very easy and can be accomplished quickly by accepting the default directory locations. Other operating systems require using the tar+gzip archive which takes a few more steps.

To install using the tar+gzip archive.

  1. Decide on a suitable location to install. For example, /usr/local.
  2. Extract the archive to the chosen directory.
  3. Create an application launcher on your desktop that points to the xxe shell script.

Which ever method of installation you decide on, make sure that you are logged in as a user with sufficient privileges to accomplish the task.

Troubleshooting Installation

If XXE refuses to run after installation it may be because it is cannot find Java. If this happens, make sure the directory containing the Java binary is included the system's PATH variable. Also, try running XXE from the command-line in order to see any error messages that might appear. If all else fails, check the XXE FAQ.

Creating A New DocBook XML Document

Creating a new document is easy once you get the hang of using the XXE. A short step-by-step example is given below.

  1. Select File, New from the XML Editor's menu.
  2. Choose DocBook Article or DocBook Book as appropriate for your document.
  3. Select Style, Both Tree And Styled Views from the menu to give a better indication of the document's structure.
  4. Fill in the empty title element with the title of your document. Do the same to the section and chapter title elements if you wish.
  5. Add new elements by selecting an existing element in the tree view and choosing Edit, Insert After from the menu. For example, to add another section select an existing section element and perform an Insert After. Then select "section" from the edit tool on the far right of the XXE window.
  6. After adding text to paragraphs you may wish use inline markup for things like commands, user input, ulinks and so on. Do this by highlighting the appropriate text and selecting Edit, Convert from the menu. Element choices appear in the edit tool on the far right.
  7. Some elements, like ulink, have attributes that require values to be filled in. This is done by selecting the element and using the attribute tool. The attribute tool in the same place as the edit tool, but is on the tab that shows a small picture of a two check boxes.
  8. Don't forget to save your work using File, Save from the menu.

Use the XXE help file and product documentation to learn more about how to use the XML Editor.

Publishing The Completed DocBook XML Document

DocBook XML documents may be converted into HTML, PDF or Rich Text formats using XMLMind's FO Converter. The licensing terms and installation process for the converter is very similar to the XML editor. The document conversion is very simple.

  1. Select the DocBook XML input document using the file browser.
  2. Choose the desired transformation. For example, DocBook to PDF.
  3. Select an output directory for the finished files.
  4. Click the Convert button.

Once the conversion is complete the resulting document may be read using the appropriate viewer. For example, a web browser for HTML files or Acrobat Reader for PDF files.