The KDE documentation project is now using DocBook as the preferred format for all documentation. As you will see, this format allows much more flexibility than Linuxdoc at the small price of having to learn a few more tags. To make it as easy as possible to convert to the new format, we have provided conversion scripts, a template for new documentation, and this crash course. We hope you find the transition to DocBook to be as painless as possible and that you enjoy the new features that DocBook brings to KDE documentation.
![]() | Please note that this crash course is designed to be used along with, not instead of, the DocBook Reference. There are a number of cases where it is much easier to refer to the reference rather than trying to rehash what it already covers. Use this guide to understand what tags you need to get by and where to use those tags. |
Many parts of this document were borrowed from the DocBook 3.0 Reference by Eve Maler of ArborText, Inc. and Terry Allen of Fujitsu Software Corporation. The parts of this document that were borrowed from the Reference are Copyright © 1992, 1993, 1994, 1995, 1996, 1997 by HaL Computer Systems, Inc., O'Reilly & Associates, Inc., Fujitsu Software Corporation, and ArborText, Inc.
When the KDE project began in 1996, Linuxdoc was the standard for writing documentation that needed to be published in multiple formats. Unfortunately, Linuxdoc suffers from a number of design limitations that hinder the writing of documentation for modern GUI applications:
Images are difficult to include in a document, making it difficult to include screenshot of the application and to describe widgets such as toolbars.
There is no way to format text into tables other than including preformatted text.
Linuxdoc has an inconsistent design. It is not often clear which tags can be included in other tags and which tags need to be closed.
Incomplete support for some character sets, making it difficult, if not impossible to translate Linuxdoc into some languages.
Weak support for meta information and indexing.
The DocBook format was designed by OASIS consortium specifically for technical documentation. It addresses all of the deficiencies listed above by providing a much richer set of tags to describe the content of your document. The only drawback of DocBook is that it is more complex than Linuxdoc, which makes it a little more difficult to learn. Even if you have never used either Linuxdoc or DocBook before you should be able to become proficient in it just by reading through this guide, examining the template, and using the online or the paper version of [DocBook - The Definitive Guide] published by O'Reilly & Associates.