Difference between revisions of "Documentation Primer/Manual/DocBook Reference/General markup"

Revision as of 10:08, 1 September 2012

Other languages:

English

Information
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.

General markup (not covered elsewhere)

<abbrev>

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.

<acronym>

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.

<attribution>

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

<blockquote>

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.

<emphasis>

Use this to emphasise text. Don't 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 of one word or short phrase, and try not to use it too much. Emphasis loses it's power when over used.

<computerouput>

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

<epigraph>

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>

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

<hardware>

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

<lineannotation>

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.

<literal>

In KDE Documentation, this is 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:)

<literal role="extension">*.tar.gz</literal>

<literallayout>

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).

<markup>

Use to wrap markup examples, for 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 won't have much need for markup.

<optional>

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

<para>

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.

<quote>

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.

<trademark class="">

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

copyright
registered
service
trade

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.

<sgmltag>

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:

attvalue, for the contents of an attribute.

attribute, for attributes.

element, for element names.

endtag, for closing tags (e.g. </para>.

emptytag, for tags which are "empty", such as <br/> in XHTML.

genentity, for markup up general entities. For example,   in XHTML

numcharref, to mark up a numbered character reference.  , for example, could also be referred to as  .

paramentity . You are unlikely to need this for any KDE documentation.

pi . Note this is an SGML PI, not an XML one. You are very unlikely to need this for any KDE documentation.

xmlpi. An XML processing instruction, such as

starttag. An opening tag, such as <para>. Most of this document is marked up this way.

sgmlcomment.

<superscript>

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

<msgtext>

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

<subscript>

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

<foreignphrase lang="">

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.

@@ Line 1: / Line 1: @@
+<languages />
+{{Transferring}}
 <translate>