Copyright © 2000, 2001, 2002, 2003 Lauri Watts
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
A quick reference guide to the current KDE DocBook markup standards
Table of Contents
- General KDE markup style guide
- Purpose of this document
- The Prologue
- Chapters and Sections
- The linking elements
- The GUI elements, menus, toolbars and shortcuts.
- Describing actions and commands
- Questions and Answers
- Images and Examples
- General markup (not covered elsewhere)
- Admonitions: Tips, hints, and Warnings.
- The synopsis elements
- Markup for programming
- Making Callouts
- References, indexes, and glossaries
- Tags we do not use
- Alphabetical List of all elements
- Credits and License
Format for readability, and content, not for a formatted document.
It is not your job or responsibility to make sure the final documentation looks good. If you use appropriate markup tags for the content of your documentation, the processing tools will ensure your document looks good. Do not substitute an inappropriate DocBook XML tag because you do not like the “look” of the correct tag.
You should use white space to make the DocBook source more readable to the writer. Please do not indent unless it is absolutely necessary.
Do what you can to ensure you turn in a valid DocBook file. The reviewers will correct any DocBook errors you create, but please try to reduce errors by checking your work before it is turned in. If you have the KDE tools installed, you can use the command
checkXMLto check for syntax errors. No result from checkXML is a good result - it means there are no problems.
Non-English words should be tagged with <foreignphrase lang="de">Wort</foreignphrase>.
Underlining and CAPITALIZING entire words are leftovers from the days of typewriters. They are no longer appropriate for today's documents.
Do not use quotation marks in your documentation. If you want a word to appear within quotation marks, simply enclose it between
This software is provided <quote>as is</quote>.
There are three different “dashes” that are commonly found in documentation.
The hyphen combines two or more words into one. For example, “mother-in-law”. The hyphen can be entered directly from the keyboard.
The en-dash is used to seperate numbers/dates/etc.. For example, “Sections 1–3 review basic concepts”. The en-dash can be encoded using
The em-dash is used to separate sentences, or to show that something is missing. This is rarely used in technical documentation, but it can be used to show that one sentence is interrupted by another. The em-dash can be encoded using
When trying to decide between an ordered and unordered list, simply ask yourself the following question: “Does the order of the listed items matter?” or “If I change the order of the listed items, does that change the meaning of the list?”. If you answer “No” to either question, then an unordered list is likely the logical choice.
<secttags must have an