Revision as of 09:05, 1 September 2012

These pages are being transferred from UserBase. Please don't work on them until the transfer is complete, and the old UserBase pages have been removed.

Purpose of this document

The purpose of this document is to describe how markup has been standardized within KDE documentation only.

This document is not to be considered more authoritative than the DocBook documentation, including the O'Reilly Duck book. However, there are places where the KDE DTD is more restrictive than, or just differs from, the OASIS DTD, and these are noted in this document. In these cases, follow the instructions here.

Please read and make use of the other documentation available to you, which is much more comprehensive. This document is not intended to be more than a quick reference for KDE authors, to clarify how the DocBook XML elements are used within the KDE Documentation.

Other reference material

Please take a look at the following reference material, rather than relying on this document to answer all your questions.

The complete DocBook SGML (and now XML) reference. Available as a download in several formats, so you can keep a copy on your hard drive for reference. Also available for sale in hard copy - if you see yourself doing a lot of DocBook Authoring, you definitely ought to consider buying it.

A non-KDE specific crash course to marking up documentation. This is the starting point for all KDE documents, including the markup issues discussed here. Note that the current version is written for SGML, but the concepts are still correct for XML.

The KDE Documentation Template

Covers many things not mentioned here, including required and optional chapters, the preferred way to mark up the prologue and bookinfo sections, and how to deal with licensing and credits. It can be found in kdelibs/kdoctools/template.docbook in CVS.