Installation guide to KDE documentation tools

Why you probably don't need these instructions

Previously, KDE documentation was written in DocBook SGML. In mid 2001, this was changed to DocBook XML. While this format currently allows many more output formats than we currently can manage, this situation will change with time, and it does relieve one nagging problem - the difficulty of installing the tools needed to process the SGML format.

Currently, with DocBook XML, nearly all the tools you need are installed as part of a normal KDE installation, in the kdelibs package. The only external requirement is libxml2, which you can find either from your distribution's normal channels, or from the project website http://www.xmlsoft.org.

Some of you may want to keep an SGML version of documentation, especially if you want to process your documents into more print friendly formats, such as TeX, or you want to create *roff output. In this case, read on. KDE provides the xmlizer script, which will convert SGML to XML. For the most part, a valid DocBook XML document will be a valid SGML document with just a change in the prologue, and removing any closure of empty elements.

If you do need to install the DocBook SGML tools, please read on for comprehensive instrcutions.

Why would you need these instructions?

These pages have been written to help you if you are in one of the following situations:

• You are a KDE user, but the Linux distribution you are using comes without documentation for KDE, and you courageously want to fix it yourself.

• You are a KDE user and you are attempting to download and recompile KDE yourself, but you failed in building KDE's documentation.
• You are a distribution packager, but you failed in building KDE's documentation.
• You are a KDE documentation writer or translator, and you need these tools to check your work.

Note: If you are using the KDE tarballs (from KDE's FTP server or one of its mirrors), the HTML documentation is already built and included in the tarballs, and you should not need this help.

What is described here?

The KDE distribution of the DocBook tools includes a recent, standard-conformant distribution of the basic tools necessary to convert and manipulate DocBook files, together with a minimal customization for KDE of this tools, that ensures KDE look-and-feel of the generated documentation, as well as enhancements like additional languages support.

The following sections explain how to download, install and run the DocBook tools to build KDE's documentation.

Note: We have currently no instructions if your system is in one of the following cases:

• Processor other than Intel or PowerPC

• Slackware, Solaris, or other system that is neither RPM-based nor DEB-based

This does not mean that it's impossible to install the KDE DocBook tools on such a system. But this means that:

• You should have some technical knowledge

• You might need to do this in collaboration with me

• Once you succeed, you should put your packages online, and write instructions to make it easier for others.

The steps

To install the KDE documentation tools, follow these steps:

• Step 1 - Downloading the KDE documentation tools
• Step 2 - Installing the basic DocBook tools
  • on a RPM-based system (RedHat-like)
  • on a DEB-based system (Debian-like)
• Step 3 - Installing the KDE-specific stuff
• Step 4 - Using the KDE documentation tools