Abbreviations are shortened forms of longer words.

Abbreviations are not normally pronounced in speech. Examples are e.g. and i.e.. This is a KDE specific distinction, please stick to it.

Acronyms are shortened forms of words or phrases, often made up of the initials of the words in a phrase. Acronyms are normally pronounced in speech as well as written. Examples are GUI and KDE. As with <abbrev>, this is a KDE specific distinction.

If you use <quote> or <blockquote>, the source of the quote (that is, who you are quoting) should be cited with this tag.

Use this when you want to quote a passage of text that should be set off from the main text, for example, an entire paragraph from a book or other source. Use <quote> to quote a passage of text that is not to be set off, for example a short sentence or comment from another person. Use both of them as little as you can, there are copyright issues to quoting from other works inside KDE Documentation.

Use this to emphasize text. Do not use it to mark up file names, commands, or anything else. Use it where you might type in all caps in an email, for emphasis on one word or short phrase, and try not to use it too much. Emphasis loses its power when overused.

Text the user can see on the computer screen. For example, a listing of a directory as produced after the command ls would be computeroutput.

A short quote or saying at, sometimes used at the beginning of a chapter as an introduction. Use sparingly, no attributes used by KDE.

Equation is used if you need to mark up a mathematical equation. You are unlikely to need to use this in KDE Documents.

Used when referring to a piece of computer hardware, e.g. Floppy Drive or Monitor.

A comment, for example in a <programlisting>. This is not for comments contained in the text, it is for comments by the author (you) about the text.

In KDE Documentation, this is a markup of last resort (or “the least of all evils”) Use it only for things that must be marked up, but have no appropriate tag, and preferably only for the following things (already decided on:)

Use very sparingly, when it is absolutely vital that some text is presented exactly as it appears, including white space and line breaks. There is almost always a better tag to use than this (screen and computeroutput together, or even a screenshot).

Use to wrap markup examples, for the text that should be represented literally. Examples are this document, and documents that have HTML markup included literally in them. Other than meta-documentation like this, you probably will not have much need for markup.

Optional information, usually in user input. Not used to date in KDE Documentation, but it may be appropriate in some circumstances.

A paragraph. This is the most common tag. You do not need to enclose lists, tables, or other markup with <para>. Sometimes however, you might want to do so, especially with <screen> and some types of lists, when they actually are still part of the current paragraph.

Use when you are quoting something or someone, inside a sentence. Also use if you want a word or phrase to be “enclosed in quotes” like this.

Used to denote that a word is a trademark. There is the optional attribute class which should contain one of the following, if appropriate:

If there is no class="" attribute, “trade” is assumed.

We have provided entities, marked up appropriately, for very commonly met trademarks, including Qt™ (&Qt;), UNIX® (&UNIX;), Linux® (&Linux;) and many more.

An SGML tag. This includes XML and XHTML tags. Use this for marking up individual components, but use <markup> when you need to display a block of markup.

sgmltag will generate the correct markup characters for you, based on the class attribute.

Attribute values available:

Superscript as in x². Unlikely to be required in most KDE Documentation.

The actual text of an informational message. Use <errorname> for error messages.

Used to create things like H₂O. Unlikely to be found in most KDE Documents.

Use this any time you need to use text in a language different than the main language of the document. This should be rare, but may occur especially in credits information. The lang attribute should contain the normal two-letter designation of the language. Please be careful with these, the Country and Language codes are sometimes different, e.g. “se” is the country code for Sweden, but the language code is “sv”. Using “uk” for British English would give you possibly unexpected results, as this is actually the language code for Ukrainian.