The KDE DocBook XML toolchain

Editors

Many writers already have a favourite editor, and many of you will find it faster to get work done in a less xml-friendly editor, than to learn a new application. However, the following tools can ease your work, and are worth a look.

Kate

Kate is a very powerful editor. 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.

The XML Plugin for Kate

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.

(X)Emacs + psgml

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(m) and friends

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.

There is a script available at www.vim.org that adds some further capabilities to vim, including the ability to insert tags automatically.

If you are already familiar with vi, then you should feel right at home using it for editing DocBook, but it's not the recommended editor for those of you who are new to UNIX.

Other editors

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 Git 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:

checkXML5

checkXML5 index.docbook

checkXML5 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.

meinproc5

meinproc5 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 meinproc5 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, checkXML5 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.

Alternate stylesheets

There are several alternate stylesheets available for use in https://commits.kde.org/kdoctools?path=src/customization/. Use them in this manner:

meinproc5 --stylesheet path/to/<stylesheet>.xsl

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

kde-chunk-online.xsl

Similar to the standard KDE stylesheet, this is used to create the pages on http://docs.kde.org.

kde-nochunk.xsl

Creates a simplified layout, without banner graphics, and all in one page. This is suitable for processing further with html2pdf for printable output, as an interim solution until we have a reliable print output mechanism. It should also print fairly nicely directly from a web browser.

kde-web.xsl

Creates a static web friendly page, suitable for using in a website that uses frames, or where you want to constrain the content to a particular width.

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 https://commits.kde.org/kdoctools?path=common/en/.

KHelpCenter

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