Chapter 5. DocBook Introduction

All KDE documentation is produced in DocBook XML format, and writers are encouraged to learn it (although it is by no means necessary, and we are very happy to receive documentation written in plain text). Although DocBook can look somewhat intimidating to beginners, the markup is extremely self-descriptive, and many people find it easier than HTML to learn.

In this chapter, we'll just take a basic overview of the ideas behind DocBook. For detailed information about individual tags and so on, please see Appendix A, KDE DocBook Reference.

Overview

DocBook is just an application of XML, so if you are familiar with XML, then you will feel right at home. If not, do not worry, as most of the gory details are not required knowledge for simply writing and updating documentation. A DocBook file (and, indeed, any XML file) consists of plain text, with tags surrounding some text to tell you (or a computer) what that text represents. So, a snippet from a DocBook file might look like:

<para>To display the clipboard history, click on the &klipper; icon
 in the &kde; panel, or press <keycombo
action="simul">&Ctrl;&Alt;<keycap>V</keycap></keycombo>. Previous
clipboard entries are shown
 at the top of the pop-up menu which
appears.</para>

The <para> and </para> show the start and end, respectively, of a paragraph. These delimiting marks are called tags, and the content they contain (along with the tags) is called an element. The <keycombo> tag has an extra piece of information specified: action="simul". This is called an attribute, and makes the tag more specific. The words surrounded by & and ; are entities. They're simply variables that expand to some other text, and are widely used in KDE documentation. See the section called “Entities” for more information about entities. Tags, entities, comments and other parts of XML that are not simple text are referred to as markup.