The K Desktop Environment

Chapter 1. Introduction

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.

Note

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.

1.1. Why DocBook?

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:

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.