Revision as of 08:28, 2 September 2012
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 Duck book
- 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.
- The Crash Course to Docbook
- 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.
- DocBook-XML (in German)
- A very nice book, in German only unfortunately, but comes highly recommended.