The KDE DocBook XML toolchain

Kate is a very powerful editor that is installed as part of the kdebase package. Kate is highly customizable, and has many features that make it ideal for XML editing. Kate can syntax highlight DocBook files automatically. Syntax highlighting is a very useful tool to help you navigate a document, and makes small syntax errors, for example, forgetting a closing > sign, very obvious. This is an ideal editor for you use to work with KDE Documentation.

Kate on its own is a very capable editor, but the xml-plugin that is in the kdeaddons package takes it to another level entirely.

With this plugin, Kate can:

• Understand the DocBook DTD
• Show you which elements (tags) are valid at the current location
• Close (recursively) currently open elements.
• List and insert entities, which are very widely used within KDE documentation.

It should be noted that although the XML plugin already understands several variants of common XML dtd's, and although we use it mostly for DocBook within KDE, it's also easy to add your own, using a standardised compiled dtd format.

Emacs and Xemacs both can syntax highlight DocBook out of the box with the sgml-mode. The addition of psgml turns these editors into powerful DocBook aware editors, but the learning curve is steep, and recommended for people who are already comfortable with Emacsen.

With psgml you can:

• List valid elements in the current location.
• List and insert entities.
• Complete recursively all open elements
• Auto insert elements for complex markup (such as tables, or variable lists)
• Validate, and even compile, documents from within the editor
• Normalize broken documents, and find syntax errors.
• "Fold up" parts of the document you are not currently working on
• Hide markup to see only the content, giving you an uncluttered view of the text.
• And much more

Emacs with psgml is the most functional open source and free (as in beer) software available on UNIX platforms, but the learning curve should not be underestimated. If you intend delving deeply into XML, SGML, and/or KDE Documentation, and you are already familiar with operating emacs, it's highly recommended you give it a try, and there are several people very familiar with these tools on the kde-doc-english mailing list. If you are not familiar with emacs, and/or are just maintaining simple documentation, the benefits may not outweigh the learning curve, and Kate + it's XML plugin is a much better choice.

Vi, vim, and others are powerful editors, but don't have any built-in XML or DocBook friendly tools other than syntax highlighting. You can use :set syntax=docbk to turn on DocBook specific syntax highlighting, and this works in KVim also.

The above editors are by no means all that are available. If you have a favourite editor, then by all means use it. Note that KDE Documentation must be committed to CVS in UTF-8 encoding, and an editor that can save directly to this format is advisable. If not, ask on the mailing list, and someone will help you with conversions.

Editors that other writers have had success with include:

• Nedit
• The built in editor from mc (Midnight Commander)
• gedit
• yudit

If you are a user of one of these (or indeed, any other) applications, and have any tips to make them more XML or DocBook friendly, please let us know.

Processing Tools

The following tools are provided as part of a normal KDE installation:

checkXML index.docbook

checkXML will check your document against the DTD, and tell you if there are any syntax errors, and the line numbers they occur on. If there are no errors, it will return you to the prompt with no output.

meinproc index.docbook

meinproc is the main tool used by KDE to transform DocBook XML into HTML for viewing in KHelpCenter. It's a very flexible tool, but in most cases you just want to look at the generated output to proofread, or spot any glaring errors. The above command will create HTML files in your current directory, along with informing you of any syntax errors that prevent processing of the file.

Many people use meinproc to check for validity, and it is the most thorough way to do so, as it also catches some problems where your document is perfectly valid XML but is wrong in some other way, for example, characters that aren't in UTF-8. For most purposes however, checkXML is a much quicker way to check a file, especially when you're working on it. It's worth getting in the habit of running it on a regular basis.

There are several alternate stylesheets available for use in kdelibs/kdoctools/customization. Use them in this manner:

meinproc --stylesheet $KDEDIR/share/apps/ksgmltools2/customization/.xsl

All these stylesheets create html pages in the current directory. The stylesheets available are:

The styles targetted for websites expect a common/ directory in the same level as that containing the HTML pages, which should hold the contents of $KDEDIR/share/doc/HTML/en/common

Ask Daniel to write about xsltproc here

The primary use of KDE Documentation is to produce manuals that will be viewed in KHelpCenter.

Sanity-checking

A number of programs are available which will help you producing a clean handbook. They are meant to catch common errors, and should usually be run when you're about to submit any manual to make sure that everything's tidy.