The K Desktop Environment

Chapter 3. A Crash Course in DocBook

This tutorial will teach you enough DocBook to write KDE documentation. You will learn how to:

3.1. Anatomy of a DocBook Tag

A DocBook tag consists of an element and attributes. For example, <Chapter ID="Introduction"> contains the element Chapter and the attribute ID. The element modifies the text within the markup, and the element's attributes modify the element. For example, the Chapter element says that all text included within the starting and closing tags should be treated as a chapter, while the ID attribute labels the Chapter so it can be linked to or used as a file name when DocBook is translated to another format.

Most DocBook tags contain a common set of attributes. The common attributes that you will be using most often are Lang, which specifies the language of the data inside the tag, and ID, which labels the tag.

Important

All DocBook tags must have a start and an end tag. If you read through the DocBook Reference you will notice that not all DocBook tags are required to have both start and end tags. Omitting the ending tags where they are not required is not an option because it will make your document inconsistent with the other KDE documentation and it will make it harder to make the transistion to XML DocBook. Also, make sure to follow the proper case of the tag because XML is picky about the case of tags.

For detailed information about tags and a list of all available tags, see the DocBook 3.0 Reference and the DocBook 3.1 Quick Reference.