DocBook Introduction
All documentation is produced in DocBook 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 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 .

Overview
DocBook is just an application of , so if you are familiar with , 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 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:

paraTo display the clipboard history, click on the klipper icon
 in the kde panel, or press keycombo
action="simul"CtrlAltkeycapVkeycapkeycombo. 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 documentation. See Entities for more information about entities. Tags, entities, comments and other parts of that are not simple text are referred to as markup.

Content and Presentation
One of the basic principles behind the use of DocBook in is that content and presentation are strictly separated. DocBook files contain the content, and files contain the information about the presentation. This has a number of advantages, some of which are:
When writing, you do not have to worry about whether the information is well presented, just that the information you're writing is correct and readable.
All documentation has a similar look, so once readers are familiar with conventions in one document, they're familiar with all documents.
Documentation is future-proofed, since by providing as much information about content as possible, future formats, search engines, are likely to be catered for easily.
In practice, this means that you should add markup that describes what things are and not how they should appear. So, in the example above, the keycombo (a keyboard shortcut) tells the reader (or computer) that the keys , and V should be pressed simultaneously, but doesn't say anything about how that should be displayed in the final output. (In fact, it appears as V, but it could equally be converted to C-M-V à la or even some other way of showing keyboard shortcuts. What is important is that the DocBook source has the information necessary to work out what is being referred to.)

Entities
Entities (which are simply variables that expand to some other text) are an important part of DocBook markup, and are used particularly widely in documentation. For example, there are entities defined for almost all applications. Therefore, when referring to, for example, in documentation, you should use:

konqueror is, among other things, a
web browser.

This has several advantages. Firstly, it ensures that applications are capitalized and marked-up consistently across all documentation. This means that you do not have to remember whether the help center program is KHelpCenter, KHelpcenter or Khelpcenter: the entity (which is always entirely lowercase) automatically expands to the correct one.
There are entities defined for several classes of names:
All applications 	 As mentioned before, all applications have an entity. The entity name is in entirely lowercase, and expands to the correctly capitalized version of the application name. There is also an entity for itself: kde.
Common English and technology abbreviations 	 For example, is written as ie and ⪚ as eg. This ensures that the same markup and capitalization are used for these abbreviations throughout documentation. Technological abbreviations such as and also have entities, which are capitalized as usual (, HTTP and XML for the previous examples).
Trademarks 	 Names of companies and their products are often trademarked. For this reason, it is important to mark them up with the trademark tag, using the class="registered" attribute if necessary. To reduce effort, and ensure that trademarks are given proper acknowledgment, many common technology-related trademarks have been given entities. For example, the entity X-Window expands to .
Contributor Names 	 Names of contributors to documentation have entities of the form Firstname.Lastname (or Firstname.Initial.Lastname). Email addresses of contributors have entities of the form Firstname.Lastname.mail.
Names of special keys 	 Names of keys on the keyboard are always marked up with either keycap or keysym. Since it can be difficult to distinguish between these two tags, entities have been created for common keys, ⪚, Ctrl and Alt.
The definitions of these entities can be found in the following locations in 3:
Items not requiring translation ( application names, technology abbreviations, trademarks) 	 general.entities
Contributor names and email addresses 	 contributor.entities
Language-specific terms and key names 	 user.entities

Necessary Sections
There are several sections that appear in all DocBook files, even though they are not required by DocBook itself:

  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">

This appears in the prologue immediately after the FPI. See for more details about this section.

<!-- TRANS:ROLES_OF_TRANSLATORS -->

This appears after the authorgroup element, and is a required placeholder for use in translation (also known as i18n from the number of letters between the first and the last of the word internationalization).