DocBook IntroductionAll 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.
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.”