Chapter 5. DocBook Introduction

All KDE documentation is produced in DocBook XML format, and writers are encouraged to learn it (although it's by no means necessary, and we're 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're familiar with XML, then you'll feel right at home. If not, don't worry, as most of the gory details aren't 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 “KDE Specialities” for more information about entities. Tags, entities, comments and other parts of XML that aren't simple text are referred to as markup.