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.
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>. Previous clipboard entries are shown at the top of the pop-up menu which appears.
</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
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 aren't simple text are referred to as “markup.”