TDE
/
tdeaddons
mirror of https://mirror.git.trinitydesktop.org/gitea/TDE/tdeaddons
0
0
Fork 0
Code Issues Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '826b1b771c'
${ noResults }
tdeaddons/doc/tutorials/markup/index.docbook

5311 lines
190 KiB
Raw Normal View History Unescape

Move Tutorials from tdebase. Add docbook & markup tutorials. Tutorials need editing and updating. Thus the default configuration is -DBUILD_TUTORIALS=OFF.
10 years ago
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE"><!-- change language only here -->
]>
<book lang="&language;">
<bookinfo>
<title>The &tde; DocBook Markup Guide</title>
<authorgroup>
<author>
<personname><firstname>Lauri</firstname><surname>Watts</surname></personname>
<email>lauri@kde.org</email>
</author>
<author>&tde-authors;</author>
</authorgroup>
<copyright>
<year>2000</year><year>2001</year><year>2002</year><year>2003</year>
<holder>Lauri Watts</holder>
</copyright>
<copyright>
<year>&tde-copyright-date;</year>
<holder>&tde-team;</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>&tde-release-date;</date>
<releaseinfo>&tde-release-version;</releaseinfo>
<abstract>
<para>
A reference guide to &tde; DocBook markup standards.
Please report any errors or omissions to
Fixed references to TDE website. Signed-off-by: Michele Calgaro <michele.calgaro@yahoo.it>
4 years ago
<email>devels@trinitydesktop.org</email>.
Move Tutorials from tdebase. Add docbook & markup tutorials. Tutorials need editing and updating. Thus the default configuration is -DBUILD_TUTORIALS=OFF.
10 years ago
</para>
</abstract>
<keywordset>
<keyword>TDE</keyword>
<keyword>Docbook</keyword>
<keyword>Documentation</keyword>
<keyword>Authors</keyword>
</keywordset>
</bookinfo>
<chapter id="markup-guide">
<title>General &tde; markup style guide</title>
<itemizedlist>
<listitem>
<para>
Format for readability, and content, not for a formatted document.
</para>
<para>
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 <quote>look</quote> of the correct tag.
</para>
<para>
You should use white space to make the DocBook source more readable to
the writer. Please do not indent unless it is absolutely necessary.
</para>
</listitem>
<listitem>
<para>
Do what you can to ensure you turn in a <emphasis>valid</emphasis>
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 &tde; tools installed, you can use the
command <userinput><command>checkXML</command>
<filename>index.docbook</filename></userinput> to check for syntax
errors. No result from <command>checkXML</command> is a good result -
it means there are no problems.
</para>
</listitem>
<listitem>
<para>
Non-English words should be tagged with <markup>&lt;foreignphrase
lang="de"&gt;Wort&lt;/foreignphrase&gt;</markup>.
</para>
</listitem>
<listitem>
<para>
Underlining and CAPITALIZING entire words are leftovers from the days of
typewriters. They are no longer appropriate for today's documents.
</para>
</listitem>
<listitem>
<para>
Do not use quotation marks in your documentation. If you want a word to
appear within quotation marks, simply enclose it between <sgmltag
class="element">quote</sgmltag> tags.
</para>
<informalexample>
<para>
This software is provided <markup>&lt;quote&gt;as
is&lt;/quote&gt;.</markup>
</para>
</informalexample>
</listitem>
<listitem>
<para>
There are three different <quote>dashes</quote> that are commonly found
in documentation.
</para>
<itemizedlist>
<listitem>
<para>
The hyphen combines two or more words into one. For example,
<quote>mother-in-law</quote>. The hyphen can be entered directly from
the keyboard.
</para>
</listitem>
<listitem>
<para>
The en-dash is used to seperate numbers/dates/&etc;. For example,
<quote>Sections 1&ndash;3 review basic concepts</quote>. The en-dash
can be encoded using <sgmltag class="genentity">ndash</sgmltag>.
</para>
</listitem>
<listitem>
<para>
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 <sgmltag class="genentity">mdash</sgmltag>.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
When trying to decide between an ordered and unordered list, simply ask
yourself the following question: <quote>Does the order of the listed
items matter?</quote> or <quote>If I change the order of the listed
items, does that change the meaning of the list?</quote>. If you answer
<quote>No</quote> to either question, then an unordered list is likely
the logical choice.
</para>
</listitem>
<listitem>
<para>
All <sgmltag class="starttag">chapter</sgmltag> and <sgmltag
class="starttag">sect<replaceable>N</replaceable></sgmltag> tags must
have an <sgmltag class="attribute">id</sgmltag>. The <sgmltag
class="attribute">id</sgmltag> must be in all lower case, and with
dashes separating words. For example, <markup>&lt;sect1
id="how-to-obtain-kapp"&gt;</markup>.
</para>
</listitem>
<listitem>
<para>
All elements must have a full closing tag unless they are empty
elements. Empty elements must still be closed with a /.
</para>
<segmentedlist>
<segtitle>Incorrect</segtitle>
<segtitle>Correct</segtitle>
<seglistitem>
<seg><markup>&lt;para/Blah blah/ or &lt;para&gt;Blah
blah&lt;/&gt;</markup></seg>
<seg><markup>&lt;para&gt;Blah blah&lt;/para&gt;</markup></seg>
</seglistitem>
</segmentedlist>
</listitem>
<listitem>
<para>
No attribute minimization.
</para>
<segmentedlist>
<segtitle>Incorrect</segtitle>
<segtitle>Correct</segtitle>
<seglistitem>
<seg><markup>attribute=value</markup> or
<markup>attribute='value'</markup></seg>
<seg><markup>attribute="value"</markup></seg>
</seglistitem>
</segmentedlist>
</listitem>
<listitem>
<para>
All entities must end with a semi-colon:
</para>
<segmentedlist>
<segtitle>Incorrect</segtitle>
<segtitle>Correct</segtitle>
<seglistitem>
<seg><markup>&percnt;parameterentity</markup> or
<markup>&amp;generalentity</markup></seg>
<seg><markup>&percnt;parameterentity;</markup> or
<markup>&amp;generalentity;</markup></seg>
</seglistitem>
</segmentedlist>
</listitem>
<listitem>
<para>
Element GIs (the first word in a tag) must be written in lower case
only.
</para>
<segmentedlist>
<segtitle>Incorrect</segtitle>
<segtitle>Correct</segtitle>
<seglistitem>
<seg><markup>&lt;MediaObject&gt;</markup> or
<markup>&lt;MEDIAOBJECT&gt;</markup></seg>
<seg><markup>&lt;mediaobject&gt;</markup></seg>
</seglistitem>
</segmentedlist>
<para>
Entities are also case sensitive, and will result in validation errors
if the case is wrong.
</para>
</listitem>
<listitem>
<para>
Specify date and application's version in the format:
</para>
<screen>
<markup>&lt;date&gt;2000-12-31&lt;/date&gt;</markup>
<markup>&lt;releaseinfo&gt;1.02.03&lt;/releaseinfo&gt;</markup>
</screen>
<para>
The <sgmltag class="starttag">date</sgmltag> is the date of the last
update. The <sgmltag class="starttag">releaseinfo</sgmltag> always
matches the version number of the application that is described in the
documentation (if any). A translated version of a documentation always
has the same <sgmltag class="starttag">date</sgmltag> and <sgmltag
class="starttag">releaseinfo</sgmltag> as the English original. Please
respect this, it is the only way to manage efficiently both the writing
and the translation processes.
</para>
</listitem>
<listitem>
<para>
The list of entities for applications is maintained centrally. Entity
names are the application name completely in lower case. In case the
name you need does not exist yet, send a mail to
<email>kde-docbook@kde.org</email> to have it added. You may add it in
the prologue for validation purposes (in case it's new), but don't
forget to remove it when you submit the document, because there should
not be any <quote>extra</quote> entities defined in the document
prologue.
</para>
</listitem>
<listitem>
<para>
For language-independent entities, use
<filename>kdelibs/kdoctools/customization/entities/general.entities</filename>
and for language-specific entities, use
<filename>kdelibs/kdoctools/customization/<replaceable>lang</replaceable>/user.entities</filename>. Try
to avoid clashes with existing &tde; entities.
</para>
</listitem>
<listitem>
<para>
The <filename>en/user.entities</filename> file should be updated
keeping in mind that translation must be possible. Here is an example of
how this translation can be managed:
</para>
<example>
<title>Managing translatable entities</title>
<para>
<sgmltag class="genentity">LMB</sgmltag> is en entity which stands for
<quote>Left Mouse Button</quote>
</para>
<para>
When translating to French for example, do not translate only the entity
contents, please also translate the entity name to <sgmltag
class="genentity">BGS</sgmltag> (or <sgmltag
class="genentity">bgs</sgmltag>), to reflect the change in the
initials:
</para>
<screen> <markup>&lt;!ENTITY "LMB" "left mouse button"&gt;</markup> <lineannotation>becomes</lineannotation>
<markup>&lt;!ENTITY "BGS" "bouton gauche de la souris"&gt;</markup></screen>
<para>
Languages that decline nouns like German and Russian can use something
like the following:
</para>
<screen><markup>
&lt;!ENTITY "LMB" "linke Maustaste"&gt;
&lt;!ENTITY "LMBn" "linken Maustaste"&gt;
</markup></screen>
</example>
</listitem>
<listitem>
<para>
If you feel that some elements don't make fine enough a distinction,
feel free to use the attribute <sgmltag class="attribute">role</sgmltag>
(but please tell the DocBook team, as otherwise you may find your
document to be suddenly invalid).
</para>
</listitem>
<listitem>
<para>
Use <sgmltag class="starttag">qandaset</sgmltag> for
&FAQ;s, not an <sgmltag
class="starttag">itemizedlist</sgmltag>. Please split up a
&FAQ; into several chapters or sections if it gets big.
The &HTML; files get too big otherwise, which the users
may not like.
</para>
</listitem>
<listitem>
<para>
Abbreviations and acronyms should be marked up as well.
</para>
<para>
Use the DocBook tags <sgmltag class="starttag">abbrev</sgmltag> and
<sgmltag class="starttag">acronym</sgmltag> respectivly.
</para>
<para>
Please keep them apart: acronyms are things like &GUI;, &tde;,
<acronym>GPL</acronym>, while abbreviations are things like &etc;, &ie;,
&eg;.
</para>
<para>
There are entities for the most common ones.
</para>
</listitem>
<listitem>
<para>
Use <sgmltag class="starttag">glossterm</sgmltag> or <sgmltag
class="starttag">firstterm</sgmltag> each time you introduce a
technically significant new word.
</para>
</listitem>
<listitem>
<para>
Keep in mind that the <quote>$</quote> sign is introduced by the shell,
and is not part of an environment variable's name:
</para>
<informalexample>
<para>
<userinput><command>ls</command> <option>-l</option>
<parameter>$<envar>TDEDIR</envar></parameter></userinput> is marked up
as</para>
<screen><markup>&lt;userinput&gt;&lt;command&gt;ls&lt;/command&gt;
&lt;option&gt;-l&lt;/option&gt;
&lt;parameter&gt;$&lt;envar&gt;TDEDIR&lt;/envar&gt;&lt;/parameter&gt;
&lt;/userinput&gt;</markup></screen>
<para><userinput><command>export</command>
<parameter>$<envar>TDEDIR</envar>=<replaceable>/usr/local/tde</replaceable></parameter></userinput>
is marked up as:</para>
<screen><markup>&lt;userinput&gt;
&lt;command&gt;export&lt;/command&gt;
&lt;parameter&gt;$&lt;envar&gt;TDEDIR&lt;/envar&gt;=&lt;filename&gt;
/usr/local/tde&lt;/filename&gt;&lt;/parameter&gt;&lt;/userinput&gt;</markup></screen>
</informalexample>
</listitem>
<listitem>
<para>
Only use <sgmltag class="starttag">ulink</sgmltag> for &URL;'s and not
for files, unlike <sgmltag class="starttag">A</sgmltag> in
<acronym>HTML</acronym>. Don't use it for email addresses either, they
have their own element, <sgmltag class="starttag">email</sgmltag>.
</para>
</listitem>
<listitem>
<para>
The elements <sgmltag class="starttag">beginpage</sgmltag> and <sgmltag
class="starttag">bridgehead</sgmltag> are disallowed and have been
removed from the &tde; customized <acronym>DTD</acronym>. (They are not
meant for new technical documentation.) <sgmltag
class="starttag">revisionhistory</sgmltag> has been removed also: we are
using <acronym>SVN</acronym> already.
</para>
</listitem>
</itemizedlist>
</chapter>
<chapter id="purpose">
<title>Purpose of this document</title>
<para>
The purpose of this document is to describe how markup has been standardized within
&tde; documentation only.
</para>
<para>
This document is <emphasis>not</emphasis> to be considered more
authoritative than the DocBook documentation, including the O'Reilly
Duck book. However, there are places where the &tde;
<acronym>DTD</acronym> is more restrictive than, or just differs from,
the <acronym>OASIS</acronym> <acronym>DTD</acronym>, and these are noted
in this document. In these cases, follow the instructions here.
</para>
<para>
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 &tde; authors, to clarify how the
DocBook &XML; elements are used within the &tde; Documentation.
</para>
<sect1>
<title>Other reference material</title>
<para>
Please take a look at the following reference material, rather than
relying on this document to answer all your questions.
</para>
<variablelist>
<varlistentry>
<term><ulink url="http://www.docbook.org/">The Duck book</ulink></term>
<listitem>
<para>
The complete DocBook <acronym>SGML</acronym> (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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink
url="http://opensource.bureau-cornavin.com/crash-course/">The Crash
Course to Docbook</ulink></term>
<listitem>
<para>
A non-&tde; specific crash course to marking up documentation. This is the
starting point for all &tde; documents, including the markup issues discussed
here. Note that the current version is written for
<acronym>SGML</acronym>, but the concepts are still correct for &XML;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>The &tde; Documentation Template</term>
<listitem>
<para>
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 <filename>kdelibs/kdoctools/template.docbook</filename> in <acronym>CVS</acronym>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.millin.de/linux_docbook_xmlbuch.html">DocBook-XML</ulink> (in German)</term>
<listitem>
<para>A very nice book, in German only unfortunately, but comes highly recommended.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="prologue">
<title>The Prologue</title>
<screen><markup>
&lt;?xml version="1.0" ?&gt;
&lt;!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
&lt;!-- Define an entity for your application if it is not part of TDE
CVS --&gt;
&lt;!ENTITY <replaceable>kmyapplication</replaceable> "&lt;application&gt;KMyApp&lt;/application&gt;"&gt;
&lt;!ENTITY kappname "<replaceable>&amp;kmyapplication;</replaceable>"&gt;&lt;!-- replace kmyapplication here
do *not* replace kappname--&gt;
&lt;!ENTITY package "<replaceable>tde-module</replaceable>"&gt;&lt;!-- tdebase, tdeadmin, etc. Leave
this unchanged if your
application is not maintained in TDE GIT --&gt;
&lt;!ENTITY % addindex "IGNORE"&gt;
&lt;!ENTITY % English "INCLUDE"&gt; &lt;!-- ONLY If you are writing non-English
original documentation, change
the language here --&gt;
]&gt;</markup></screen>
<para>
In general, this needs minimal changing from the template. The items
you <emphasis>must</emphasis> change are the entities
<quote>kappname</quote>, <quote>package</quote>, and <quote>English</quote>.
</para>
<para>
The entity <quote>kappname</quote> looks like it's redundant (as the
comment in the template notes), but it is important. This allows us to
use one global text in all documents, and still refer to the specific
application by its correct name. So it should be changed to refer to
this new entity, but this time you should only change the part in quotes
(<quote>&amp;kmyapplication;</quote>) as follow:
</para>
<example>
<title>Setting up the global <quote>kappname</quote> entity</title>
<screen>
From:
<markup>
&lt;!ENTITY kappname "&amp;kmyapplication;" -- this only *seems* redundant --&gt;
</markup>
To:
<markup>
&lt;!ENTITY kappname "&amp;kate;" -- this only *seems* redundant --&gt;
</markup>
</screen>
</example>
<para>In short: change any occurrence of <quote>kmyapplication</quote>
to the real name of your application. Do <emphasis>not</emphasis> use
<quote>kappname</quote> or <quote>kapp</quote> directly in a document
yourself.</para>
<para>The entity <quote>package</quote> is used similarly. It allows
us to insert a single piece of <quote>boilerplate</quote> text into
every document, and have the correct package name inserted when the
document is compiled. Use the cvs module name, in lower case, &eg;
<quote>tdeedu</quote> or <quote>tdebase</quote>.</para>
<para>The entity <sgmltag class="paramentity">addindex</sgmltag> is a toggle. If
set to <quote>INCLUDE</quote> a document index will be automatically
generated. It is normally set instead to <quote>IGNORE</quote>, and should
not be changed unless you really do want to generate an index. You can find
out more about indexes in <xref linkend="references-indexes-glossary"/>.</para>
<example>
<title>A &tde; User Manual Prolog</title>
<para>Here is an example of a completely set up prolog, as it normally
looks. This is the prolog from the &amor; documentation</para>
<screen><markup>&lt;?xml version="1.0" ?&gt;
&lt;!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
&lt;!ENTITY kappname "&amp;amor;"&gt;
&lt;!ENTITY package "tdetoys"&gt;
&lt;!ENTITY % addindex "IGNORE"&gt;
&lt;!ENTITY % English "INCLUDE"&gt;
]&gt;</markup></screen>
</example>
<note>
<para>
The entity <quote>English</quote> should be changed to reflect your
language, if you are either writing original documentation in another
language, or you are translating a document. For &tde; the original
documentation should always be in English, so you should not need to change
this when writing. For informational purposes, the currently supported
languages are:
</para>
<itemizedlist>
<listitem>
<para>
Afrikaans
</para>
</listitem>
<listitem>
<para>
British-English
</para>
</listitem>
<listitem>
<para>
Bulgarian
</para>
</listitem>
<listitem>
<para>
Catalan
</para>
</listitem>
<listitem>
<para>
Czech
</para>
</listitem>
<listitem>
<para>
Danish
</para>
</listitem>
<listitem>
<para>
German
</para>
</listitem>
<listitem>
<para>
Greek
</para>
</listitem>
<listitem>
<para>
English
</para>
</listitem>
<listitem>
<para>
Spanish
</para>
</listitem>
<listitem>
<para>
Estonian
</para>
</listitem>
<listitem>
<para>
Finnish
</para>
</listitem>
<listitem>
<para>
Faroese
</para>
</listitem>
<listitem>
<para>
French
</para>
</listitem>
<listitem>
<para>
Hebrew
</para>
</listitem>
<listitem>
<para>
Hungarian
</para>
</listitem>
<listitem>
<para>
Indonesian
</para>
</listitem>
<listitem>
<para>
Italian
</para>
</listitem>
<listitem>
<para>
Japanese
</para>
</listitem>
<listitem>
<para>
Dutch
</para>
</listitem>
<listitem>
<para>
Norwegian (Note, this is only for compatibility, either Norwegian-Bokmal or
Norwegian-Nynorsk should be used in preference.)
</para>
</listitem>
<listitem>
<para>
Norwegian-Bokmal
</para>
</listitem>
<listitem>
<para>
Norwegian-Nynorsk
</para>
</listitem>
<listitem>
<para>
Polish
</para>
</listitem>
<listitem>
<para>
Portuguese
</para>
</listitem>
<listitem>
<para>
Brasilian-Portuguese
</para>
</listitem>
<listitem>
<para>
Romanian
</para>
</listitem>
<listitem>
<para>
Russian
</para>
</listitem>
<listitem>
<para>
Slovak
</para>
</listitem>
<listitem>
<para>
Slovenian
</para>
</listitem>
<listitem>
<para>
Serbian
</para>
</listitem>
<listitem>
<para>
Swedish
</para>
</listitem>
<listitem>
<para>
Turkish
</para>
</listitem>
<listitem>
<para>
Ukrainian
</para>
</listitem>
<listitem>
<para>
Walloon
</para>
</listitem>
<listitem>
<para>
Xhosa
</para>
</listitem>
<listitem>
<para>
Continental-Chinese
</para>
</listitem>
<listitem>
<para>
Traditional-Chinese
</para>
</listitem>
</itemizedlist>
</note>
<sect1 id="book-and-bookinfo">
<title><sgmltag class="element">book</sgmltag> and the <sgmltag
class="element">bookinfo</sgmltag> section</title>
<para>
The <sgmltag class="element">bookinfo</sgmltag> section is most easily prepared
by copying the &tde; template.
</para>
<variablelist>
<varlistentry>
<term><sgmltag class="starttag">book lang="&amp;language"</sgmltag>
<anchor id="book"/>
</term>
<listitem>
<para>
Contains the entire document. Most important thing to remember is the <sgmltag
class="attribute">lang</sgmltag> attribute, which must contain exactly <sgmltag
class="attvalue">&amp;language;</sgmltag>, and must not be changed. To set the
language for the document, change the entity as described in the <link
linkend="prologue">prologue</link> section.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">bookinfo</sgmltag>
<anchor id="bookinfo"/>
</term>
<listitem>
<para>
Wraps the <quote>meta</quote> information &ndash; information about
the document, not about the application it is documenting. Required in
&tde; documentation. No attributes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">authorgroup</sgmltag>
<anchor id="authorgroup"/>
</term>
<listitem>
<para>
Wraps the author information, and may also contain <sgmltag
class="starttag">othercredit</sgmltag> information. Required in &tde;
documentation. No attributes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">author</sgmltag>
<anchor id="author"/>
</term>
<listitem>
<para>
Required element in the header section of all &tde; documentation. Use this
element <emphasis>only</emphasis> for the author(s) of the document. Other
contributers (developers, translators, and so on) should be credited in the
<link linkend="othercredit"><sgmltag
class="starttag">othercredit</sgmltag></link> section. No attributes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">personname</sgmltag><anchor id="personname"/></term>
<listitem>
<para>Used to wrap a person's name. You can use this directly in the
text as well, but here it should be used to contain each author or
contributor name.</para></listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">firstname</sgmltag><anchor id="firstname"/></term>
<listitem>
<para>
The contributor's first name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">othername</sgmltag><anchor
id="othername"/></term>
<listitem>
<para>
If the author normally uses more than a first and surname, you can add
further names here.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">surname</sgmltag><anchor
id="surname"/></term>
<listitem>
<para>
The author's surname.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">email</sgmltag></term>
<listitem>
<para>
An email address for the maintainer of the document is required for
&tde; documentation. You do not have to use your primary private
address, and you may be able to arrange for someone else (the
developer perhaps) to receive the email regarding the document. In
any case, there must be an address for users and translators to
contact regarding errors and document bugs.
</para>
<note><para>In previous versions of DocBook, <sgmltag
class="starttag">email</sgmltag> could not be used directly inside
<sgmltag class="starttag">author</sgmltag>. Since DocBook XML V 4.2
(used by &tde; for documents after &tde; 3.1.x), this is possible,
which simplifies this markup considerably.</para></note>
<para>
In other contexts in the document, <sgmltag
class="starttag">email</sgmltag> is used to contain any email address,
and is not used inside the <sgmltag class="element">address</sgmltag>
element.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">othercredit role=""</sgmltag>
<anchor id="othercredit"/></term>
<listitem>
<para>
Similary to <sgmltag class="element">author</sgmltag>, this is a wrapper around
information describing other contributors to the document. Include here the
contributor's name and email address as you do for the author. See the template
for more details.
</para>
<para>
The <sgmltag class="attribute">role</sgmltag> attribute is required, and can
contain any one of the following:
</para>
<itemizedlist>
<listitem>
<para>Translator</para>
</listitem>
<listitem>
<para>Developer</para>
</listitem>
<listitem>
<para>Reviewer</para>
</listitem>
<listitem>
<para>Graphist</para>
</listitem>
<listitem>
<para>Musician</para>
</listitem>
</itemizedlist>
<para>
The <sgmltag class="element">othercredit</sgmltag> element also includes the
<sgmltag class="element">contrib</sgmltag> element.
</para>
<variablelist>
<varlistentry>
<term><sgmltag class="starttag">contrib</sgmltag>
<anchor id="contrib"/></term>
<listitem>
<para>
The role this contributor played in the document or application preparation.
This could contain something like:
</para>
<itemizedlist>
<listitem>
<para>Developer</para>
</listitem>
<listitem>
<para><foreignphrase lang="de">Deutsche &Uuml;bersetzung</foreignphrase></para>
</listitem>
<listitem>
<para>Reviewer</para>
</listitem>
<listitem>
<para><foreignphrase lang="fr">Traduction fran&ccedil;aise</foreignphrase></para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">corpauthor</sgmltag>
<anchor id="corpauthor"/></term>
<listitem>
<para>
This is used in very specific circumstances, where an organization
(&eg; <quote>The TDE Team</quote>) is being credited with authorship of
a document. Authors writing about applications should not use this
and should credit themselves. If you do find a need to use this,
please be sure to include a maintainer's name and email address in the
credits chapter of the document.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">copyright</sgmltag>
<anchor id="copyright"/></term>
<listitem>
<para>
This is a wrapper for copyright information. <sgmltag
class="element">copyright</sgmltag> must contain these elements:
</para>
<variablelist>
<varlistentry>
<term><sgmltag class="starttag">year</sgmltag><anchor id="year"/></term>
<listitem>
<para>
Add one <sgmltag class="element">year</sgmltag> element for each year
in which the document was changed or added to. Don't put more than
one year in each tag, rather add more <sgmltag
class="element">year</sgmltag> elements, and use the 4 digit
<quote>YYYY</quote> format.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">holder</sgmltag><anchor id="holder"/></term>
<listitem>
<para>
The usual full name of the copyright holder(s). If there is more
than one copyright holder (the document was previously maintained by
another person, or is written collaboratively), then add more <sgmltag
class="element">copyright</sgmltag> sections, rather than trying to
fit multiple names in the one section.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Copyright is automatically held by the author of the document, but the
<sgmltag class="element">copyright</sgmltag> element is still required
for all &tde; documentation. None of the elements contained have any
attributes.
</para>
<para>Please do <emphasis>not</emphasis> add more names or years to
existing <sgmltag class="starttag">holder</sgmltag> or <sgmltag
class="starttag">year</sgmltag> elements. Add more, if they are
required, or have multiple <sgmltag
class="element">copyright</sgmltag> sections.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">legalnotice</sgmltag><anchor
id="legalnotice"/></term>
<listitem>
<para>
This contains, of course, a legal notice. This is absolutely required for any
&tde; document. In the context of this section, it should contain the
<sgmltag>&amp;FDLNotice;</sgmltag> entity, which inserts some information into
the document about the document's license (and <emphasis>not</emphasis> the
license of the application you are describing.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="date"><sgmltag class="starttag">date</sgmltag></term>
<listitem>
<para>
<emphasis>The date is very important.</emphasis> It is used not only by
scripts for automatic processing of documentation, but is also central
to revision control and co-ordination of translations. You must change
the date if you have changed the <emphasis>original</emphasis> document,
and you must <emphasis>not</emphasis> change the date if you are a
translator. The format of the date is very important. It
<emphasis>must</emphasis> be in the <acronym>ISO</acronym>, with
<quote>literal</quote> delimiters, in the form
<quote>yyyy-mm-dd</quote>. Please be extremely careful about this,
and triple check it before you send in the document.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="releaseinfo"><sgmltag class="starttag">releaseinfo</sgmltag></term>
<listitem>
<para>
This should match exactly the version of the
<emphasis>application</emphasis> you are documenting. It should
normally conform to the format X.x.xx (where X is a major version
number and x are minor version numbers, however, you no longer have to
pad the content to this length. That is to say, if the application has
released version <quote>1.4</quote>, you may write
<markup>&lt;releaseinfo&gt;1.4&lt;/releaseinfo&gt;</markup>, and you
do not need to make it
<markup>&lt;releaseinfo&gt;1.04.00&lt;/releaseinfo&gt;</markup></para>
<para>This is <emphasis>not</emphasis> the version of the document.
There are no attributes, and this element is required in &tde;
documentation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="abstract"><sgmltag class="starttag">abstract</sgmltag></term>
<listitem>
<para>
In &tde; Documentation, the abstract is required. It should be a short
one- or two-sentence summary of the document. The abstract is not the
place to put version or contact information, but it should say something
about the application and its purpose. For example <quote>KFoo is a
small fast network enabled foo generator, suitable for both beginner and
advanced foo users.</quote>.
</para>
<para>The abstract is your chance to sum up the application in a small
paragraph &mdash; in &khelpcenter; it shows up on the first page as
your document is selected, and the abstract frequently shows up in the
summary of your document in web searches. A short overview of the
application you are writing about is very valuable in this situation,
<quote>This is the KFoo handbook and describes KFoo 1.2.</quote> on
its own, is not.</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="keywordset"><sgmltag class="starttag">keywordset</sgmltag></term>
<listitem>
<para>
A wrapper for a set of keywords suitable for search engines. Required
for &tde; Documentation, and there are no attributes. The <sgmltag
class="element">keywordset</sgmltag> should contain several
<sgmltag class="starttag">keyword</sgmltag>s.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="keyword"><sgmltag class="starttag">keyword</sgmltag></term>
<listitem>
<para>
Add one <sgmltag class="starttag">keyword</sgmltag> inside the <sgmltag
class="starttag">keywordset</sgmltag> for each search term. You must
include at a minimum the terms <quote>TDE</quote>, the name of the
application you are documenting, and the name of the package it is found
in, for example <quote>tdegames</quote>. The keywords should be in
order from most general first (that is, <acronym>TDE</acronym>) through
less general, to the most specific. Add two or three more relevant words
that people might search with, &eg;, for the application &kwrite; you
might add <quote>editor</quote> and <quote>text</quote>. This is
required for &tde; Documentation, and there are no attributes.
</para></listitem>
</varlistentry>
<varlistentry>
<term id="translator-hooks"><markup>&lt;!-- TRANS:ROLES_OF_TRANSLATORS
--&gt;</markup></term>
<listitem>
<para>
This line is specific to &tde; documentation. Although it's a comment,
it is <emphasis>absolutely</emphasis> required in documents. It is
used by the translation system as a placeholder for the translation
teams to add their own role info. Translators should add more <sgmltag
class="element">othercredit</sgmltag> sections here as appropriate.
</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>The bookinfo section from the &tde; template</title>
<screen width="40"><markup>
&lt;bookinfo&gt;
&lt;title&gt;The &amp;kmyapplication; Handbook&lt;/title&gt;
&lt;authorgroup&gt;
&lt;author&gt;
&lt;!-- This is just put in as an example. For real documentation, please
define a general entity in entities/contributor.entities, e.g.
&lt;!ENTITY George.N.Ugnacious "&lt;personname&gt;&lt;firstname&gt;George&lt;/firstname&gt;&lt;othername&gt;N.&lt;/othername&gt;&lt;surname&gt;Ugnacious&lt;/surname&gt;&lt;/personname&gt;"&gt;
&lt;!ENTITY George.N.Ugnacious.mail "&lt;email&gt;gnu@tde.org&lt;/email&gt;"&gt;
and use `&amp;George.N.Ugnacious; &amp;George.N.Ugnacious.mail;' in the author element.
--&gt;
&lt;personname&gt;
&lt;firstname&gt;George&lt;/firstname&gt;
&lt;othername&gt;N.&lt;/othername&gt;
&lt;surname&gt;Ugnacious&lt;/surname&gt;
&lt;/personname&gt;
&lt;email&gt;gnu@tde.org&lt;/email&gt;
&lt;/author&gt;
&lt;/authorgroup&gt;
&lt;!-- TRANS:ROLES_OF_TRANSLATORS --&gt;
&lt;copyright&gt;
&lt;year&gt;2002&lt;/year&gt;
&lt;holder&gt;George N. Ugnacious&lt;/holder&gt;
&lt;/copyright&gt;
&lt;!-- Translators: put here the copyright notice of the translation --&gt;
&lt;!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
and in the FDL itself on how to use it. --&gt;
&lt;legalnotice&gt;&amp;FDLNotice;&lt;/legalnotice&gt;
&lt;!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (YYYY-MM-DD) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. --&gt;
&lt;date&gt;2003-01-10&lt;/date&gt;
&lt;releaseinfo&gt;1.1.&lt;/releaseinfo&gt;
&lt;!-- Abstract about this handbook --&gt;
&lt;abstract&gt;
&lt;para&gt;
&amp;kmyapplication; is an application specially designed to do nothing you would
ever want.
&lt;/para&gt;
&lt;/abstract&gt;
&lt;!-- This is a set of Keywords for indexing by search engines.
Please at least include TDE, the TDE package it is in, the name
of your application, and a few relevant keywords. --&gt;
&lt;keywordset&gt;
&lt;keyword&gt;TDE&lt;/keyword&gt;
&lt;keyword&gt;tdeutils&lt;/keyword&gt;
&lt;keyword&gt;Kapp&lt;/keyword&gt;
&lt;keyword&gt;nothing&lt;/keyword&gt;
&lt;keyword&gt;nothing else&lt;/keyword&gt;
&lt;/keywordset&gt;
&lt;/bookinfo&gt;
</markup></screen>
</example>
</sect1>
</chapter>
<chapter id="section-tags">
<title>Chapters and Sections</title>
<variablelist>
<varlistentry>
<term id="chapter"><sgmltag class="starttag">chapter
id=""</sgmltag></term>
<listitem>
<para>
Use chapters to break up the document into smaller chunks. A chapter
break should occur when a major subject change happens. Use sections
within the chapter when the subject changes, but you are still
discussing a particular aspect of a larger subject.
</para>
<para>
For example, going from discussing how to use the application, to how to
configure the application would be worthy of a new chapter. Moving from
discussing how to specifically configure the application on SuSE, to how
to specifically configure the application on &RedHat;, would be a new
section in a larger <quote>Configuration</quote> chapter.
</para>
<para>
Chapters must have an <sgmltag class="attribute">id</sgmltag>. This is
the only attribute used in &tde; documentation. For &tde; Documents,
this id must be in lower case, and with a hyphen (-) to separate words.
Please don't use spaces, underscores, or run the words together. For
<acronym>HTML</acronym> generation, the chapter id and most <sgmltag
class="starttag">sect1</sgmltag> id's are used to name the separate
<abbrev>HTML</abbrev> pages, so take care to make them sensible and
descriptive. For translators, these id's should be translated, but you
will need to take care to also translate references to the id's in
<sgmltag class="starttag">link</sgmltag> and <sgmltag
class="starttag">xref</sgmltag> elements in other parts of the document.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="title">
<sgmltag class="starttag">title</sgmltag></term>
<listitem>
<para>
Titles are used in many places, but the most common is the Chapter and
Section headings. Make sure to use sensible titles, as these will also
be that chapter's (or section's) entry in the table of contents, so people
will rely on these to find the part of the document they are interested
in.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="sect1"><sgmltag class="starttag">sect1 id=""</sgmltag>,
<sgmltag class="starttag">sect2</sgmltag>, <sgmltag
class="starttag">sect3</sgmltag>, <sgmltag
class="starttag">sect4</sgmltag>, <sgmltag
class="starttag">sect5</sgmltag></term>
<listitem>
<anchor id="sect2"/><anchor id="sect3"/><anchor id="sect4"/><anchor
id="sect5"/>
<para>
Use sections to break chapters up into smaller pieces. Use similar
criteria on where to divide them as you would for chapters.
</para>
<para>
Sections require a <sgmltag class="starttag">title</sgmltag>. Sections
are nested according to the number - a <sgmltag
class="starttag">sect2</sgmltag> can contain any number of <sgmltag
class="starttag">sect3</sgmltag>, which can contain <sgmltag
class="starttag">sect4</sgmltag>, but a <sgmltag
class="starttag">sect2</sgmltag> can't directly contain a <sgmltag
class="starttag">sect4</sgmltag>.
</para>
<para>
<sgmltag class="starttag">sect1</sgmltag> requires an id attribute, and
you can use id's on the other section tags if you want to later link
directly to them from other parts of the document. <sgmltag
class="attribute">id</sgmltag> is the only attribute used in &tde;
Documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="sect1info"><sgmltag class="starttag">sect1info</sgmltag>,
<sgmltag class="starttag">sect2info</sgmltag>, <sgmltag
class="starttag">sect3info</sgmltag>, <sgmltag
class="starttag">sect4info</sgmltag>, <sgmltag
class="starttag">sect5info</sgmltag></term> <listitem><anchor
id="sect2info"/><anchor id="sect3info"/><anchor id="sect4info"/><anchor
id="sect5info"/>
<para>
The section info elements are rarely used in &tde; Documentation.
They are appropriate for documents where some smaller sections are
contributed by third parties, or where the document covers multiple
applications. The contents are more or less the same as those of the
<sgmltag class="starttag">bookinfo</sgmltag> section, although they
tend to be briefer.</para>
<para>Please ensure if you use these elements that you add the
translation placeholder comments as you do in the prolog.</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="appendix">
<sgmltag class="starttag">appendix</sgmltag></term>
<listitem>
<para>
The standard installation instructions for all applications are
contained in an <sgmltag class="starttag">appendix</sgmltag>, and are
normally required for &tde; documents. Although the installation
instructions as found in the template are reasonably complete, and
need no customization for most applications, authors are very strongly
encouraged to expand on them. For example, links to web pages, where
to find libraries, plugins, screenshots of the application in a
particular configuration, or any other information you can think of.
</para>
<para>If the application is only distributed with &tde;, there is
little use in repeating the same installation instructions for every
manual. You may leave it out entirely, unless you have further
information to add.</para>
<para>
For other purposes, appendices are used infrequently in &tde;
Documentation. An appendix can be found, for example, in the &kppp;
document, containing such things as Hayes Modem commands. Only use an
appendix if you think it's very necessary. In most cases, the
information it would contain would be better moved to the main document.
In the example of &kppp;, this information is vital to a few people, but
extremely uninteresting to the majority, so it was placed in an
appendix.
</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter id="links">
<title>The linking elements</title>
<variablelist>
<varlistentry>
<term id="link"><sgmltag class="starttag">link
linkend=""</sgmltag></term>
<listitem>
<para>
The most common link. Use this to turn a word or phrase into a link to
another part of the document. <sgmltag
class="attribute">linkend</sgmltag> is the only attribute we use.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="ulink"><sgmltag class="starttag">ulink url=""</sgmltag></term>
<listitem>
<para>A link that refers to a document using it's
<acronym>URI</acronym>. Use this for websites and ftp sites, but not
for <link linkend="email">email addresses</link>, which have their own
specific tag. Please do <emphasis>not</emphasis> use this to link to
other documents on the local system.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="anchor">
<sgmltag class="starttag">anchor id=""/</sgmltag></term>
<listitem>
<para>
Marks a place in the document, which you can use to link to. Note that
the <sgmltag class="attribute">id</sgmltag> attribute on any other
element where it is valid, will automatically generate an
<acronym>HTML</acronym> anchor in generated <acronym>HTML</acronym>, so
you do not need to duplicate these. Use anchors only when you need to
jump into the middle of a longer page, for example, to a particular menu
item, or to a particular option in a preference dialog.
</para>
<note>
<para>
<sgmltag class="emptytag">anchor</sgmltag> is an empty element, and must
be closed with a /.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term id="xref"><sgmltag class="emptytag">xref
linkend=""</sgmltag></term>
<listitem>
<para>
A cross reference to another part of the document. Use this when you
want to refer to the section without the name. This is one of very few
unclosed elements allowed. <sgmltag class="attribute">linkend</sgmltag>
is the only attribute we currently use.
</para>
<note>
<para>
<sgmltag class="emptytag">xref</sgmltag> is an empty element, and must
be closed with a /.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term id="email">
<sgmltag class="starttag">email</sgmltag></term>
<listitem>
<para>
Use this to enclose an email address. Don't add <quote>mailto:</quote>
to the email address, and don't use <sgmltag class="starttag">ulink
url=""</sgmltag> for email addresses. No attributes required.
</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter id="lists">
<title>Lists</title>
<variablelist>
<varlistentry>
<term id="listitem"><sgmltag class="starttag">listitem</sgmltag></term>
<listitem>
<para>
<sgmltag class="starttag">listitem</sgmltag> is the main building block
of almost all the lists. It should always contain some other markup,
usually a <sgmltag class="starttag">para</sgmltag>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="orderedlist"><sgmltag
class="starttag">orderedlist</sgmltag></term>
<listitem>
<para>
Use this type of list when the order of the items matters, but they are
not a set of steps that are carried out to achieve something. A good
example is a list of things in order of importance.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="itemizedlist"><sgmltag
class="starttag">itemizedlist</sgmltag></term>
<listitem>
<para>
Use an itemized list when the order of the items is not
important.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="variablelist"><sgmltag
class="starttag">variablelist</sgmltag></term>
<listitem>
<para>
A list that has two sections for each entry. Examples: A menu item, and
what the menu item does, An action, and its result, or a term and its
definition. This is a very common type of list. (Almost this entire
document is composed of variable lists.)
</para>
<para>
<sgmltag class="starttag">variablelist</sgmltag> contains the following
elements:
</para>
<variablelist>
<varlistentry>
<term id="varlistentry"><sgmltag
class="starttag">varlistentry</sgmltag></term>
<listitem>
<para>
A <sgmltag class="starttag">varlistentry</sgmltag> is a wrapper around
each pair in the variable list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="term"><sgmltag class="starttag">term</sgmltag></term>
<listitem>
<para>
To reuse the above examples, the <sgmltag
class="starttag">term</sgmltag> for each pair would be the menu item you
are describing, the action, or the term you are defining. You can use
the <sgmltag class="attribute">id</sgmltag> attribute for this element,
which is quite convenient in long lists such as a menu reference,
enabling you to link directly to a particular menu item from another
part of the document.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag class="starttag">listitem</sgmltag></term>
<listitem>
<para>
As described above the <sgmltag class="starttag">listitem</sgmltag> is
used inside a <sgmltag class="starttag">varlistentry</sgmltag> to hold
the second part of the pair: The result of choosing that menu item, for
example, the consequences of an action, or the definition of the term.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term id="procedure"><sgmltag
class="starttag">procedure</sgmltag></term>
<listitem>
<para>
Use a procedure list when you are listing a sequence of steps which are
performed in a particular order.
</para>
<para>
A procedure contains only one tag:
</para>
<variablelist>
<varlistentry><term id="step"><sgmltag
class="starttag">step</sgmltag></term>
<listitem>
<para>
A step is one of the sequence of events that make up a
procedure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="substeps"><sgmltag class="starttag">substeps</sgmltag></term>
<listitem>
<para>A step can contain substeps</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term id="simplelist"><sgmltag
class="starttag">simplelist</sgmltag></term>
<listitem>
<para>
A simple list is just that - a simple list, with no formatting
required. A simple list can contain only one type of element:
</para>
<variablelist>
<varlistentry><term id="member"><sgmltag
class="starttag">member</sgmltag></term>
<listitem>
<para>
Members of a simple list.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term id="segmentedlist">
<sgmltag class="starttag">segmentedlist</sgmltag></term>
<listitem>
<para>
A Segmented list is a very particular type of list. Use
sparingly, as it's very difficult to get these right, and most content
appropriate for a segmented list could just as well fit the table model.
</para>
<example>
<title>A Segmented List</title>
<screen><markup>
&lt;segmentedlist&gt;
&lt;segtitle&gt;Name&lt;/segtitle&gt;
&lt;segtitle&gt;Occupation&lt;/segtitle&gt;
&lt;segtitle&gt;Favorite Food&lt;/segtitle&gt;
&lt;seglistitem&gt;
&lt;seg&gt;Tux&lt;/seg&gt;
&lt;seg&gt;Linux Mascot&lt;/seg&gt;
&lt;seg&gt;Herring&lt;/seg&gt;
&lt;/seglistitem&gt;
&lt;seglistitem&gt;
&lt;seg&gt;Konqui&lt;/seg&gt;
&lt;seg&gt;The TDE Dragon&lt;/seg&gt;
&lt;seg&gt;Gnomes&lt;/seg&gt;
&lt;/seglistitem&gt;
&lt;/segmentedlist&gt;</markup></screen>
<segmentedlist><segtitle>Name</segtitle>
<segtitle>Occupation</segtitle>
<segtitle>Favorite Food</segtitle>
<seglistitem><seg>Tux</seg>
<seg>Linux Mascot</seg>
<seg>Herring</seg></seglistitem>
<seglistitem><seg>Konqui</seg>
<seg>The TDE Dragon</seg>
<seg>Gnomes</seg></seglistitem></segmentedlist>
</example>
<para>The segmented list contains the following elements:</para>
<variablelist>
<varlistentry>
<term id="segtitle"><sgmltag class="starttag">segtitle</sgmltag></term>
<listitem>
<para>
The title each segment will have
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="seglistitem"><sgmltag
class="starttag">seglistitem</sgmltag></term>
<listitem>
<para>
A set of entries in the list
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="seg"><sgmltag class="starttag">seg</sgmltag></term>
<listitem>
<para>
The contents of the entries in the list. In each
<sgmltag class="starttag">seglistitem</sgmltag> there is one
<sgmltag class="starttag">seg</sgmltag> for each
<sgmltag class="starttag">segtitle</sgmltag>.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter id="tables">
<title>Tables</title>
<variablelist>
<varlistentry>
<term id="informaltable"><sgmltag
class="starttag">informaltable</sgmltag></term>
<listitem>
<para>
This is the table type used most in &tde; Documentation. Please be very
sure that what you are marking up as a table, is actually tabular data,
as in many cases a <sgmltag class="starttag">variablelist</sgmltag> is
more appropriate. Please do not use any of the presentation attributes
to make tables <quote>look nice</quote>. The only attribute currently
allowed in &tde; Documents is <sgmltag class="attribute">pgwide</sgmltag>.
</para>
<para>
An <sgmltag class="starttag">informaltable</sgmltag> must contain a
<sgmltag class="starttag">tgroup cols=""</sgmltag> entry. Informal
tables have no specific title, if you wish the table to be titled and to
have an entry in the table of contents, you should use <link
linkend="table"><sgmltag class="starttag">table</sgmltag></link>. Do
not use any attributes other than <sgmltag
class="attribute">pgwide</sgmltag> on tables or informal tables for
&tde; documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="table"><sgmltag class="starttag">table</sgmltag></term>
<listitem>
<para>
A formal table with a title. Tables will have their own separate entry
in the table of contents. Other than the addition of a title, they are
marked up the same as an <sgmltag
class="starttag">informaltable</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="tgroup"><sgmltag class="starttag">tgroup
cols=""</sgmltag></term>
<listitem>
<para>
A <sgmltag class="starttag">tgroup</sgmltag> is a required element in a
table. The <sgmltag class="attribute">cols</sgmltag> attribute is
required, and should be completed with the number of columns the table
is to hold. No other attributes used in &tde; Documentation.
</para>
<para>
A <sgmltag class="element">tgroup</sgmltag> must contain a <sgmltag
class="element">tbody</sgmltag>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="tbody"><sgmltag class="starttag">tbody</sgmltag></term>
<listitem>
<para>
A <sgmltag class="element">tbody</sgmltag> is a required element in a
table. There are no attributes. The <sgmltag
class="element">tbody</sgmltag> contains rows.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="row"><sgmltag class="starttag">row</sgmltag></term>
<listitem>
<para>
A <sgmltag class="element">row</sgmltag> corresponds directly with the
rows of the table. Rows contain <sgmltag
class="starttag">entry</sgmltag> tags, one for each column in the table,
as specified by the <sgmltag class="attribute">cols</sgmltag> attribute
on the <link linkend="tgroup"><sgmltag
class="starttag">tgroup</sgmltag></link> tag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="entry"><sgmltag class="starttag">entry</sgmltag></term>
<listitem>
<para>
The entry is the basic building block of a table. Each entry corresponds
to one <quote>data cell</quote> in the table. There must be as many
<sgmltag class="starttag">entry</sgmltag> tags in each row as the
<sgmltag class="attribute">cols</sgmltag> attribute on the <link
linkend="tgroup"><sgmltag class="starttag">tgroup</sgmltag></link> tag.
There are no attributes used in &tde; Documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="thead"><sgmltag class="starttag">thead</sgmltag></term>
<listitem>
<para>
<sgmltag class="starttag">thead</sgmltag> can be used to create a
heading row for the table. It must appear before the <sgmltag
class="element">tbody</sgmltag> element, and should normally contain one
<sgmltag class="element">row</sgmltag> and as many <sgmltag
class="element">entry</sgmltag> elements as the rest of the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="tfoot"><sgmltag class="starttag">tfoot</sgmltag></term>
<listitem>
<para><sgmltag class="starttag">tfoot</sgmltag> is not currently used in
&tde; Documentation. If you want to use it, please see the Duck book
for information.
</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>An <sgmltag class="starttag">informaltable</sgmltag>
template</title>
<screen width="40">
<markup>
&lt;informaltable&gt;
&lt;tgroup cols="2"&gt;
&lt;tbody&gt;
&lt;row&gt;
&lt;entry&gt;&lt;/entry&gt;
&lt;entry&gt;&lt;/entry&gt;
&lt;/row&gt;
&lt;/tbody&gt;
&lt;/tgroup&gt;
&lt;/informaltable&gt;
</markup>
</screen>
</example>
<example>
<title>A <sgmltag class="starttag">table</sgmltag> template</title>
<screen width="40">
<markup>
&lt;table&gt;
&lt;title&gt;&lt;/title&gt;
&lt;tgroup cols="2"&gt;
&lt;tbody&gt;
&lt;row&gt;
&lt;entry&gt;&lt;/entry&gt;
&lt;entry&gt;&lt;/entry&gt;
&lt;/row&gt;
&lt;/tbody&gt;
&lt;/tgroup&gt;
&lt;/table&gt;
</markup>
</screen>
</example>
</chapter>
<chapter id="gui">
<title>The &GUI; elements, menus, toolbars and
shortcuts.</title>
<variablelist>
<varlistentry>
<term id="action"><sgmltag class="starttag">action</sgmltag></term>
<listitem>
<para>
The result of a user action. This does not need to be a complete
sentence, or even more than a single word. For example, <quote>This
button &lt;action&gt;closes the dialog&lt;/action&gt;.</quote> The main
place you will find this in &tde; Documentation is in the Menu and
Command reference chapters of the manuals.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="guibutton"><sgmltag
class="starttag">guibutton</sgmltag></term>
<listitem>
<para>
The text on a button that you click on. Icons, Radio buttons and check
boxes are not considered buttons in this sense.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="guiicon"><sgmltag class="starttag">guiicon</sgmltag></term>
<listitem>
<para>
The name or description of an icon.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="guilabel"><sgmltag class="starttag">guilabel</sgmltag></term>
<listitem>
<para>
The text of anything that is labelled on screen, and isn't a button,
icon, menu, or menu item. For example, the name of a dialog box, the
name of a tab in that dialog box, and the name of a label by a checkbox.
</para>
<para>Take care that the text exactly matches the label on screen. If
it has a <literal>:</literal> on the dialog box, put the
<literal>:</literal> into your documentation. Match the
capitalization. There is a script in the tde-i18n module called
<filename>check-gui-texts</filename> which you can use to help check
that your text matches exactly what is in the application. During
translation, the translators can use this script to generate
translations from their translations of the &GUI; itself, but this
will only work if the English text matches precisely.</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="guimenu"><sgmltag class="starttag">guimenu</sgmltag></term>
<listitem>
<para>
The top level name of a menu (that is, the name you can see on the menu
bar when the menu isn't open).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="guimenuitem"><sgmltag
class="starttag">guimenuitem</sgmltag></term>
<listitem>
<para>
The final item you select on the menu, that actually performs an action.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="guisubmenu"><sgmltag
class="starttag">guisubmenu</sgmltag></term>
<listitem>
<para>
A submenu. That is, a menu which has items both above and below it in
the hierarchy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="keycap"><sgmltag class="starttag">keycap</sgmltag></term>
<listitem>
<para>
A keycap is a key as it is labelled on your keyboard.
<keycap>Home</keycap> is a keycap on a standard English keyboard.
<keycap>Alt Gr</keycap> is a standard key on many European keyboards.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="keycode"><sgmltag class="starttag">keycode</sgmltag></term>
<listitem>
<para>
The internal identifier for a key on the keyboard. Used very
infrequently, but you may find need for it, for example when describing
entries in rc files.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="keysym"><sgmltag class="starttag">keysym</sgmltag></term>
<listitem>
<para>
Right arrow is the <sgmltag class="starttag">keysym</sgmltag> for the
<sgmltag class="starttag">keycap</sgmltag> that looks like
<keycap>-></keycap>. Please note this is a &tde; specific use of
<sgmltag class="starttag">keysym</sgmltag>, and does not precisely
follow the examples in the Duck Book.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="menuchoice"><sgmltag
class="starttag">menuchoice</sgmltag></term>
<listitem>
<para>
A menuchoice describes a menu entry. You should use <sgmltag
class="starttag">menuchoice</sgmltag> anywhere you are describing how
to reach a menu item. In normal text, there are no particular
requirements. In a menu reference, the <sgmltag
class="starttag">menuchoice</sgmltag> should also contain a <sgmltag
class="starttag">shortcut</sgmltag> element describing the keyboard
shortcut, and the contents should also be marked up with <sgmltag
class="starttag">accel</sgmltag> as appropriate.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="shortcut"><sgmltag class="starttag">shortcut</sgmltag></term>
<listitem>
<para>
A key combination that is a shortcut for a menu item. This is
<emphasis>only</emphasis> used inside <sgmltag
class="starttag">menuchoice</sgmltag> and contains <sgmltag
class="starttag">keycombo</sgmltag> or <sgmltag
class="starttag">keycap</sgmltag> that is defined as the keyboard
shortcut in the menu. In the markup, it appears before the actual menu
entries inside the <sgmltag class="starttag">menuchoice</sgmltag> You do
not need to describe the shortcut every time the menu item is mentioned
in the text, although it may be appropriate to do so on some occasions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="mousebutton"><sgmltag
class="starttag">mousebutton</sgmltag></term>
<listitem>
<para>
The normal name of a mouse button. It will be normally be one
of:</para>
<itemizedlist>
<listitem>
<para><markup>&lt;mousebutton&gt;left&lt;/mousebutton&gt;</markup> or
the entity <sgmltag class="genentity">LMB</sgmltag>
</para>
</listitem>
<listitem>
<para><markup>&lt;mousebutton&gt;middle&lt;/mousebutton&gt;</markup> or
the entity <sgmltag class="genentity">MMB</sgmltag>
</para>
</listitem>
<listitem>
<para><markup>&lt;mousebutton&gt;right&lt;/mousebutton&gt;</markup> or
the entity <sgmltag class="genentity">RMB</sgmltag>.
</para>
</listitem>
<listitem>
<para><markup>&lt;mousebutton&gt;wheel&lt;/mousebutton&gt;</markup>
</para>
</listitem>
</itemizedlist>
<para>Wheel is used only in specific instructions for applications that
support it, of course.</para>
<para>
Use the entities where possible, they are a lot less typing and
are simple to remember (which is why we have provided them.) If you are
translating, check with your team leader, as the entities above are
<emphasis>not</emphasis> translated, but you may have your own language
specific ones to use in their place.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="keycombo"><sgmltag class="starttag">keycombo
action=""</sgmltag></term>
<listitem>
<para>
A keycombo is a sequence or combination of keypresses that are performed
together. A keycombo can contain <sgmltag
class="starttag">keycap</sgmltag>, <sgmltag class="starttag">keysym</sgmltag> or <sgmltag class="starttag">mousebutton</sgmltag>, or
any combination of these, in any order.</para> <para>It is normal to
have them in the order <literal>modifier</literal>,
<literal>Alpha-numeric</literal>, <literal>Mouse</literal>. That is,
<keycombo>&Ctrl;<keycap>A</keycap></keycombo>, not
<keycombo><keycap>A</keycap>&Ctrl;</keycombo>, unless pressing
<keycap>A</keycap> then &Ctrl; actually is the shortcut.
</para>
<para>
Keycombo requires an <sgmltag class="attribute">action</sgmltag>
attribute, describing exactly how the keys (or mouse buttons) are
combined. The choices are:
</para>
<itemizedlist>
<listitem>
<para>
<sgmltag class="attvalue">Click</sgmltag>
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">Double-Click</sgmltag>
</para>
</listitem>
<listitem>
<para><sgmltag class="attvalue">Other</sgmltag>
</para>
</listitem>
<listitem>
<para><sgmltag class="attvalue">Press</sgmltag>
</para>
</listitem>
<listitem>
<para><sgmltag class="attvalue">Seq</sgmltag>
</para>
</listitem>
<listitem>
<para><sgmltag class="attvalue">Simul</sgmltag>
</para>
</listitem>
</itemizedlist>
<para>
You will most likely need to use <sgmltag class="attvalue">Seq</sgmltag>
(for a sequence of keys that are pressed one after the other), or
<sgmltag class="attvalue">Simul</sgmltag> for a combination of keys that
are pressed at the same time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="accel"><sgmltag class="starttag">accel</sgmltag></term>
<listitem>
<para>
The accelerator key that can be used to access a <acronym>GUI</acronym>
menu without a mouse. This is indicated in the menu by an underlined
letter. Although we previously used this in the menu references, we
have since decided not to, the maintenance is too high, and it causes
an enormous amount of work during translation.
</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>An example from a menu reference entry</title>
<screen width="40">
<markup>
&lt;varlistentry&gt;
&lt;term&gt;&lt;menuchoice&gt;
&lt;shortcut&gt;
&lt;keycombo action="simul"&gt;&amp;Ctrl;
&lt;keycap&gt;C&lt;/keycap&gt;&lt;/keycombo&gt;
&lt;/shortcut&gt;
&lt;guimenu&gt;Edit&lt;/guimenu&gt;
&lt;guimenuitem&gt;Copy&lt;/guimenuitem&gt;
&lt;/menuchoice&gt;&lt;/term&gt;
&lt;listitem&gt;&lt;para&gt;&lt;action&gt;Copy the selected text&lt;/action&gt; to the
clipboard&lt;/para&gt;&lt;/listitem&gt;
&lt;/varlistentry&gt;
&lt;varlistentry&gt;
&lt;term&gt;&lt;menuchoice&gt;
&lt;shortcut&gt;&lt;keycombo action="simul"&gt;&amp;Ctrl;
&lt;keycap&gt;V&lt;/keycap&gt;
&lt;/keycombo&gt;&lt;/shortcut&gt;
&lt;guimenu&gt;Edit&lt;/guimenu&gt;
&lt;guimenuitem&gt;Paste&lt;/guimenuitem&gt;
&lt;/menuchoice&gt;&lt;/term&gt;
&lt;listitem&gt;&lt;para&gt;&lt;action&gt;Paste&lt;/action&gt; the contents of
the clipboard at the cursor.&lt;/para&gt;&lt;/listitem&gt;
&lt;/varlistentry&gt;
</markup>
</screen>
<para>
Please note, this is very complicated markup, and until you have
written a few it's very hard to follow, but it does get much easier with
practise! Although indenting is discouraged in general, this is one
place where you might want to use some indenting and white space to make
it clearer while writing, at least when you are beginning. There are
also no rules as to when you must start a new line for a new element, so
format the markup to suit your own taste while you are writing, if that
makes it easier for you to follow.
</para>
</example>
</chapter>
<chapter id="actions-and-commands">
<title>Describing actions and commands</title>
<variablelist>
<varlistentry>
<term id="replaceable"><sgmltag
class="starttag">replaceable</sgmltag></term>
<listitem>
<para>
Use this for placeholder or sample text, that a user would not
actually type, but would instead replace with the correct text for
their environment. For example, <markup>Edit the file
&lt;filename&gt;&lt;replaceable&gt;/usr/local/foo/bar&lt;/replaceable&gt;&lt;/filename&gt;</markup>,
because it may already be established that <filename
class="directory">/usr/local</filename> is only the default location
of this file, and the user may have it installed to &eg; <filename
class="directory">/opt/</filename> instead.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="application"><sgmltag
class="starttag">application</sgmltag></term>
<listitem>
<para>
Use this to mark up the name of any software program mentioned in the
text. Don't use this to mark up the actual command issued to execute
the application. For example, <sgmltag
class="starttag">application&gt;Kate&lt;/application</sgmltag> is the
name of the editor, but <sgmltag
class="starttag">command&gt;kate&lt;/command</sgmltag> is the name of
the command that starts the <application>Kate</application>
application.</para>
<note>
<para>
All &tde; applications, and several non-&tde; but very common
applications, are provided as entities.
</para>
</note>
<para>
For the &tde; applications, using the entities will save you much
typing, and will ensure that applications are always referred to with
their correct name across all documentation. The entity is always the
application's executable name, in lower case, &eg; <sgmltag
class="genentity">kcontrol</sgmltag>, <sgmltag
class="genentity">konqueror</sgmltag> or <sgmltag
class="genentity">kmail</sgmltag>.
</para>
<para>
For non-&tde; applications, one of the major reasons to use the entities
is that there are legal implications, so far as we are required to
acknowledge trademarks and copyrights held by others outside our
organisation. You will find in <xref linkend="appendix-entities"/> a
list containing a list of the more common non-&tde; application
entities.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="interface"><sgmltag
class="starttag">interface</sgmltag></term>
<listitem>
<para>
Catch all element for gui interface items that do not have a more
specific tag. You can use this to markup things like the <quote>View
pane</quote> in &khelpcenter;, or the <quote>Board</quote> in
&kjumpingcube;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="userinput"><sgmltag
class="starttag">userinput</sgmltag></term>
<listitem>
<para>
<emphasis>Any</emphasis> text that the user must type, including
commands and data entry.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="screen"><sgmltag class="starttag">screen</sgmltag></term>
<listitem>
<para>
Used to represent the computer screen (usually to represent a terminal
or console.) Text contained in <sgmltag
class="starttag">screen</sgmltag> is considered to be literal text &mdash;
line breaks and white space are honored and it will be rendered with a
mono-spaced font. Don't use screen when what you really want is an
example, or an informal example.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="command"><sgmltag class="starttag">command</sgmltag></term>
<listitem>
<para>
Text the user enters to instruct the computer or an application
to do something. <userinput><command>ls
<option>-al</option></command></userinput> is a command (it's also userinput,
and has options.) <userinput><command>/join #tde</command></userinput>
in an <acronym>irc</acronym> client is a command (and again, is
userinput.)
</para>
<para>
Commands are not <sgmltag class="element">userinput</sgmltag> when you
are not expecting the user to actually type them, for example in the
sentence <quote>The output from the <command>ls</command> command should
show you...</quote>, the text <quote>ls</quote> is a command, but is not
<sgmltag class="element">userinput</sgmltag> in this context.
</para>
<para>
Applications not marked up with the <sgmltag
class="starttag">application</sgmltag> tag are also considered commands,
for example, <command>gcc</command>, <command>automake</command> and
<command>autoconf</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="prompt"><sgmltag class="starttag">prompt</sgmltag></term>
<listitem>
<para>
The prompt at which a user types input. For most &tde;
Documentation, this has been standardised as
<sgmltag
class="starttag">prompt</sgmltag><sgmltag class="genentity">percnt</sgmltag><sgmltag
class="endtag">prompt</sgmltag> (which is the &percnt; character).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="option"><sgmltag class="starttag">option</sgmltag></term>
<listitem>
<para>An optional parameter to a command. Since we write about &UNIX;
platforms, an option on the commandline is almost always indicated by a
<quote>-</quote>, but there are exceptions (&eg;,
<userinput><command>tar</command> <option>zxvf</option>
<replaceable>filename.tar.gz</replaceable></userinput> or
<userinput><command>ps</command> <option>ax</option></userinput>, which
are marked up as
<markup>&lt;userinput&gt;&lt;command&gt;tar&lt;/command&gt;
&lt;option&gt;zxvf&lt;/option&gt;
&lt;replaceable&gt;filename.tar.gz&lt;/replaceable&gt;&lt;/userinput&gt;</markup>
and <markup>&lt;userinput&gt;&lt;command&gt;ps&lt;/command&gt;
&lt;option&gt;ax&lt;/option&gt;&lt;/userinput&gt;</markup> respectively.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="envar"><sgmltag class="starttag">envar</sgmltag></term>
<listitem>
<para>
An environment variable. Note that the variable indicator (usually $
for &UNIX;) is not part of the name of the environment variable, so it
is correct to do this:
<markup>$&lt;envar&gt;TDEDIR&lt;/envar&gt;</markup>. There are no
attributes in use in &tde; Documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="errorcode"><sgmltag class="starttag">errorcode</sgmltag></term>
<listitem>
<para>
A (usually numeric, but not always) error
code. <errorcode>SIGSEGV</errorcode> is an errorcode, as is
<errorcode>404</errorcode> as you might receive when you are web
browsing.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="errorname"><sgmltag class="starttag">errorname</sgmltag></term>
<listitem>
<para>
The actual text of an error message - to reuse the
<errorcode>404</errorcode> example, the <sgmltag
class="starttag">errorname</sgmltag> might be <errorname>Page not
found</errorname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="errortype"><sgmltag class="starttag">errortype</sgmltag></term>
<listitem>
<para>
The type of error, &eg; <errortype>fatal</errortype>
or <errortype>recoverable</errortype>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="filename"><sgmltag class="starttag">filename</sgmltag></term>
<listitem>
<para>
Use <sgmltag class="starttag">filename</sgmltag> for all occurrences of
file names including:
</para>
<itemizedlist>
<listitem>
<para>
Directory names &mdash; with the attribute <markup>class="directory"</markup>
</para>
</listitem>
<listitem>
<para>
Paths
</para>
</listitem>
<listitem>
<para>
File names
</para>
</listitem>
<listitem>
<para>
File name placeholders (which should also be tagged with
<sgmltag class="starttag">replaceable</sgmltag>
</para>
</listitem>
</itemizedlist>
<para>
Do not use <sgmltag class="starttag">filename</sgmltag> for file
fragments or extensions (&ie; <literal role="extension">*.tgz</literal>
which should instead be marked up as <link linkend="literal"><sgmltag
class="starttag">literal role="extension"</sgmltag></link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="symbol"><sgmltag class="starttag">symbol</sgmltag></term>
<listitem>
<para>
Symbols are things that are replaced by the computer when they are
processed. It's difficult to say when things are a symbol and when they
are not - if there is a more specific element to use (&eg; <sgmltag
class="starttag">envar</sgmltag> or <sgmltag
class="starttag">constant</sgmltag> then you should use that instead.
</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter id="questions-and-answers">
<title>Questions and Answers</title>
<variablelist>
<varlistentry>
<term id="qandaset"><sgmltag class="starttag">qandaset</sgmltag></term>
<listitem>
<para>
A set of questions and answers, suitable for a
&FAQ;. <sgmltag class="starttag">qandaset</sgmltag> must
contain <sgmltag class="starttag">qandaentry</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="qandaentry"><sgmltag class="starttag">qandaentry</sgmltag></term>
<listitem>
<para>
Each question and answer pair is a <sgmltag
class="starttag">qandaentry</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="question"><sgmltag class="starttag">question</sgmltag></term>
<listitem>
<para>
The question being asked. It must be inside a qandaentry, and
it must have a matching answer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="answer"><sgmltag class="starttag">answer</sgmltag></term>
<listitem>
<para>
The answer to the matching question in the same qandaset.
</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title><sgmltag class="starttag">qandaset</sgmltag> Template</title>
<screen width="40"><markup>
&lt;qandaset&gt;
&lt;qandaentry&gt;
&lt;question&gt;
&lt;/question&gt;
&lt;answer&gt;
&lt;/answer&gt;
&lt;/qandaentry&gt;
&lt;/qandaset&gt;
</markup></screen>
</example>
</chapter>
<chapter id="screenshots-and-examples">
<title>Images and Examples</title>
<variablelist>
<varlistentry>
<term id="screenshot"><sgmltag class="starttag">screenshot</sgmltag></term>
<listitem>
<para>
Wrapper around screenshots. Use this when you are including a
screenshot in your document.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="screeninfo">
<sgmltag class="starttag">screeninfo</sgmltag></term>
<listitem>
<para>
Screeninfo is a description of the screenshot. It's common (but not
required) to reuse this text in the textobject element, as it saves
translation time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="mediaobject"><anchor id="inlinemediaobject"/><sgmltag
class="starttag">mediaobject</sgmltag> and <sgmltag
class="starttag">inlinemediaobject</sgmltag></term>
<listitem>
<para>
Use <sgmltag class="element">inlinemediaobject</sgmltag> to insert an
inline image (that is, one that is inside a paragraph of text, or is the
only item in a table entry. Use <sgmltag
class="element">mediaobject</sgmltag> for all other images. If the
image is a screenshot, the <sgmltag
class="element">mediaobject</sgmltag> should be wrapped with a
<sgmltag class="element">screenshot</sgmltag> element. mediaobjects
contain the following items:
</para>
<variablelist>
<varlistentry><term id="imageobject"><sgmltag class="starttag">imageobject</sgmltag></term>
<listitem>
<para>
Imageobject contains information about one specific image. DocBook
allows you to add more than one imageobject, in order to provide
alternatives if the user is unable to see the preferred image. We don't
currently use this functionality in &tde; Documentation, but may do at
some time in the future.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="imagedata"><sgmltag class="emptytag">imagedata fileref=""
format=""</sgmltag></term>
<listitem>
<para>
This element holds the actual image reference. The fileref
indicates the location of the image. You should always keep images in the same
directory as the document itself, so you need only put the filename into the
fileref attribute. The format indicates the type of image you are including.
For &tde; this should be <sgmltag class="attvalue">PNG</sgmltag>. Do
<emphasis>not</emphasis> use gif format images for &tde; documents.
</para>
<para>
This is one of few <quote>empty</quote> elements in use in &tde;
Documentation. This means there is no &lt;/imagedata&gt;, but you
should <emphasis>always</emphasis> close the element as shown above,
with a final <quote>/</quote>.
</para>
<para>
Keep the images in the same directory as your
<filename>index.docbook</filename>, don't create a separate directory to
store them in.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="textobject"><sgmltag
class="starttag">textobject</sgmltag></term>
<listitem>
<para>
Encloses the text part of a screenshot, which for &tde; Documentation
means it contains a <sgmltag class="starttag">phrase</sgmltag> element.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="phrase"><sgmltag class="starttag">phrase</sgmltag></term>
<listitem>
<para>
A short descriptive phrase about the image contents, this element is
contained in the <sgmltag class="starttag">textobject</sgmltag> element.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="caption"><sgmltag class="starttag">caption</sgmltag></term>
<listitem>
<para>
If you want the image to have a caption when displayed, you can add
this. It's not required for &tde; documents, but recommended,
especially if there are several images near each other and there could
be confusion as to which you are referring in the text.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term id="informalexample"><sgmltag
class="starttag">informalexample</sgmltag></term>
<listitem>
<para>
Use this element to enclose any informal examples you use in your
document. There are no attributes. An informal example can contain
almost any markup, so feel free to use them liberally. They should
generally not be part of a paragraph.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="example"><sgmltag class="starttag">example</sgmltag></term>
<listitem>
<para>
An example is a more formal example, which has a title and an entry in
the table of contents. Use sparingly, because having a hundred examples
listed in the contents of a 5 page document lessens their usefulness.
However, don't hesitate to use when you think it's necessary.
</para>
<para>
I've used them in this document to make it easy to quickly go to the
small <quote>template</quote> examples for complex markup, because you
can find them directly from the table of contents. Less difficult
examples in this document have <sgmltag
class="starttag">informalexample</sgmltag> instead. Use your best
judgement. As with <sgmltag class="starttag">informalexample</sgmltag>,
they can contain almost any markup.
</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>A screenshot example</title>
<screen width="40">
<markup>
&lt;screenshot&gt;
&lt;screeninfo&gt;An example image&lt;/screeninfo&gt;
&lt;mediaobject&gt;
&lt;imageobject&gt;
&lt;imagedata fileref="example.png" format="PNG" /&gt;
&lt;/imageobject&gt;
&lt;textobject&gt;
&lt;phrase&gt;An example image&lt;/phrase&gt;
&lt;/textobject&gt;
&lt;/mediaobject&gt;
&lt;/screenshot&gt;
</markup>
</screen>
</example>
</chapter>
<chapter id="other-markup">
<title>General markup (not covered elsewhere)</title>
<variablelist>
<varlistentry>
<term id="abbrev"><sgmltag class="starttag">abbrev</sgmltag></term>
<listitem>
<para>
Abbreviations are shortened forms of longer words.
</para>
<para>
Abbreviations are not normally pronounced in speech. Examples are &eg;
and &ie;. This is a &tde; specific distinction, please stick to
it.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="acronym"><sgmltag class="starttag">acronym</sgmltag></term>
<listitem>
<para>
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
&tde;. As with <sgmltag class="starttag">abbrev</sgmltag>, this is a
&tde; specific distinction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="attribution">
<sgmltag class="starttag">attribution</sgmltag></term>
<listitem>
<para>
If you use <sgmltag class="starttag">quote</sgmltag> or <sgmltag
class="starttag">blockquote</sgmltag>, the source of the quote (that is,
<emphasis>who</emphasis> you are quoting) should be cited with this tag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="blockquote"><sgmltag
class="starttag">blockquote</sgmltag></term>
<listitem>
<para>
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 <sgmltag class="starttag">quote</sgmltag> 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 &tde;
Documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="emphasis"><sgmltag class="starttag">emphasis</sgmltag></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="computeroutput"><sgmltag
class="starttag">computerouput</sgmltag></term>
<listitem>
<para>
Text the user can see on the computer screen. For example, a
listing of a directory as produced after the command
<command>ls</command> would be <sgmltag
class="element">computeroutput</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="epigraph"><sgmltag class="starttag">epigraph</sgmltag></term>
<listitem>
<para>
A short quote or saying at, sometimes used at the beginning of a chapter
as an introduction. Use sparingly, no attributes used by &tde;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="equation"><sgmltag class="starttag">equation</sgmltag></term>
<listitem>
<para>
Equation is used if you need to mark up a mathematical equation. You
are unlikely to need to use this in &tde; Documents.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="hardware"><sgmltag class="starttag">hardware</sgmltag></term>
<listitem>
<para>
Used when referring to a piece of computer hardware, &eg;
<hardware>Floppy Drive</hardware> or <hardware>Monitor</hardware>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="lineannotation"><sgmltag
class="starttag">lineannotation</sgmltag></term>
<listitem>
<para>
A comment, for example in a <sgmltag
class="starttag">programlisting</sgmltag>. This is
<emphasis>not</emphasis> for comments contained in the text, it is for
comments by the author (you) <emphasis>about</emphasis> the text.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="literal"><sgmltag class="starttag">literal</sgmltag></term>
<listitem>
<para>
In &tde; Documentation, this is markup of last resort (or <quote>the
least of all evils</quote>) 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:)
</para>
<itemizedlist>
<listitem>
<para>
<sgmltag class="starttag">literal
role="extension"&gt;*.tar.gz&lt;/literal</sgmltag>
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term id="literallayout"><sgmltag
class="starttag">literallayout</sgmltag></term>
<listitem>
<para>
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).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="markup"><sgmltag class="starttag">markup</sgmltag></term>
<listitem>
<para>
Use to wrap markup examples, for text that should be represented
literally. Examples are this document, and documents that have
<abbrev>HTML</abbrev> markup included literally in them. Other than
meta-documentation like this, you probably won't have much need for
<sgmltag class="element">markup</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="optional"><sgmltag class="starttag">optional</sgmltag></term>
<listitem>
<para>
Optional information, usually in user input. Not used to date in &tde;
Documentation, but it may be appropriate in some circumstances.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="para"><sgmltag class="starttag">para</sgmltag></term>
<listitem>
<para>
A paragraph. This is the most common tag. You do not need to enclose
lists, tables, or other markup with <sgmltag
class="starttag">para</sgmltag>. Sometimes however, you might want to do
so, especially with <sgmltag class="starttag">screen</sgmltag> and some
types of lists, when they actually are still part of the current
paragraph.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="quote"><sgmltag class="starttag">quote</sgmltag></term>
<listitem>
<para>
Use when you are quoting something or someone, inside a sentence. Also
use if you want a word or phrase to be <quote>enclosed in quotes</quote>
like this.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="trademark"><sgmltag class="starttag">trademark
class=""</sgmltag></term>
<listitem>
<para>
Used to denote that a word is a trademark. There is the optional
attribute <sgmltag class="attribute">class</sgmltag> which should
contain one of the following, if appropriate:
</para>
<itemizedlist>
<listitem><para>copyright</para></listitem>
<listitem><para>registered</para></listitem>
<listitem><para>service</para></listitem>
<listitem><para>trade</para></listitem>
</itemizedlist>
<para>
If there is no <sgmltag class="attribute">class=""</sgmltag> attribute,
<quote>trade</quote> is assumed.
</para>
<para>
We have provided entities, marked up appropriately, for very commonly
met trademarks, including &Qt; (<sgmltag
class="genentity">Qt</sgmltag>), &UNIX; (<sgmltag
class="genentity">UNIX</sgmltag>), &Linux; (<sgmltag
class="genentity">Linux</sgmltag>) and many more.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="sgmltag"><sgmltag class="starttag">sgmltag</sgmltag></term>
<listitem>
<para>
An <acronym>SGML</acronym> tag. This includes &XML; and &XHTML; tags.
Use this for marking up individual components, but use <sgmltag
class="starttag">markup</sgmltag> when you need to display a block of
markup.
</para>
<para>
<sgmltag class="element">sgmltag</sgmltag> will generate the correct
markup characters for you, based on the <sgmltag
class="attribute">class</sgmltag> attribute.
</para>
<para>
Attribute values available:
</para>
<itemizedlist>
<listitem>
<para>
<sgmltag class="attvalue">attvalue</sgmltag>, for the contents of
an attribute.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">attribute</sgmltag>, for attributes.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">element</sgmltag>, for element names.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">endtag</sgmltag>, for closing tags (&eg;
<sgmltag class="endtag">para</sgmltag>.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">emptytag</sgmltag>, for tags which are
<quote>empty</quote>, such as <sgmltag class="emptytag">br</sgmltag> in
&XHTML;.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">genentity</sgmltag>, for markup up general
entities. For example, <sgmltag class="genentity">nbsp</sgmltag> in
&XHTML;.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">numcharref</sgmltag>, to mark up a numbered
character reference. <sgmltag class="genentity">nbsp</sgmltag>, for
example, could also be referred to as <sgmltag
class="numcharref">160</sgmltag>.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">paramentity</sgmltag> <!-- TODO find a very -->
<!-- short description to put here -->. You are unlikely to need this
for any &tde; documentation.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">pi</sgmltag> <!-- TODO find a very -->
<!-- short description to put here -->. Note this is an
<acronym>SGML</acronym> <acronym>PI</acronym>, not an &XML; one. You
are very unlikely to need this for any &tde; documentation.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">xmlpi</sgmltag>. An &XML; processing
instruction, such as <!-- TODO find an example that is common -->
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">starttag</sgmltag>. An opening tag, such as
<sgmltag class="starttag">para</sgmltag>. Most of this document is
marked up this way.
</para>
</listitem>
<listitem>
<para>
<sgmltag class="attvalue">sgmlcomment</sgmltag>.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term id="superscript"><sgmltag
class="starttag">superscript</sgmltag></term>
<listitem>
<para>
Superscript as in x<superscript>2</superscript>. Unlikely to be
required in most &tde; Documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="msgtext"><sgmltag class="starttag">msgtext</sgmltag></term>
<listitem>
<para>
The actual text of an informational message. Use <sgmltag
class="starttag">errorname</sgmltag> for error
messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="subscript"><sgmltag
class="starttag">subscript</sgmltag></term>
<listitem><para>Used to create things like H<subscript>2</subscript>O.
Unlikely to be found in most &tde; Documents.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="foreignphrase"><sgmltag class="starttag">foreignphrase
lang=""</sgmltag></term>
<listitem>
<para>
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 <sgmltag
class="attribute">lang</sgmltag> attribute should contain the normal two
letter designation of the language. Please be careful with these, the
<emphasis>Country</emphasis> and <emphasis>Language</emphasis> codes are
sometimes different, &eg; <quote>se</quote> is the country code for
Sweden, but the language code is <quote>sv</quote>. Using
<quote>uk</quote> for British English would give you possibly unexpected
results, as this is actually the language code for Ukrainian.
</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter id="tips-hints-etc">
<title>Admonitions: Tips, hints, and Warnings.</title>
<para>
Admonitions are set off from the main body of the text. Use these
sparingly, as they disturb the flow of the writing, but don't be afraid
to use them where necessary. Just make sure they
<emphasis>are</emphasis> necessary when you do use them.
</para>
<para>
We have settled on a preliminary order of importance for these elements,
which differs from that explained in the Duck Book. Note that this
particular order is for &tde; Documentation only, and use your own
judgement which is the most appropriate element if your situation
differs from those outlined.
</para>
<variablelist>
<varlistentry>
<term id="warning"><sgmltag class="starttag">warning</sgmltag></term>
<listitem>
<para>
Use warning when data loss could occur if you follow the procedure being
described.
</para>
</listitem>
</varlistentry>
<varlistentry><term id="caution"><sgmltag
class="starttag">caution</sgmltag></term>
<listitem>
<para>
A note of caution. Use this for example when the reader may lose easily
recovered or replaceable information (&eg; user settings), or when they
could cause data loss if they don't correctly follow the procedure being
outlined.
</para>
</listitem>
</varlistentry>
<varlistentry><term id="important"><sgmltag
class="starttag">important</sgmltag></term>
<listitem>
<para>
When there is no danger of data loss, but you wish to make clear to the
reader a consequence that isn't immediately obvious (&eg; when changing
the font for one instance of a program also changes the default setting,
and this isn't clear from the &GUI;.)
</para>
</listitem>
</varlistentry>
<varlistentry><term id="note"><sgmltag
class="starttag">note</sgmltag></term>
<listitem>
<para>
Information the user should be aware of, but is peripheral to the actual
task being described.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="tip"><sgmltag class="starttag">tip</sgmltag></term>
<listitem>
<para>
When you're giving a hint to make things easier or more productive for
the reader.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="footnote"><sgmltag class="starttag">footnote
id=""</sgmltag></term>
<listitem>
<para>
Use very sparingly for things that really are footnotes. An example
might be to note that the situation being described will be changing at
some currently unknown future time. Most footnotes would better be
marked up as notes, or tips. </para>
</listitem>
</varlistentry>
<varlistentry>
<term id="footnoteref"><sgmltag class="starttag">footnoteref
linkend=""</sgmltag></term>
<listitem>
<para>
You can refer to a footnote more than once, by using this element to
refer to it's unique id. The footnote does not need to be in the same
chapter. Use this very sparingly.
</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter id="synopsis">
<title>The synopsis elements</title>
<variablelist>
<varlistentry>
<term id="cmdsynopsis"><sgmltag
class="starttag">cmdsynopsis</sgmltag></term>
<listitem>
<para>
</para>
<example>
<title>How to markup a command synopsis</title>
<screen width="40">
&lt;cmdsynopsis&gt;
&lt;command&gt;more&lt;/command&gt;
&lt;group choice="opt"&gt;&lt;option&gt;-d&lt;/option&gt;
&lt;option&gt;l&lt;/option&gt;&lt;option&gt;f&lt;/option&gt;
&lt;option&gt;p&lt;/option&gt;&lt;option&gt;c&lt;/option&gt;
&lt;option&gt;s&lt;/option&gt;&lt;option&gt;u&lt;/option&gt;
&lt;/group&gt;
&lt;arg&gt;-num&lt;/arg&gt;
&lt;arg&gt;+/ pattern&lt;/arg&gt;
&lt;arg&gt;+ linenum&lt;/arg&gt;
&lt;arg rep="repeat"&gt;&lt;replaceable&gt;file&lt;/replaceable&gt;&lt;/arg&gt;
&lt;/cmdsynopsis&gt;
</screen>
<para>This should generate:
<cmdsynopsis>
<command>more</command>
<group
choice="opt"><option>-d</option>
<option>l</option><option>f</option>
<option>p</option><option>c</option>
<option>s</option><option>u</option></group>
<arg>-num</arg>
<arg>+/ pattern</arg>
<arg>+ linenum</arg>
<arg rep="repeat"><replaceable>file</replaceable></arg>
</cmdsynopsis>
</para>
<para>
There are several very nice examples in the Duck book at <ulink
url="http://www.docbook.org">www.docbook.org</ulink>
</para>
</example>
</listitem>
</varlistentry>
<varlistentry>
<term id="funcsynopsis"><sgmltag class="starttag">funcsynopsis</sgmltag></term>
<listitem>
<example>
<title>How to markup a function synopsis</title>
<screen>
<markup>
&lt;funcsynopsis&gt;
&lt;funcprototype&gt;
&lt;funcdef&gt;void &lt;function&gt;setFile&lt;/function&gt;&lt;/funcdef&gt;
&lt;paramdef&gt;QString &lt;parameter&gt;file&lt;/parameter&gt;&lt;/paramdef&gt;
&lt;/funcprototype&gt;
&lt;/funcsynopsis&gt;
&lt;funcsynopsis&gt;
&lt;funcprototype&gt;
&lt;funcdef&gt;void &lt;function&gt;setAutoResize&lt;/function&gt;&lt;/funcdef&gt;
&lt;paramdef&gt;bool &lt;parameter&gt;&lt;replaceable&gt;val&lt;/replaceable&gt;&lt;/parameter&gt;&lt;/paramdef&gt;
&lt;/funcprototype&gt;
&lt;/funcsynopsis&gt;
&lt;funcsynopsis&gt;
&lt;funcprototype&gt;
&lt;funcdef&gt;QString &lt;function&gt;getVideoCodec&lt;/function&gt;&lt;/funcdef&gt;&lt;void/&gt;
&lt;/funcprototype&gt;
&lt;/funcsynopsis&gt;
</markup>
</screen>
<para>
These would generate the following, respectively.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>setFile</function></funcdef><paramdef>QString <parameter>file</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>setAutoResize</function></funcdef><paramdef>bool <parameter><replaceable>val</replaceable></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>QString <function>getVideoCodec</function></funcdef><void/>
</funcprototype>
</funcsynopsis>
</example>
<para>A function synopsis can contain the following:</para>
<variablelist>
<varlistentry>
<term id="funcprototype"><sgmltag
class="starttag">funcprototype</sgmltag></term> <listitem><para>Contains
a prototype of the function. It can contain <sgmltag
class="starttag">void</sgmltag>, <sgmltag
class="starttag">varargs</sgmltag>, <sgmltag
class="starttag">paramdef</sgmltag> or most commonly, a <sgmltag
class="starttag">funcdef</sgmltag> which actually defines the
function.</para></listitem>
</varlistentry>
<varlistentry>
<term id="funcdef"><sgmltag class="starttag">funcdef</sgmltag></term>
<listitem><para>A function and it's return type. </para></listitem>
</varlistentry>
<varlistentry>
<term id="funcparams"><sgmltag class="starttag">funcparams</sgmltag></term>
<listitem><para>Contains the list of parameters for the
function.</para></listitem>
</varlistentry>
<varlistentry><term id="paramdef"><sgmltag class="starttag">paramdef</sgmltag></term>
<listitem><para>Information about the parameters of a
function.</para></listitem>
</varlistentry>
<varlistentry>
<term id="void"><sgmltag class="starttag">void</sgmltag></term>
<listitem><para>An empty element in a function indicating there are no
arguments.</para></listitem>
</varlistentry>
<varlistentry><term id="varargs"><sgmltag class="starttag">varargs</sgmltag></term>
<listitem><para>An empty element in a function indicating there are multiple
arguments, without specifically listing them. This is generally represented
with an ellipsis (...). For example <function>int
max(...);</function></para></listitem>
</varlistentry>
<varlistentry>
<term id="funcsynopsisinfo"><sgmltag class="starttag">funcsynopsisinfo</sgmltag></term>
<listitem><para>Not used in &tde; documentation.</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term id="arg"><sgmltag class="starttag">arg</sgmltag></term>
<listitem><para>Used inside <link linkend="cmdsynopsis"><sgmltag
class="starttag">cmdsynopsis</sgmltag></link>. Since most &tde;
applications are &GUI; only, you won't see this very often. See the entry
for <link linkend="cmdsynopsis"><sgmltag
class="starttag">cmdsynopsis</sgmltag></link> for a full explanation and
example.</para></listitem></varlistentry>
<varlistentry><term id="group"><sgmltag class="starttag">group</sgmltag></term>
<listitem><para>Group</para></listitem></varlistentry>
<varlistentry><term id="sbr"><sgmltag class="starttag">sbr</sgmltag></term>
<listitem><para>sbr</para></listitem></varlistentry>
<varlistentry><term id="synopfragment"><sgmltag class="starttag">synopfragment</sgmltag></term>
<listitem><para>synopfragment</para></listitem>
</varlistentry>
<varlistentry>
<term id="modifier"><sgmltag class="starttag">modifier</sgmltag></term>
<listitem><para>A modifier modifies a class, field, or method synopsis.
Examples are the words <quote>public</quote>, <quote>private</quote> or
<quote>virtual</quote></para></listitem>
</varlistentry>
<varlistentry>
<term id="fieldsynopsis"><sgmltag class="starttag">fieldsynopsis</sgmltag></term>
<listitem><para>A field synopsis.</para></listitem>
</varlistentry>
<!--
<varlistentry>
<term id="classsynopsisinfo"><sgmltag
class="starttag">classynopsisinfo</sgmltag></term>
<listitem><para>A class synopsis</para></listitem>
</varlistentry>
<varlistentry>
<term id="methodsynopsis"><sgmltag
class="starttag">methodsynopsis</sgmltag></term>
<listitem><para>A method synopsis</para>
<classsynopsis language="cpp">
<ooclass>
<classname>QWidget</classname>
</ooclass>
<methodsynopsis>
<methodname>QWidget::QWidget</methodname>
<methodparam choice="opt">
<funcparams>
<parameter>QWidget* parent = 0</parameter></funcparams>
</methodparam>
<methodparam choice="opt">
<type>const char*</type> <parameter>name = 0</parameter>
</methodparam>
</methodsynopsis>
</classsynopsis>
<methodsynopsis>
<methodname>QWidget::QWidget</methodname>
<methodparam choice="opt">
<funcparams>
<parameter>QWidget* parent = 0</parameter></funcparams>
</methodparam>
<methodparam choice="opt">
<parameter>const char* name = 0</parameter>
</methodparam>
</methodsynopsis>
<classsynopsis language="cpp">
<ooclass>
<classname></classname>
</ooclass>
<destructorsynopsis>
<void/>
</destructorsynopsis>
<fieldsynopsis>
<varname></varname>
</fieldsynopsis>
<methodsynopsis>
<methodname></methodname>
<methodparam>
<modifier></modifier>
<type></type>
<parameter></parameter>
</methodparam>
</methodsynopsis>
<methodsynopsis>
<methodname></methodname>
<methodparam>
<modifier></modifier>
<type></type>
<funcparams></funcparams>
</methodparam>
</methodsynopsis>
<constructorsynopsis>
<methodparam>
<modifier></modifier>
<type></type>
<parameter></parameter>
</methodparam>
</methodsynopsis>
<methodsynopsis>
<methodname></methodname>
<methodparam>
<modifier></modifier>
<type></type>
<funcparams></funcparams>
</methodparam>
</constructorsynopsis>
</classsynopsis>
</listitem>
</varlistentry>
<varlistentry>
<term id="destructorsynopsis"><sgmltag
class="starttag">destructorsynopsis</sgmltag></term>
<listitem><para>A destructor synopsis</para></listitem>
</varlistentry>
<varlistentry>
<term id="constructorsynopsis"><sgmltag class="starttag">
constructorsynopsis</sgmltag></term>
<listitem><para>A constructor synopsis
<constructorsynopsis>
<methodname>QWidget::QWidget</methodname>
<methodparam choice="opt">
<funcparams><type>QWidget*</type> <parameter>parent = 0</parameter></funcparams>
</methodparam>
<methodparam choice="opt">
<funcparams>
<type>const char*</type> <parameter>name = 0</parameter></funcparams>
</methodparam>
</constructorsynopsis>
<constructorsynopsis>
<methodname>QWidget::QWidget</methodname>
<methodparam choice="opt">
<funcparams>
<parameter>QWidget* parent = 0</parameter></funcparams>
</methodparam>
<methodparam choice="opt">
<parameter>const char* name = 0</parameter>
</methodparam>
</constructorsynopsis>
</para></listitem>
</varlistentry>
<varlistentry>
<term id="methodparam"><sgmltag class="starttag">
methodparam</sgmltag></term>
<listitem><para>A parameter to a method, used inside a <sgmltag
class="element">methodsynopsis</sgmltag></para></listitem>
</varlistentry>
-->
</variablelist>
</chapter>
<chapter id="programming">
<title>Markup for programming</title>
<para>
For formally marking up code examples or making a synopsis, you should
study the Duck Book and the <link linkend="synopsis">Synopsis</link>
chapter. The elements described below are mainly for marking up of
pieces of source code that appear in the running text. Remember that
&tde; and &tde; applications are written almost exclusively in C++, so
our useage may differ in places from the examples in the Duck book,
which may be describing other programming languages.
</para>
<para>
To Developers reading this, remember most of the authors who may be
documenting your work are unfamiliar with source code, and many of them
like it that way. Therefore, the explanations here are more concerned
with how to tell things apart than what they are for, and may make you
cringe.
</para>
<para>To everyone reading this, this section is very much under
construction so to speak. If you already need to use this markup, you
can ask questions on the tde-docbook mailing list, which is the most
likely place to get correct and up to date answers.</para>
<variablelist>
<varlistentry>
<term id="classname"><sgmltag
class="starttag">classname</sgmltag></term>
<listitem>
<para>
Used to identify the name of a class in a programming language. In
&tde; Documentation, you won't see this much in the user documentation,
except for those applications which contain an <acronym>API</acronym> reference
chapter, and occasionally in others. You will find it used a lot in the
<application>TDevelop</application> documentation.
</para>
<para>
For non-programmers, as we're almost exclusively discussing &tde;
applications written in C++ and using &Qt;, classnames are fairly easy
to distinguish: They start with a capital Q or K, and are usually one
word only, in the form of <classname>KApplication</classname> or
<classname>QListBox</classname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="function"><sgmltag class="starttag">function</sgmltag>,
<sgmltag class="starttag">methodname</sgmltag></term>
<listitem><anchor id="methodname"/>
<para>
A function or <quote>subroutine</quote>. In C++, a function generally
looks something like this: <function>foo();</function>. The semi-colon
may not always be present and there may or may not be content inside the
braces.
</para>
<para>
If you see things that have the form
<methodname>Kfoo::bar()</methodname> these are not just functions, but
also methods, so you would use the <sgmltag
class="starttag">methodname</sgmltag> for these.
</para>
<para>
Constructors are methods where the parts before and after the :: are the
same, &eg; <methodname>KFoo::Kfoo()</methodname>.Destructors look like
Constructors, but have a <literal>~</literal> after the :: &eg;
<methodname>Kfoo::~Kfoo()</methodname>. The same things apply as with
functions and methods: there may or may not be a ; at the end, and there
may or may not be content inside the braces of a constructor (there is
never content for a destructor).
</para>
<para>
These are normally marked up as <sgmltag
class="starttag">methodname</sgmltag>, but if you need to make a
synopsis of a method, there are specific elements available: <link
linkend="constructorsynopsis"><sgmltag
class="starttag">constructorsynopsis</sgmltag></link> and <link
linkend="destructorsynopsis"><sgmltag
class="starttag">destructorsynopsis</sgmltag></link>
</para>
<para>To recap: </para>
<variablelist>
<varlistentry>
<term>Function</term>
<listitem>
<para>
<function>foo()</function>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Methodname</term>
<listitem>
<para><methodname>Kfoo::bar()</methodname>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Constructor</term>
<listitem>
<para>
<methodname>Kfoo::Kfoo()</methodname> These are methods in ordinary
text, but when making a synopsis, have a more specific tag to use.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Destructor</term>
<listitem>
<para><methodname>Kfoo::~Kfoo()</methodname> These are methods in
ordinary text, but when making a synopsis, have a more specific tag to
use.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Sometimes you really can't tell the difference, especially when they are
being mentioned in passing in the text. Also, programmers tend to
shorten and make shortcuts when referring to snippets of source. If
it's very unclear what something is, mark it up with <sgmltag
class="starttag">function</sgmltag> and ask the developer.
</para>
<tip>
<para>
Asking a developer <quote>What is foo?</quote> will likely result in a
two page explanation of a finer point of C++ programming, which, if you
could understand it, you wouldn't have needed to ask the question in the
first place. It saves everyone a lot of time and frustration if you
word the question <quote>Out of function, method, constructor and
destructor, which is the best fit for foo?</quote>.
</para>
</tip>
</listitem>
</varlistentry>
<varlistentry>
<term id="varname"><sgmltag class="starttag">varname</sgmltag></term>
<listitem>
<para>
The name of a variable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="returnvalue"><sgmltag
class="starttag">returnvalue</sgmltag></term>
<listitem>
<para>
The value returned by a function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="token"><sgmltag class="starttag">token</sgmltag></term>
<listitem>
<para>
A token is a placeholder, something that is replaced by an actual value
during processing. (I need to come up with a useful example for a token)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="constant"><sgmltag class="starttag">constant</sgmltag></term>
<listitem>
<para>
A constant. In the snippet:
</para>
<programlisting>enum MyType { Red = 0, Green, Blue, Yellow };</programlisting>
<para><constant>Red</constant>, <constant>Green</constant>,
<constant>Blue</constant> and <constant>Yellow</constant> should be
marked up as <sgmltag class="starttag">constant</sgmltag></para>
</listitem>
</varlistentry>
<varlistentry>
<term id="type"><sgmltag class="starttag">type</sgmltag></term>
<listitem>
<para>
Used to classify a value. In the snippet:
</para>
<programlisting>enum MyType { Red = 0, Green, Blue, Yellow };</programlisting>
<para><type>MyType</type> is a <sgmltag
class="starttag">type</sgmltag></para>
</listitem>
</varlistentry>
<varlistentry>
<term id="programlisting"><sgmltag
class="starttag">programlisting</sgmltag></term>
<listitem>
<para>
Use this to wrap any source code examples in your document. You don't
need to use this for short snippets that are inline in the text, but you
should use it for any examples longer than a line or two, or that are a
separate block of text.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="structname"><sgmltag
class="starttag">structname</sgmltag>,<sgmltag
class="starttag">structfield</sgmltag></term>
<listitem><anchor id="structfield"/>
<para>
Not used in &tde; Documentation, primarily because they are rare
in &tde; source code, and are almost certainly never going to require
marking up.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="parameter"><sgmltag
class="starttag">parameter</sgmltag></term>
<listitem>
<para>
Parameters can be used for commandlines as well as for code samples.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="classsynopsis"><sgmltag
class="starttag">classsynopsis</sgmltag></term>
<listitem>
<para>
A class synopsis
</para>
<classsynopsis class="class" language="cpp">
<ooclass>
<classname>DCOPStub</classname>
</ooclass>
<classsynopsisinfo>? not sure about what goes here ?</classsynopsisinfo>
<methodsynopsis><type>enum</type> <methodname>Status</methodname>
<methodparam>
<parameter>CallSucceeded</parameter>
</methodparam>
<methodparam>
<parameter>CallFailed</parameter>
</methodparam>
</methodsynopsis>
</classsynopsis>
</listitem>
</varlistentry>
<varlistentry>
<term id="initializer"><sgmltag
class="starttag">initializer</sgmltag></term>
<listitem>
<para>
An initializer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="exceptionname"><sgmltag
class="starttag">exceptionname</sgmltag></term>
<listitem>
<para>
An exception name
</para>
</listitem>
</varlistentry>
</variablelist>
<anchor id="constructorsynopsis"/>
<anchor id="destructorsynopsis"/>
<anchor id="classsynopsisinfo"/>
<anchor id="methodparam"/>
<anchor id="methodsynopsis"/>
</chapter>
<chapter id="callouts">
<title>Making Callouts</title>
<para>
Callouts are difficult, so they have their own chapter. Use callouts
when you want to refer from text to specific parts of an image,
programlisting, or synopsis. Using callouts with graphics is currently
unused, and is somewhat problematic, so they will not (yet) be described
here.
</para>
<variablelist>
<varlistentry>
<term id="calloutlist"><sgmltag
class="starttag">calloutlist</sgmltag></term>
<listitem>
<para>
A list element that contains the callouts themselves. That is, a list
of the explanations that belong to the indicated areas in the item being
explained.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="callout"><sgmltag class="starttag">callout
arearefs=""</sgmltag></term>
<listitem>
<para>
The actual explanation or description of the called out area or line.
The <sgmltag class="attribute">arearefs</sgmltag> attribute should
contain the id of the appropriate callout you are referring to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="programlistingco"><sgmltag
class="starttag">programlistingco</sgmltag>
and <sgmltag class="starttag">screenco</sgmltag></term>
<listitem>
<para><anchor id="screenco"/>
Callouts applied to a programlisting or a screen element. Although they
look more difficult than just embedding the callouts directly in the
text, they really aren't too hard. The programlistingco contains one
areaspec, and one programlisting. The screenco contains one areaspec
and one screen element. The programlisting and screen elements are
exactly as you would normally have.
</para>
<variablelist>
<varlistentry>
<term id="areaspec"><sgmltag class="starttag">areaspec</sgmltag></term>
<listitem>
<para>
The areaspec contains a list of area elements, each of which describes
one single callout.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="area"><sgmltag class="emptytag">area coords=""
id=""</sgmltag></term>
<listitem>
<para>
The area is another of the very few empty elements, so there is no
<sgmltag class="endtag">area</sgmltag>. The <sgmltag
class="attribute">id</sgmltag> attribute should contain a unique name
for the item. The <sgmltag class="attribute">coords</sgmltag> contains
a pair of numbers which indicate first the line and then the column
where the co should appear. The line and column refer to the position
in relation to the container element, <emphasis>not the entire
document!</emphasis>. That is, in a screenco, the line and column
numbers refer to the line <emphasis>within the <sgmltag
class="element">screen</sgmltag> element</emphasis>.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>Marking up callouts with <sgmltag
class="starttag">screenco</sgmltag>.</title>
<screen>
<markup>
&lt;screenco&gt;
&lt;areaspec&gt;
&lt;area coords="2 65" id="currentdir"/&gt;
&lt;area coords="3 65" id="updir"/&gt;
&lt;area coords="4 75" id="hiddenfile"/&gt;
&lt;area coords="10 75" id="backupfile"/&gt;
&lt;area coords="13 70" id="hiddendir"/&gt;
&lt;screen&gt;
total 864
drwx------ 8 vampyr vampyr 4096 Oct 2 18:01 ./
drwxr-xr-x 13 root root 4096 Oct 1 16:32 ../
-rw------- 1 vampyr vampyr 32 Sep 2 14:21 .MCOP-random-seed
-rw------- 1 vampyr vampyr 0 Sep 2 14:42 .Xauthority
-rw-r--r-- 1 vampyr vampyr 1899 Aug 6 19:32 .Xdefaults
-rw------- 1 vampyr vampyr 261 Sep 29 22:59 .bash_history
-rw-r--r-- 1 vampyr vampyr 24 Aug 6 19:32 .bash_logout
-rw-r--r-- 1 vampyr vampyr 285 Aug 6 19:34 .bash_profile
-rw-r--r-- 1 root root 230 Aug 6 19:32 .bash_profile~
-rw-r--r-- 1 vampyr vampyr 559 Aug 6 19:32 .bashrc
-rw-r--r-- 1 vampyr vampyr 4044 Aug 6 19:32 .emacs
drwxr-xr-x 7 vampyr vampyr 4096 Sep 29 17:31 .trinity/
&lt;/screen&gt;
&lt;/screenco&gt;
&lt;calloutlist&gt;
&lt;callout arearefs="currentdir1"&gt;&lt;para&gt;The current directory.&lt;/para&gt;
&lt;/callout&gt;
&lt;callout arearefs="updir1"&gt;
&lt;para&gt;One directory up in the tree.&lt;/para&gt;
&lt;/callout&gt;
&lt;callout arearefs="hiddenfile1"&gt;
&lt;para&gt;A hidden file, indicated by the . beginning the name.&lt;/para&gt;
&lt;/callout&gt;
&lt;callout arearefs="backupfile1"&gt;
&lt;para&gt;A backup or temporary file, indicated by the ~ ending the name.&lt;/para&gt;
&lt;/callout&gt;
&lt;callout arearefs="hiddendir1"&gt;
&lt;para&gt;A hidden directory, which, like a hidden file, is indicated by the . at
the start of the name.&lt;/para&gt;
&lt;/callout&gt;
&lt;/calloutlist&gt;
</markup>
</screen>
<para>
All this markup above, while it looks complicated is really quite simple
if you study it closely. It would generate the following:
</para>
<screenco>
<areaspec>
<area coords="2 65" id="currentdir1"/>
<area coords="3 65" id="updir1"/>
<area coords="4 75" id="hiddenfile1"/>
<area coords="10 75" id="backupfile1"/>
<area coords="13 70" id="hiddendir1"/>
</areaspec>
<screen>
total 864
drwx------ 8 vampyr vampyr 4096 Oct 2 18:01 ./
drwxr-xr-x 13 root root 4096 Oct 1 16:32 ../
-rw------- 1 vampyr vampyr 32 Sep 2 14:21 .MCOP-random-seed
-rw------- 1 vampyr vampyr 0 Sep 2 14:42 .Xauthority
-rw-r--r-- 1 vampyr vampyr 1899 Aug 6 19:32 .Xdefaults
-rw------- 1 vampyr vampyr 261 Sep 29 22:59 .bash_history
-rw-r--r-- 1 vampyr vampyr 24 Aug 6 19:32 .bash_logout
-rw-r--r-- 1 vampyr vampyr 285 Aug 6 19:34 .bash_profile
-rw-r--r-- 1 root root 230 Aug 6 19:32 .bash_profile~
-rw-r--r-- 1 vampyr vampyr 559 Aug 6 19:32 .bashrc
-rw-r--r-- 1 vampyr vampyr 4044 Aug 6 19:32 .emacs
drwxr-xr-x 7 vampyr vampyr 4096 Sep 29 17:31 .trinity/
</screen>
</screenco>
<calloutlist>
<callout arearefs="currentdir1"><para>The current directory.</para>
</callout>
<callout arearefs="updir1">
<para>One directory up in the tree.</para>
</callout>
<callout arearefs="hiddenfile1">
<para>A hidden file, indicated by the . beginning the name.</para>
</callout>
<callout arearefs="backupfile1">
<para>A backup or temporary file, indicated by the ~ ending the name.</para>
</callout>
<callout arearefs="hiddendir1">
<para>A hidden directory, which, like a hidden file, is indicated by the . at
the start of the name.</para>
</callout>
</calloutlist>
</example>
<variablelist>
<varlistentry><term id="co"><sgmltag class="starttag">co</sgmltag></term>
<listitem>
<para>
Indicates where a callout is. For &tde; <acronym>HTML</acronym>
documentation, a small numbered graphic will be placed here, and also at
the location of the explanation. These numbered graphics are links
between the two places. It is entirely possible to embed the callout
elements directly in the text you are describing, and this is perhaps
the easiest way to do it. It isn't the most specific, but working out
the line coordinates to use the more precise elements is difficult, so
this way is acceptable for now.
</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>Marking up callouts by embedding directly in text</title>
<screen>
&lt;screen&gt;
drwxr-xr-x 3 vampyr vampyr 4096 Aug 6 19:32 .triniity/
lrwxrwxrwx 1 vampyr vampyr 15 Sep 3 19:46
.tdeinit-whiterabbit.magicians.org-:0 -&gt; /tmp/.kinV4m2iI= &lt;co id="symlink"/&gt;
-rw-r--r-- 1 vampyr vampyr 2096 Aug 6 19:32 .tderc
-r-------- 1 vampyr vampyr 21 Sep 2 14:21 .kxmlrpcd
-rw-r--r-- 1 vampyr vampyr 185 Aug 6 19:32 .mailcap
-rw------- 1 vampyr vampyr 31 Sep 2 14:21 .mcoprc
drwxr-xr-x 4 vampyr vampyr 4096 Aug 6 19:32 .netscape/
-rw------- 1 vampyr vampyr 777947 Sep 2 14:42 .xsession-errors
drwxr-xr-x 5 vampyr vampyr 4096 Sep 2 14:42 Desktop/ &lt;co id="dir"/&gt;
drwx------ 2 vampyr vampyr 4096 Aug 6 19:32 tmp/
-rw-r--r-- 1 vampyr vampyr 3836 Oct 13 16:44 notes.txt &lt;co id="file"/&gt;
&lt;/screen&gt;
&lt;calloutlist&gt;
&lt;callout arearefs="symlink"&gt;
&lt;para&gt;A symbolic link, indicated by the -&gt;, and showing the location it is
linked to.&lt;/para&gt;
&lt;/callout&gt;
&lt;callout arearefs="dir"&gt;
&lt;para&gt;An ordinary directory.&lt;/para&gt;
&lt;/callout&gt;
&lt;callout arearefs="file"&gt;
&lt;para&gt;An ordinary file.&lt;/para&gt;
&lt;/callout&gt;
&lt;/calloutlist&gt;
</screen>
<para>
Again it's really not as hard as it looks on first glance. This markup
would generate the following:
</para>
<screen>
drwxr-xr-x 3 vampyr vampyr 4096 Aug 6 19:32 .trinity/
lrwxrwxrwx 1 vampyr vampyr 15 Sep 3 19:46
.tdeinit-whiterabbit.magicians.org-:0 -> /tmp/.kinV4m2iI= <co id="symlink"/>
-rw-r--r-- 1 vampyr vampyr 2096 Aug 6 19:32 .tderc
-r-------- 1 vampyr vampyr 21 Sep 2 14:21 .kxmlrpcd
-rw-r--r-- 1 vampyr vampyr 185 Aug 6 19:32 .mailcap
-rw------- 1 vampyr vampyr 31 Sep 2 14:21 .mcoprc
drwxr-xr-x 4 vampyr vampyr 4096 Aug 6 19:32 .netscape/
-rw------- 1 vampyr vampyr 777947 Sep 2 14:42 .xsession-errors
drwxr-xr-x 5 vampyr vampyr 4096 Sep 2 14:42 Desktop/ <co id="dir"/>
drwx------ 2 vampyr vampyr 4096 Aug 6 19:32 tmp/
-rw-r--r-- 1 vampyr vampyr 3836 Oct 13 16:44 notes.txt <co id="file"/>
</screen>
<calloutlist>
<callout arearefs="symlink">
<para>A symbolic link, indicated by the ->, and showing the location it is
linked to.</para>
</callout>
<callout arearefs="dir">
<para>An ordinary directory.</para>
</callout>
<callout arearefs="file">
<para>An ordinary file.</para>
</callout>
</calloutlist>
</example>
<variablelist>
<varlistentry>
<term id="imageobjectco"><sgmltag
class="starttag">imageobjectco</sgmltag></term>
<listitem>
<para>
Currently unused in &tde; Documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="mediaobjectco"><sgmltag
class="starttag">mediaobjectco</sgmltag></term>
<listitem>
<para>
Currently unused in &tde; Documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="areaset">
<sgmltag class="starttag">areaset</sgmltag></term>
<listitem>
<para>
Currently unused in &tde; Documentation. This and the
above two elements will be used eventually (just as soon as I figure out
how they work).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="graphicco"><sgmltag class="starttag">graphicco</sgmltag></term>
<listitem>
<para>
Not to be used in &tde; Documentation at all.
</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter id="references-indexes-glossary">
<title>References, indexes, and glossaries</title>
<para>
These elements are very underused in &tde; Documentation up to this point,
and we will probably make an effort to implement them more fully at some
point. In the meantime, you may use them if you wish, so they are
explained here.
</para>
<sect1 id="glossaries">
<title>Making a glossary</title>
<variablelist>
<varlistentry>
<term id="glossterm"><sgmltag
class="starttag">glossterm</sgmltag></term>
<listitem>
<para>
Use this inline to identify words in the text that are explained further
in a <link linkend="glossary"><sgmltag
class="starttag">glossary</sgmltag></link> or <link
linkend="glosslist"><sgmltag
class="starttag">glosslist</sgmltag></link>. When it's placed inside a
<sgmltag class="starttag">glossentry</sgmltag> it contains the term that
glossary entry is defining (see the example below to see this in
action.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="glossary"><sgmltag class="starttag">glossary</sgmltag></term>
<listitem>
<para>
Put this where you have the glossary appearing. This is usually
at the end of the document, perhaps last before the credits section, or before
an index. A glossary will become a separate section in the book.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="glosslist"><sgmltag class="starttag">glosslist</sgmltag></term>
<listitem>
<para>
Use this if the glossary is fairly short and simple. It can
appear anywhere a normal list could appear. For &tde; Documentation, a proper
glossary is preferred, so keep use of <sgmltag
class="starttag">glosslist</sgmltag> to a minimum, where your glossary
would only contain a small handful of entries. Use your own judgement
which is most appropriate. You might use a glosslist for example, to
explain a list of terms which only appear in one section, but are very
important to understanding that section and occur several times there,
so you want the explanations to appear close to the text.
</para>
</listitem>
</varlistentry>
<varlistentry><term id="glossdiv"><sgmltag
class="starttag">glossdiv</sgmltag></term>
<listitem>
<para>
Divides a glossary into several smaller sections. A good use of this in
a very large glossary could be to break it up into separate sections for
each letter in the alphabet.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="glossentry"><sgmltag class="starttag">glossentry
id=""</sgmltag></term>
<listitem>
<para>
Contains the actual entries in the glossary or glosslist, where you
explain the terms you have marked up with glossterm in the text. You
should give these an <sgmltag class="attribute">id</sgmltag>, so they
can be linked to from the text, and crossreferenced between glossary
entries.
</para>
<para>
A <sgmltag class="element">glossentry</sgmltag> always contains one
<link linkend="glossterm"><sgmltag
class="starttag">glossterm</sgmltag></link>. It also contains one <link
linkend="glossdef"><sgmltag class="starttag">glossdef</sgmltag></link>,
or one <link linkend="glosssee"><sgmltag
class="starttag">glosssee</sgmltag></link>, or a <link
linkend="glossdef"><sgmltag class="starttag">glossdef</sgmltag></link>
and a <link linkend="glossseealso"><sgmltag
class="starttag">glossseealso</sgmltag></link>.
</para>
<tip>
<para>
I would suggest a consistent naming scheme, so glossary entries are easy
to reference without having to go look them up all the time. For
example, I use the form <sgmltag
class="attribute">id="gloss-<replaceable>word</replaceable>"</sgmltag>,
where <replaceable>word</replaceable> is the term that is being
explained.
</para>
</tip>
</listitem>
</varlistentry>
<varlistentry><term id="glossdef"><sgmltag
class="starttag">glossdef</sgmltag></term>
<listitem>
<para>
Contains the actual definitions of the terms
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="glosssee"><sgmltag class="starttag">glosssee
otherterm=""</sgmltag></term>
<listitem>
<para>
You can use this to save duplicating entries in the glossary. Instead
of a <sgmltag class="starttag">glossdef</sgmltag> you can put <sgmltag
class="starttag">glosssee</sgmltag> with the <acronym>id</acronym> of
another <sgmltag class="starttag">glossentry</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="glossseealso"><sgmltag class="starttag">glossseealso
otherterm=""</sgmltag></term>
<listitem>
<para>
This is very similar to <sgmltag class="starttag">glosssee</sgmltag>,
but instead of replacing the <sgmltag
class="starttag">glossdef</sgmltag> it is in addition to
it.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
If you compare a glossary entry to a variable list entry, you'll see the
structure is quite similar, with a <sgmltag
class="element">glossterm</sgmltag> taking the place of the <sgmltag
class="element">term</sgmltag>, and a <sgmltag
class="element">glossdef</sgmltag> taking the place of the <sgmltag
class="element">listitem</sgmltag>. Since variable lists get heavy use
in &tde; Documents, it shouldn't take you long to pick up how to do a
glossary.
</para>
<example>
<title>How to markup a glossary</title>
<para>
Say you have in the text of the document the following sentence:
</para>
<blockquote>
<para>
KWord is a graphical, wysiwyg word processor, and is part of KOffice.
</para>
</blockquote>
<para>
You want to have the words KWord and koffice in the index, and KWord,
wysiwyg, <quote>word processor</quote> and KOffice explained in a
glossary.
</para>
<para>
Many of these terms also need to be marked up with other tags, such as
application, and acronym.
</para>
<para>The eventual markup would look like this:</para>
<screen>
<markup>
&lt;para&gt;&lt;glossterm linkend="gloss-kword"&gt;KWord&lt;/glossterm&gt;
&lt;indexterm&gt;&lt;primary&gt;KWord&lt;/primary&gt;&lt;/indexterm&gt; is a
graphical &lt;glossterm linkend
="gloss-wysiwyg"&gt;&lt;acronym&gt;WYSIWYG&lt;/acronym&gt;&lt;/glossterm&gt;
&lt;glossterm linkend="gloss-word-processor"&gt;word
processor&lt;/glossterm&gt;, and is part of &lt;glossterm
linkend="gloss-koffice"&gt;KOffice&lt;/glossterm&gt;.
&lt;indexterm&gt;&lt;primary&gt;KOffice&lt;/primary&gt;&lt;/indexterm&gt;&lt;/para&gt;
</markup>
</screen>
<para>
The next part is shown here as a <sgmltag
class="starttag">glosslist</sgmltag>, and if there were really only this
many entries in it, that could be entirely appropriate. In reality, if
you are going to make a glossary, it would have many more entries and so
would warrant it's own <sgmltag class="starttag">glossary</sgmltag>
section. The syntax inside <sgmltag class="starttag">glossary</sgmltag>
and <sgmltag class="starttag">glosslist</sgmltag> are otherwise the
same.
</para>
<screen>
<markup>
&lt;glosslist&gt;
&lt;glossentry id="gloss-kword"&gt;
&lt;glossterm&gt;KWord&lt;/glossterm&gt;
&lt;glossdef&gt;&lt;para&gt;The name of the TDE word
processor&lt;/para&gt;&lt;/glossdef&gt;
&lt;/glossentry&gt;
&lt;glossentry id="gloss-koffice"&gt;
&lt;glossterm&gt;KOffice&lt;/glossterm&gt;
&lt;glossdef&gt;&lt;para&gt;A collection of office productivity tools, designed
by and for &lt;acronym&gt;TDE&lt;/acronym&gt;, including presentation software,
a word processor, a spreadsheet, a &lt;acronym&gt;PIM&lt;/acronym&gt;, and a
vector illustration application.&lt;/para&gt;&lt;/glossdef&gt;
&lt;/glossentry&gt;
&lt;glossentry id="gloss-word-processor"&gt;
&lt;glossterm&gt;word processor&lt;/glossterm&gt;
&lt;glossdef&gt;&lt;para&gt;An application for handling text, typically more
concerned with formatting visually than a plain text
editor.&lt;/para&gt;&lt;/glossdef&gt;
&lt;/glossentry&gt;
&lt;glossentry id="gloss-wysiwyg"&gt;
&lt;glossterm&gt;WYSIWYG&lt;/glossterm&gt;
&lt;glossdef&gt;&lt;para&gt;Stands for &lt;quote&gt;What You See Is What You
Get&lt;/quote&gt;, indicating that you can visually format the presentation of
your data onscreen, and when you print the document, it will look exactly as you
see on the screen.&lt;/para&gt;&lt;/glossdef&gt;
&lt;/glossentry&gt;
&lt;/glosslist&gt;
</markup>
</screen>
<para>
And the result of all this would be as follows:
</para>
<para>
<glossterm linkend="gloss-kword">KWord</glossterm>
<indexterm><primary>KWord</primary></indexterm> is a graphical
<glossterm linkend
="gloss-wysiwyg"><acronym>WYSIWYG</acronym></glossterm> <glossterm
linkend="gloss-word-processor">word processor</glossterm>, and is part
of <glossterm
linkend="gloss-koffice">KOffice</glossterm>.<indexterm><primary>KOffice</primary></indexterm>.
</para>
<glosslist>
<glossentry id="gloss-kword">
<glossterm>KWord</glossterm>
<glossdef><para>The name of the TDE word processor</para></glossdef>
</glossentry>
<glossentry id="gloss-koffice">
<glossterm>KOffice</glossterm>
<glossdef><para>A collection of office productivity tools, designed by and for
<acronym>TDE</acronym>, including presentation software, a word processor, a
spreadsheet, a <acronym>PIM</acronym>, and a vector illustration
application.</para></glossdef>
</glossentry>
<glossentry id="gloss-word-processor">
<glossterm>word processor</glossterm>
<glossdef><para>An application for handling text, typically more concerned with
formatting visually than a plain text editor.</para></glossdef>
</glossentry>
<glossentry id="gloss-wysiwyg">
<glossterm>WYSIWYG</glossterm>
<glossdef><para>Stands for <quote>What You See Is What You Get</quote>,
indicating that you can visually format the presentation of your data onscreen,
and when you print the document, it will look exactly as you see on the
screen.</para></glossdef></glossentry>
</glosslist>
</example>
</sect1>
<sect1 id="indexes">
<title>Making an Index</title>
<para>
For &tde; Documentation, indexes will in the future be generated
automatically, so many of these elements are not to be used directly
when authoring. At this stage, indexes are not generated, but if you
want to you can mark up words that should be indexed with the <sgmltag
class="starttag">indexterm</sgmltag> element, to save work for later.
</para>
<variablelist>
<varlistentry>
<term id="indexterm"><sgmltag
class="starttag">indexterm</sgmltag></term>
<listitem>
<anchor id="primary"/>
<para>
Use this to note places in the main text of the document that should
have an entry in the index. Don't over use it - not every single
occurrence of a word needs to be noted in the index, but every
occurrence where that term is significant should be.
</para>
<para>
<sgmltag class="element">indexterm</sgmltag> should contain a <sgmltag
class="starttag">primary</sgmltag>, which contains the text that the
entry will appear under in the index.
</para>
<para>
Place the <sgmltag class="element">indexterm</sgmltag> directly before
the word you want to index, and place the word itself inside the primary
element. If the word should also be listed under a secondary heading,
place that term inside a secondary element.
</para>
<example>
<title>Index</title>
<para>Say the document contains the following sentence:</para>
<blockquote><para>KWord is a graphical, wysiwyg word processor, and is part of
KOffice. </para></blockquote>
<para>You want KWord to have an index entry of it's own, and to also be noted
under KOffice in the index.</para>
<screen>
<markup>
&lt;para&gt;&lt;application&gt;KWord&lt;/application&gt;
&lt;indexterm&gt;&lt;primary&gt;KWord&lt;/primary&gt;&lt;secondary&gt;KOffice&lt;/secondary&gt;&lt;/indexterm&gt;
is a graphical, &lt;acronym&gt;WYSIWYG&lt;/acronym&gt; word processor, and is part of
KOffice.&lt;/para&gt;
</markup>
</screen>
<para>The fact that an index entry exists is not normally indicated by a change
in appearance.</para>
</example>
<para>If you think it should also be added under a third heading in the index,
you can use tertiary to indicate this. Most terms you would find in &tde;
Documentation will only need a primary index heading, so use the others
sparingly, if at all.
</para>
</listitem>
</varlistentry>
<varlistentry><term id="tertiary"><sgmltag class="starttag">tertiary</sgmltag></term>
<listitem><para>tertiary</para></listitem></varlistentry>
<varlistentry><term id="seealso"><sgmltag class="starttag">seealso</sgmltag></term>
<listitem><para>seealso</para></listitem></varlistentry>
</variablelist>
<para>
The following elements are used to create the actual index, but they are
automatically generated, if required. You should not use them when
authoring documents.
</para>
<itemizedlist>
<listitem id="index">
<para>
<sgmltag class="starttag">index</sgmltag>
</para>
</listitem>
<listitem id="indexdiv">
<para>
<sgmltag class="starttag">indexdiv</sgmltag>
</para>
</listitem>
<listitem id="indexentry">
<para>
<sgmltag class="starttag">indexentry</sgmltag>
</para>
</listitem>
<listitem id="primaryie">
<para>
<sgmltag class="starttag">primaryie</sgmltag>
</para>
</listitem>
<listitem id="secondaryie">
<para>
<sgmltag class="starttag">secondaryie</sgmltag>
</para>
</listitem>
<listitem id="see">
<para>
<sgmltag class="starttag">see</sgmltag>
</para>
</listitem>
<listitem id="seealsoie">
<para>
<sgmltag class="starttag">seealsoie</sgmltag>
</para>
</listitem>
<listitem id="seeie">
<para>
<sgmltag class="starttag">seeie</sgmltag>
</para>
</listitem>
<listitem id="tertiaryie">
<para>
<sgmltag class="starttag">tertiaryie</sgmltag>
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="other-reference-sections">
<title>Other Reference Sections</title>
<variablelist>
<varlistentry>
<term id="firstterm"><sgmltag
class="starttag">firstterm</sgmltag></term>
<listitem>
<para>
Mark up the first occurence of a technically significant term with this
element. If you are creating a glossary or an index, the first occurence
of a term will probably also warrant being an entry in one or both.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refsynopsisdivinfo"><sgmltag
class="starttag">refsynopsisdivinfo</sgmltag></term>
<listitem>
<para>
refsynopsisdivinfo
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refnamediv"><sgmltag
class="starttag">refnamediv</sgmltag></term>
<listitem>
<para>refnamediv
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refclass"><sgmltag
class="starttag">refclass</sgmltag></term>
<listitem>
<para>
refclass
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refmeta"><sgmltag
class="starttag">refmeta</sgmltag></term>
<listitem>
<para>
refmeta
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refsect1"><sgmltag
class="starttag">refsect1</sgmltag>,<sgmltag
class="starttag">refsect2</sgmltag>
and <sgmltag class="starttag">refsect3</sgmltag></term>
<listitem>
<anchor id="refsect2"/><anchor id="refsect3"/>
<para>
refsect1, refsect2 and refsect3
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refmiscinfo"><sgmltag
class="starttag">refmiscinfo</sgmltag></term>
<listitem>
<para>
refmiscinfo
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refsect1info"><sgmltag
class="starttag">refsect1info</sgmltag>,<sgmltag
class="starttag">refsect2info</sgmltag> and <sgmltag
class="starttag">refsect3info</sgmltag></term>
<listitem><anchor id="refsect2info"/><anchor id="refsect3info"/>
<para>
refsect1info, refsect2info and refsect3info
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refdescriptor"><sgmltag
class="starttag">refdescriptor</sgmltag></term>
<listitem>
<para>
refdescriptor
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="setindex"><sgmltag class="starttag">setindex</sgmltag></term>
<listitem>
<para>
Not Used in &tde; Documentation
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refpurpose"><sgmltag
class="starttag">refpurpose</sgmltag></term>
<listitem>
<para>
refpurpose
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="reference"><sgmltag class="starttag">reference</sgmltag></term>
<listitem>
<para>
reference
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refentrytitle"><sgmltag
class="starttag">refentrytitle</sgmltag></term>
<listitem>
<para>
refentrytitle
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refname"><sgmltag class="starttag">refname</sgmltag></term>
<listitem>
<para>
refname
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refentry"><sgmltag class="starttag">refentry</sgmltag></term>
<listitem>
<para>
refentry
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="refsynopsisdiv"><sgmltag
class="starttag">refsynopsisdiv</sgmltag></term>
<listitem>
<para>
refsynpsisdiv
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="tags-we-dont-use">
<title>Tags we do not use</title>
<para>
These are tags that are available for DocBook &XML;, but we have decided
they will not (at this time) be used for &tde; Documentation. They are
included here for completeness, and so nobody can say <quote>I didn't
know I wasn't supposed to use that!</quote>
</para>
<para>
They fall into two categories: Tags we have definitely decided to not
use, in which case we have made a decision to use another tag instead,
and tags that are just irrelevant to the documentation we are doing,
which you hopefully will never want. Should we write new documentation
that can sensibly be marked up with any of these elements, this list
will be revised.
</para>
<para>
If you think you have a use for one of these elements, please, check
with the DocBook team first, and be prepared to justify your case.
</para>
<itemizedlist>
<listitem id="ackno"><para><sgmltag class="starttag">ackno</sgmltag></para></listitem>
<listitem id="alt"><para><sgmltag class="starttag">alt</sgmltag></para></listitem>
<listitem id="appendixinfo"><para><sgmltag class="starttag">appendixinfo</sgmltag></para></listitem>
<listitem id="artheader"><para><sgmltag class="starttag">artheader</sgmltag></para></listitem>
<listitem id="article"><para><sgmltag class="starttag">article</sgmltag></para></listitem>
<listitem id="articleinfo"><para><sgmltag class="starttag">articleinfo</sgmltag></para></listitem>
<listitem id="artpagenums"><para><sgmltag class="starttag">artpagenums</sgmltag></para></listitem>
<listitem id="audiodata"><para><sgmltag class="starttag">audiodata</sgmltag></para></listitem>
<listitem id="audioobject"><para><sgmltag class="starttag">audioobject</sgmltag></para></listitem>
<listitem id="authorblurb"><para><sgmltag class="starttag">authorblurb</sgmltag></para></listitem>
<listitem id="authorinitials"><para><sgmltag class="starttag">authorinitials</sgmltag></para></listitem>
<listitem id="beginpage"><para><sgmltag class="starttag">beginpage</sgmltag></para></listitem>
<listitem id="bibliodiv"><para><sgmltag class="starttag">bibliodiv</sgmltag></para></listitem>
<listitem id="biblioentry"><para><sgmltag class="starttag">biblioentry</sgmltag></para></listitem>
<listitem id="bibliography"><para><sgmltag class="starttag">bibliography</sgmltag></para></listitem>
<listitem id="bibliographyinfo"><para><sgmltag class="starttag">bibliographyinfo</sgmltag></para></listitem>
<listitem id="bibliomisc"><para><sgmltag class="starttag">bibliomisc</sgmltag></para></listitem>
<listitem id="bibliomixed"><para><sgmltag class="starttag">bibliomixed</sgmltag></para></listitem>
<listitem id="bibliomset"><para><sgmltag class="starttag">bibliomset</sgmltag></para></listitem>
<listitem id="biblioset"><para><sgmltag class="starttag">biblioset</sgmltag></para></listitem>
<listitem id="bookbiblio"><para><sgmltag class="starttag">bookbiblio</sgmltag></para></listitem>
<listitem id="bridgehead"><para><sgmltag class="starttag">bridgehead</sgmltag></para></listitem>
<listitem id="chapterinfo"><para><sgmltag class="starttag">chapterinfo</sgmltag></para></listitem>
<listitem id="citation"><para><sgmltag class="starttag">citation</sgmltag></para></listitem>
<listitem id="citerefentry"><para><sgmltag class="starttag">citerefentry</sgmltag></para></listitem>
<listitem id="citetitle"><para><sgmltag class="starttag">citetitle</sgmltag></para></listitem>
<listitem id="city"><para><sgmltag class="starttag">city</sgmltag></para></listitem>
<listitem id="collab"><para><sgmltag class="starttag">collab</sgmltag></para></listitem>
<listitem id="collabname"><para><sgmltag class="starttag">collabname</sgmltag></para></listitem>
<listitem id="colophon"><para><sgmltag class="starttag">colophon</sgmltag></para></listitem>
<listitem id="colspec"><para><sgmltag class="starttag">colspect</sgmltag></para></listitem>
<listitem id="comment"><para><sgmltag class="starttag">comment</sgmltag></para></listitem>
<listitem id="confdates"><para><sgmltag class="starttag">confdates</sgmltag></para></listitem>
<listitem id="confgroup"><para><sgmltag class="starttag">confgroup</sgmltag></para></listitem>
<listitem id="confnum"><para><sgmltag class="starttag">confnum</sgmltag></para></listitem>
<listitem id="confsponsor"><para><sgmltag class="starttag">confsponsor</sgmltag></para></listitem>
<listitem id="conftitle"><para><sgmltag class="starttag">conftitle</sgmltag></para></listitem>
<listitem id="contractnum"><para><sgmltag class="starttag">contractnum</sgmltag></para></listitem>
<listitem id="contractsponsor"><para><sgmltag class="starttag">contractsponsor</sgmltag></para></listitem>
<listitem id="corpname"><para><sgmltag class="starttag">corpname</sgmltag></para></listitem>
<listitem id="country"><para><sgmltag class="starttag">country</sgmltag></para></listitem>
<listitem id="database"><para><sgmltag class="starttag">database</sgmltag></para></listitem>
<listitem id="dedication"><para><sgmltag class="starttag">dedication</sgmltag></para></listitem>
<listitem id="docinfo"><para><sgmltag class="starttag">docinfo</sgmltag></para></listitem>
<listitem id="edition"><para><sgmltag class="starttag">edition</sgmltag></para></listitem>
<listitem id="editor"><para><sgmltag class="starttag">editor</sgmltag></para></listitem>
<listitem id="entrytbl"><para><sgmltag class="starttag">entrytbl</sgmltag></para></listitem>
<listitem id="fax"><para><sgmltag class="starttag">fax</sgmltag></para></listitem>
<listitem id="figure"><para><sgmltag class="starttag">figure</sgmltag></para></listitem>
<listitem id="formalpara"><para><sgmltag class="starttag">formalpara</sgmltag></para></listitem>
<listitem id="glossaryinfo"><para><sgmltag class="starttag">sgmltag</sgmltag></para></listitem>
<listitem id="graphic"><para><sgmltag class="starttag">graphic</sgmltag></para></listitem>
<listitem id="highlights"><para><sgmltag class="starttag">highlights</sgmltag></para></listitem>
<listitem id="honorific"><para><sgmltag class="starttag">honorific</sgmltag></para></listitem>
<listitem id="indexinfo"><para><sgmltag class="starttag">indexinfo</sgmltag></para></listitem>
<listitem id="informalequation"><para><sgmltag class="starttag">informalequation</sgmltag></para></listitem>
<listitem id="informalfigure"><para><sgmltag class="starttag">informalfigure</sgmltag></para></listitem>
<listitem id="inlineequation"><para><sgmltag class="starttag">inlineequation</sgmltag></para></listitem>
<listitem id="inlinegraphic"><para><sgmltag class="starttag">inlinegraphic</sgmltag></para></listitem>
<listitem id="interfacedefinition"><para><sgmltag class="starttag">interfacedefinition</sgmltag></para></listitem>
<listitem id="interfacename"><para><sgmltag class="starttag">interfacename</sgmltag></para></listitem>
<listitem id="invpartnumber"><para><sgmltag class="starttag">invpartnumber</sgmltag></para></listitem>
<listitem id="isbn"><para><sgmltag class="starttag">isbn</sgmltag></para></listitem>
<listitem id="issn"><para><sgmltag class="starttag">issn</sgmltag></para></listitem>
<listitem id="issuenum"><para><sgmltag class="starttag">issuenum</sgmltag></para></listitem>
<listitem id="itermset"><para><sgmltag class="starttag">itermset</sgmltag></para></listitem>
<listitem id="jobtitle"><para><sgmltag class="starttag">jobtitle</sgmltag></para></listitem>
<listitem id="lineage"><para><sgmltag class="starttag">lineage</sgmltag></para></listitem>
<listitem id="lot"><para><sgmltag class="starttag">lot</sgmltag></para></listitem>
<listitem id="lotentry"><para><sgmltag class="starttag">lotentry</sgmltag></para></listitem>
<listitem id="manvolnum"><para><sgmltag class="starttag">manvolnum</sgmltag></para></listitem>
<listitem id="medialabel"><para><sgmltag class="starttag">medialabel</sgmltag></para></listitem>
<listitem id="modespec"><para><sgmltag class="starttag">modespec</sgmltag></para></listitem>
<listitem id="msg"><para><sgmltag class="starttag">msg</sgmltag></para></listitem>
<listitem id="msgaud"><para><sgmltag class="starttag">msgaud</sgmltag></para></listitem>
<listitem id="msgentry"><para><sgmltag class="starttag">msgentry</sgmltag></para></listitem>
<listitem id="msgexplan"><para><sgmltag class="starttag">msgexplan</sgmltag></para></listitem>
<listitem id="msginfo"><para><sgmltag class="starttag">msginfo</sgmltag></para></listitem>
<listitem id="msglevel"><para><sgmltag class="starttag">msglevel</sgmltag></para></listitem>
<listitem id="msgmain"><para><sgmltag class="starttag">msgmain</sgmltag></para></listitem>
<listitem id="msgorig"><para><sgmltag class="starttag">msgorig</sgmltag></para></listitem>
<listitem id="msgrel"><para><sgmltag class="starttag">msgrel</sgmltag></para></listitem>
<listitem id="msgset"><para><sgmltag class="starttag">msgset</sgmltag></para></listitem>
<listitem id="msgsub"><para><sgmltag class="starttag">msgsub</sgmltag></para></listitem>
<listitem id="objectinfo"><para><sgmltag class="starttag">objectinfo</sgmltag></para></listitem>
<listitem id="olink"><para><sgmltag class="starttag">olink</sgmltag></para></listitem>
<listitem id="orgdiv"><para><sgmltag class="starttag">orgdiv</sgmltag></para></listitem>
<listitem id="orgname"><para><sgmltag class="starttag">orgname</sgmltag></para></listitem>
<listitem id="otheraddr"><para><sgmltag class="starttag">otheraddr</sgmltag></para></listitem>
<listitem id="pagenums"><para><sgmltag class="starttag">pagenums</sgmltag></para></listitem>
<listitem id="part"><para><sgmltag class="starttag">part</sgmltag></para></listitem>
<listitem id="partintro"><para><sgmltag class="starttag">partintro</sgmltag></para></listitem>
<listitem id="phone"><para><sgmltag class="starttag">phone</sgmltag></para></listitem>
<listitem id="pob"><para><sgmltag class="starttag">pob</sgmltag></para></listitem>
<listitem id="postcode"><para><sgmltag class="starttag">postcode</sgmltag></para></listitem>
<listitem id="preface"><para><sgmltag class="starttag">preface</sgmltag></para></listitem>
<listitem id="prefaceinfo"><para><sgmltag class="starttag">prefaceinfo</sgmltag></para></listitem>
<listitem id="printhistory"><para><sgmltag class="starttag">printhistory</sgmltag></para></listitem>
<listitem id="productname"><para><sgmltag class="starttag">productname</sgmltag></para></listitem>
<listitem id="productnumber"><para><sgmltag class="starttag">productnumber</sgmltag></para></listitem>
<listitem id="property"><para><sgmltag class="starttag">property</sgmltag></para></listitem>
<listitem id="pubdate"><para><sgmltag class="starttag">pubdate</sgmltag></para></listitem>
<listitem id="publisher"><para><sgmltag class="starttag">publisher</sgmltag></para></listitem>
<listitem id="publishername"><para><sgmltag class="starttag">publishername</sgmltag></para></listitem>
<listitem id="pubsnumber"><para><sgmltag class="starttag">pubsnumber</sgmltag></para></listitem>
<listitem id="qandadiv"><para><sgmltag class="starttag">qandadiv</sgmltag></para></listitem>
<listitem id="refentryinfo"><para><sgmltag class="starttag">refentryinfo</sgmltag></para></listitem>
<listitem id="referenceinfo"><para><sgmltag class="starttag">referenceinfo</sgmltag></para></listitem>
<listitem id="remark"><para><sgmltag class="starttag">remark</sgmltag></para></listitem>
<listitem id="revdescription"><para><sgmltag class="starttag">revdescription</sgmltag></para></listitem>
<listitem id="revhistory"><para><sgmltag class="starttag">revhistory</sgmltag></para></listitem>
<listitem id="revision"><para><sgmltag class="starttag">revision</sgmltag></para></listitem>
<listitem id="revnumber"><para><sgmltag class="starttag">revnumber</sgmltag></para></listitem>
<listitem id="revremark"><para><sgmltag class="starttag">revremark</sgmltag></para></listitem>
<listitem id="secondary"><para><sgmltag class="starttag">secondary</sgmltag></para></listitem>
<listitem id="section"><para><sgmltag class="starttag">section</sgmltag></para></listitem>
<listitem id="sectioninfo"><para><sgmltag class="starttag">sectioninfo</sgmltag></para></listitem>
<listitem id="seriesinfo"><para><sgmltag class="starttag">seriesinfo</sgmltag></para></listitem>
<listitem id="seriesvolnums"><para><sgmltag class="starttag">seriesvolnums</sgmltag></para></listitem>
<listitem id="set"><para><sgmltag class="starttag">set</sgmltag></para></listitem>
<listitem id="setindexinfo"><para><sgmltag class="starttag">setindexinfo</sgmltag></para></listitem>
<listitem id="setinfo"><para><sgmltag class="starttag">setinfo</sgmltag></para></listitem>
<listitem id="shortaffil"><para><sgmltag class="starttag">shortaffil</sgmltag></para></listitem>
<listitem id="sidebar"><para><sgmltag class="starttag">sidebar</sgmltag></para></listitem>
<listitem id="sidebarinfo"><para><sgmltag class="starttag">sidebarinfo</sgmltag></para></listitem>
<listitem id="simpara"><para><sgmltag class="starttag">simpara</sgmltag></para></listitem>
<listitem id="simplemsgentry"><para><sgmltag class="starttag">simplemsgentry</sgmltag></para></listitem>
<listitem id="simplesect"><para><sgmltag class="starttag">simplesect</sgmltag></para></listitem>
<listitem id="spanspec"><para><sgmltag class="starttag">spanspec</sgmltag></para></listitem>
<listitem id="state"><para><sgmltag class="starttag">state</sgmltag></para></listitem>
<listitem id="street"><para><sgmltag class="starttag">street</sgmltag></para></listitem>
<listitem id="subject"><para><sgmltag class="starttag">subject</sgmltag></para></listitem>
<listitem id="subjectset"><para><sgmltag class="starttag">subjectset</sgmltag></para></listitem>
<listitem id="subjectterm"><para><sgmltag class="starttag">subjectterm</sgmltag></para></listitem>
<listitem id="subtitle"><para><sgmltag class="starttag">subtitle</sgmltag></para></listitem>
<listitem id="systemitem"><para><sgmltag class="starttag">systemitem</sgmltag></para></listitem>
<listitem id="titleabbrev"><para><sgmltag class="starttag">titleabbrev</sgmltag></para></listitem>
<listitem id="toc"><para><sgmltag class="starttag">toc</sgmltag></para></listitem>
<listitem id="tocback"><para><sgmltag class="starttag">tocback</sgmltag></para></listitem>
<listitem id="tocchap"><para><sgmltag class="starttag">tocchap</sgmltag></para></listitem>
<listitem id="tocentry"><para><sgmltag class="starttag">tocentry</sgmltag></para></listitem>
<listitem id="tocfront"><para><sgmltag class="starttag">tocfront</sgmltag></para></listitem>
<listitem id="toclevel1"><para><sgmltag class="starttag">toclevel1</sgmltag></para></listitem>
<listitem id="toclevel2"><para><sgmltag class="starttag">toclevel2</sgmltag></para></listitem>
<listitem id="toclevel3"><para><sgmltag class="starttag">toclevel3</sgmltag></para></listitem>
<listitem id="toclevel4"><para><sgmltag class="starttag">toclevel4</sgmltag></para></listitem>
<listitem id="toclevel5"><para><sgmltag class="starttag">toclevel5</sgmltag></para></listitem>
<listitem id="tocpart"><para><sgmltag class="starttag">tocpart</sgmltag></para></listitem>
<listitem id="videodata"><para><sgmltag class="starttag">videodata</sgmltag></para></listitem>
<listitem id="videoobject"><para><sgmltag class="starttag">videoobject</sgmltag></para></listitem>
<listitem id="volumenum"><para><sgmltag class="starttag">volumenum</sgmltag></para></listitem>
<listitem id="wordasword"><para><sgmltag class="starttag">wordasword</sgmltag></para></listitem>
</itemizedlist>
</chapter>
<chapter id="alphabetical-list">
<title>Alphabetical List of all elements</title>
<para>
This is a list of all the markup elements contained in DocBook XML
4.1.2. Choose the element you are interested in to go directly to the
section of this document which describes it.
</para>
<note>
<para>
We don't use all these elements in &tde; Documentation - they are here
for completeness. Elements we don't use are listed in <xref
linkend="tags-we-dont-use"/>.
</para>
</note>
<itemizedlist>
<listitem><para><link linkend="authorinitials"><sgmltag
class="starttag">authorinitials</sgmltag></link></para></listitem>
<listitem><para><link linkend="beginpage"><sgmltag class="starttag">beginpage</sgmltag></link></para></listitem>
<listitem><para><link linkend="bibliodiv"><sgmltag class="starttag">bibliodiv</sgmltag></link></para></listitem>
<listitem><para><link linkend="biblioentry"><sgmltag class="starttag">biblioentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="bibliographyinfo"><sgmltag class="starttag">bibliographyinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="bibliomset"><sgmltag class="starttag">bibliomset</sgmltag></link></para></listitem>
<listitem><para><link linkend="bibliomisc"><sgmltag class="starttag">bibliomisc</sgmltag></link></para></listitem>
<listitem><para><link linkend="bibliomixed"><sgmltag class="starttag">bibliomixed</sgmltag></link></para></listitem>
<listitem><para><link linkend="biblioset"><sgmltag class="starttag">biblioset</sgmltag></link></para></listitem>
<listitem><para><link linkend="bibliography"><sgmltag class="starttag">bibliography</sgmltag></link></para></listitem>
<listitem><para><link linkend="blockquote"><sgmltag class="starttag">blockquote</sgmltag></link></para></listitem>
<listitem><para><link linkend="book"><sgmltag class="starttag">book</sgmltag></link></para></listitem>
<listitem><para><link linkend="bookbiblio"><sgmltag class="starttag">bookbiblio</sgmltag></link></para></listitem>
<listitem><para><link linkend="bookinfo"><sgmltag class="starttag">bookinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="bridgehead"><sgmltag class="starttag">bridgehead</sgmltag></link></para></listitem>
<listitem><para><link linkend="co"><sgmltag class="starttag">co</sgmltag></link></para></listitem>
<listitem><para><link linkend="callout"><sgmltag class="starttag">callout</sgmltag></link></para></listitem>
<listitem><para><link linkend="calloutlist"><sgmltag class="starttag">calloutlist</sgmltag></link></para></listitem>
<listitem><para><link linkend="caption"><sgmltag class="starttag">caption</sgmltag></link></para></listitem>
<listitem><para><link linkend="caution"><sgmltag class="starttag">caution</sgmltag></link></para></listitem>
<listitem><para><link linkend="chapter"><sgmltag class="starttag">chapter</sgmltag></link></para></listitem>
<listitem><para><link linkend="chapterinfo"><sgmltag class="starttag">chapterinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="citation"><sgmltag class="starttag">citation</sgmltag></link></para></listitem>
<listitem><para><link linkend="citerefentry"><sgmltag class="starttag">citerefentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="citetitle"><sgmltag class="starttag">citetitle</sgmltag></link></para></listitem>
<listitem><para><link linkend="city"><sgmltag class="starttag">city</sgmltag></link></para></listitem>
<listitem><para><link linkend="classname"><sgmltag class="starttag">classname</sgmltag></link></para></listitem>
<listitem><para><link linkend="classsynopsis"><sgmltag class="starttag">classsynopsis</sgmltag></link></para></listitem>
<listitem><para><link linkend="classsynopsisinfo"><sgmltag class="starttag">classsynopsisinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="cmdsynopsis"><sgmltag class="starttag">cmdsynopsis</sgmltag></link></para></listitem>
<listitem><para><link linkend="colspec"><sgmltag class="starttag">colspec</sgmltag></link></para></listitem>
<listitem><para><link linkend="collab"><sgmltag class="starttag">collab</sgmltag></link></para></listitem>
<listitem><para><link linkend="collabname"><sgmltag class="starttag">collabname</sgmltag></link></para></listitem>
<listitem><para><link linkend="colophon"><sgmltag class="starttag">colophon</sgmltag></link></para></listitem>
<listitem><para><link linkend="command"><sgmltag class="starttag">command</sgmltag></link></para></listitem>
<listitem><para><link linkend="comment"><sgmltag class="starttag">comment</sgmltag></link></para></listitem>
<listitem><para><link linkend="computeroutput"><sgmltag class="starttag">computeroutput</sgmltag></link></para></listitem>
<listitem><para><link linkend="confdates"><sgmltag class="starttag">confdates</sgmltag></link></para></listitem>
<listitem><para><link linkend="confgroup"><sgmltag class="starttag">confgroup</sgmltag></link></para></listitem>
<listitem><para><link linkend="confnum"><sgmltag class="starttag">confnum</sgmltag></link></para></listitem>
<listitem><para><link linkend="confsponsor"><sgmltag class="starttag">confsponsor</sgmltag></link></para></listitem>
<listitem><para><link linkend="conftitle"><sgmltag class="starttag">conftitle</sgmltag></link></para></listitem>
<listitem><para><link linkend="constant"><sgmltag class="starttag">constant</sgmltag></link></para></listitem>
<listitem><para><link linkend="constructorsynopsis"><sgmltag class="starttag">constructorsynopsis</sgmltag></link></para></listitem>
<listitem><para><link linkend="contractnum"><sgmltag class="starttag">contractnum</sgmltag></link></para></listitem>
<listitem><para><link linkend="contractsponsor"><sgmltag class="starttag">contractspnosor</sgmltag></link></para></listitem>
<listitem><para><link linkend="contrib"><sgmltag class="starttag">contrib</sgmltag></link></para></listitem>
<listitem><para><link linkend="copyright"><sgmltag class="starttag">copyright</sgmltag></link></para></listitem>
<listitem><para><link linkend="corpauthor"><sgmltag class="starttag">corpauthor</sgmltag></link></para></listitem>
<listitem><para><link linkend="corpname"><sgmltag class="starttag">corpname</sgmltag></link></para></listitem>
<listitem><para><link linkend="country"><sgmltag class="starttag">country</sgmltag></link></para></listitem>
<listitem><para><link linkend="database"><sgmltag class="starttag">database</sgmltag></link></para></listitem>
<listitem><para><link linkend="date"><sgmltag class="starttag">date</sgmltag></link></para></listitem>
<listitem><para><link linkend="dedication"><sgmltag class="starttag">dedication</sgmltag></link></para></listitem>
<listitem><para><link linkend="destructorsynopsis"><sgmltag class="starttag">destructorsynopsis</sgmltag></link></para></listitem>
<listitem><para><link linkend="docinfo"><sgmltag class="starttag">docinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="edition"><sgmltag class="starttag">edition</sgmltag></link></para></listitem>
<listitem><para><link linkend="editor"><sgmltag class="starttag">editor</sgmltag></link></para></listitem>
<listitem><para><link linkend="email"><sgmltag class="starttag">email</sgmltag></link></para></listitem>
<listitem><para><link linkend="emphasis"><sgmltag class="starttag">emphasis</sgmltag></link></para></listitem>
<listitem><para><link linkend="envar"><sgmltag class="starttag">envar</sgmltag></link></para></listitem>
<listitem><para><link linkend="entry"><sgmltag class="starttag">entry</sgmltag></link></para></listitem>
<listitem><para><link linkend="entrytbl"><sgmltag class="starttag">entrytbl</sgmltag></link></para></listitem>
<listitem><para><link linkend="epigraph"><sgmltag class="starttag">epigraph</sgmltag></link></para></listitem>
<listitem><para><link linkend="equation"><sgmltag class="starttag">equation</sgmltag></link></para></listitem>
<listitem><para><link linkend="errorcode"><sgmltag class="starttag">errorcode</sgmltag></link></para></listitem>
<listitem><para><link linkend="errorname"><sgmltag class="starttag">errorname</sgmltag></link></para></listitem>
<listitem><para><link linkend="errortype"><sgmltag class="starttag">errortype</sgmltag></link></para></listitem>
<listitem><para><link linkend="example"><sgmltag class="starttag">example</sgmltag></link></para></listitem>
<listitem><para><link linkend="exceptionname"><sgmltag class="starttag">exceptionname</sgmltag></link></para></listitem>
<listitem><para><link linkend="fax"><sgmltag class="starttag">fax</sgmltag></link></para></listitem>
<listitem><para><link linkend="figure"><sgmltag class="starttag">figure</sgmltag></link></para></listitem>
<listitem><para><link linkend="fieldsynopsis"><sgmltag class="starttag">fieldsynopsis</sgmltag></link></para></listitem>
<listitem><para><link linkend="filename"><sgmltag class="starttag">filename</sgmltag></link></para></listitem>
<listitem><para><link linkend="firstterm"><sgmltag class="starttag">firstterm</sgmltag></link></para></listitem>
<listitem><para><link linkend="footnote"><sgmltag class="starttag">footnote</sgmltag></link></para></listitem>
<listitem><para><link linkend="footnoteref"><sgmltag class="starttag">footnoteref</sgmltag></link></para></listitem>
<listitem><para><link linkend="foreignphrase"><sgmltag class="starttag">foreignphrase</sgmltag></link></para></listitem>
<listitem><para><link linkend="formalpara"><sgmltag class="starttag">formalpara</sgmltag></link></para></listitem>
<listitem><para><link linkend="funcdef"><sgmltag class="starttag">funcdef</sgmltag></link></para></listitem>
<listitem><para><link linkend="funcparams"><sgmltag class="starttag">funcparams</sgmltag></link></para></listitem>
<listitem><para><link linkend="funcprototype"><sgmltag class="starttag">funcprototype</sgmltag></link></para></listitem>
<listitem><para><link linkend="funcsynopsis"><sgmltag class="starttag">funcsynopsis</sgmltag></link></para></listitem>
<listitem><para><link linkend="funcsynopsisinfo"><sgmltag class="starttag">funcsynopsisinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="function"><sgmltag class="starttag">function</sgmltag></link></para></listitem>
<listitem><para><link linkend="guibutton"><sgmltag class="starttag">guibutton</sgmltag></link></para></listitem>
<listitem><para><link linkend="guiicon"><sgmltag class="starttag">guiicon</sgmltag></link></para></listitem>
<listitem><para><link linkend="guilabel"><sgmltag class="starttag">guilabel</sgmltag></link></para></listitem>
<listitem><para><link linkend="guimenu"><sgmltag class="starttag">guimenu</sgmltag></link></para></listitem>
<listitem><para><link linkend="guimenuitem"><sgmltag class="starttag">guimenuitem</sgmltag></link></para></listitem>
<listitem><para><link linkend="guisubmenu"><sgmltag class="starttag">guisubmenu</sgmltag></link></para></listitem>
<listitem><para><link linkend="glossdef"><sgmltag class="starttag">glossdef</sgmltag></link></para></listitem>
<listitem><para><link linkend="glossdiv"><sgmltag class="starttag">glossdiv</sgmltag></link></para></listitem>
<listitem><para><link linkend="glossentry"><sgmltag class="starttag">glossentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="glosslist"><sgmltag class="starttag">glosslist</sgmltag></link></para></listitem>
<listitem><para><link linkend="glosssee"><sgmltag class="starttag">glosssee</sgmltag></link></para></listitem>
<listitem><para><link linkend="glossseealso"><sgmltag class="starttag">glossseealso</sgmltag></link></para></listitem>
<listitem><para><link linkend="glossterm"><sgmltag class="starttag">glossterm</sgmltag></link></para></listitem>
<listitem><para><link linkend="glossary"><sgmltag class="starttag">glossary</sgmltag></link></para></listitem>
<listitem><para><link linkend="glossaryinfo"><sgmltag class="starttag">glossaryinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="graphic"><sgmltag class="starttag">graphic</sgmltag></link></para></listitem>
<listitem><para><link linkend="graphicco"><sgmltag class="starttag">graphicco</sgmltag></link></para></listitem>
<listitem><para><link linkend="group"><sgmltag class="starttag">group</sgmltag></link></para></listitem>
<listitem><para><link linkend="hardware"><sgmltag class="starttag">hardware</sgmltag></link></para></listitem>
<listitem><para><link linkend="highlights"><sgmltag class="starttag">highlights</sgmltag></link></para></listitem>
<listitem><para><link linkend="holder"><sgmltag class="starttag">holder</sgmltag></link></para></listitem>
<listitem><para><link linkend="honorific"><sgmltag class="starttag">honorific</sgmltag></link></para></listitem>
<listitem><para><link linkend="isbn"><sgmltag class="starttag">isbn</sgmltag></link></para></listitem>
<listitem><para><link linkend="issn"><sgmltag class="starttag">issn</sgmltag></link></para></listitem>
<listitem><para><link linkend="itermset"><sgmltag class="starttag">itermset</sgmltag></link></para></listitem>
<listitem><para><link linkend="imagedata"><sgmltag class="starttag">imagedata</sgmltag></link></para></listitem>
<listitem><para><link linkend="imageobject"><sgmltag class="starttag">imageobject</sgmltag></link></para></listitem>
<listitem><para><link linkend="imageobjectco"><sgmltag class="starttag">imabeobjectco</sgmltag></link></para></listitem>
<listitem><para><link linkend="important"><sgmltag class="starttag">important</sgmltag></link></para></listitem>
<listitem><para><link linkend="index"><sgmltag class="starttag">index</sgmltag></link></para></listitem>
<listitem><para><link linkend="indexdiv"><sgmltag class="starttag">indexdiv</sgmltag></link></para></listitem>
<listitem><para><link linkend="indexentry"><sgmltag class="starttag">indexentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="indexinfo"><sgmltag class="starttag">indexinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="indexterm"><sgmltag class="starttag">indexterm</sgmltag></link></para></listitem>
<listitem><para><link linkend="informalequation"><sgmltag class="starttag">informalequation</sgmltag></link></para></listitem>
<listitem><para><link linkend="informalexample"><sgmltag class="starttag">informalexample</sgmltag></link></para></listitem>
<listitem><para><link linkend="informalfigure"><sgmltag class="starttag">informalfigure</sgmltag></link></para></listitem>
<listitem><para><link linkend="informaltable"><sgmltag class="starttag">informaltable</sgmltag></link></para></listitem>
<listitem><para><link linkend="initializer"><sgmltag class="starttag">initializer</sgmltag></link></para></listitem>
<listitem><para><link linkend="inlineequation"><sgmltag class="starttag">inlineequation</sgmltag></link></para></listitem>
<listitem><para><link linkend="inlinegraphic"><sgmltag class="starttag">inlinegraphic</sgmltag></link></para></listitem>
<listitem><para><link linkend="inlinemediaobject"><sgmltag class="starttag">inlinemediaobject</sgmltag></link></para></listitem>
<listitem><para><link linkend="interface"><sgmltag class="starttag">interface</sgmltag></link></para></listitem>
<listitem><para><link linkend="interfacedefinition"><sgmltag class="starttag">interfacedefinition</sgmltag></link></para></listitem>
<listitem><para><link linkend="interfacename"><sgmltag class="starttag">interfacename</sgmltag></link></para></listitem>
<listitem><para><link linkend="invpartnumber"><sgmltag class="starttag">invpartnumber</sgmltag></link></para></listitem>
<listitem><para><link linkend="issuenum"><sgmltag class="starttag">issuenum</sgmltag></link></para></listitem>
<listitem><para><link linkend="itemizedlist"><sgmltag class="starttag">itemizedlist</sgmltag></link></para></listitem>
<listitem><para><link linkend="jobtitle"><sgmltag class="starttag">jobtitle</sgmltag></link></para></listitem>
<listitem><para><link linkend="keycap"><sgmltag class="starttag">keycap</sgmltag></link></para></listitem>
<listitem><para><link linkend="keycode"><sgmltag class="starttag">keycode</sgmltag></link></para></listitem>
<listitem><para><link linkend="keycombo"><sgmltag class="starttag">keycombo</sgmltag></link></para></listitem>
<listitem><para><link linkend="keysym"><sgmltag class="starttag">keysym</sgmltag></link></para></listitem>
<listitem><para><link linkend="keyword"><sgmltag class="starttag">keyword</sgmltag></link></para></listitem>
<listitem><para><link linkend="keywordset"><sgmltag class="starttag">keywordset</sgmltag></link></para></listitem>
<listitem><para><link linkend="legalnotice"><sgmltag class="starttag">legalnotice</sgmltag></link></para></listitem>
<listitem><para><link linkend="lineannotation"><sgmltag class="starttag">lineannotation</sgmltag></link></para></listitem>
<listitem><para><link linkend="lineage"><sgmltag class="starttag">lineage</sgmltag></link></para></listitem>
<listitem><para><link linkend="link"><sgmltag class="starttag">link</sgmltag></link></para></listitem>
<listitem><para><link linkend="listitem"><sgmltag class="starttag">listitem</sgmltag></link></para></listitem>
<listitem><para><link linkend="literal"><sgmltag class="starttag">literal</sgmltag></link></para></listitem>
<listitem><para><link linkend="literallayout"><sgmltag class="starttag">literallayout</sgmltag></link></para></listitem>
<listitem><para><link linkend="lot"><sgmltag class="starttag">lot</sgmltag></link></para></listitem>
<listitem><para><link linkend="lotentry"><sgmltag class="starttag">lotentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="manvolnum"><sgmltag class="starttag">manvolnum</sgmltag></link></para></listitem>
<listitem><para><link linkend="markup"><sgmltag class="starttag">markup</sgmltag></link></para></listitem>
<listitem><para><link linkend="medialabel"><sgmltag class="starttag">medialabel</sgmltag></link></para></listitem>
<listitem><para><link linkend="mediaobject"><sgmltag class="starttag">mediaobject</sgmltag></link></para></listitem>
<listitem><para><link linkend="mediaobjectco"><sgmltag class="starttag">mediaobjectco</sgmltag></link></para></listitem>
<listitem><para><link linkend="member"><sgmltag class="starttag">member</sgmltag></link></para></listitem>
<listitem><para><link linkend="menuchoice"><sgmltag class="starttag">menuchoice</sgmltag></link></para></listitem>
<listitem><para><link linkend="methodname"><sgmltag class="starttag">methodname</sgmltag></link></para></listitem>
<listitem><para><link linkend="methodparam"><sgmltag class="starttag">methodparam</sgmltag></link></para></listitem>
<listitem><para><link linkend="methodsynopsis"><sgmltag class="starttag">methodsynopsis</sgmltag></link></para></listitem>
<listitem><para><link linkend="modespec"><sgmltag class="starttag">modespec</sgmltag></link></para></listitem>
<listitem><para><link linkend="modifier"><sgmltag class="starttag">modifier</sgmltag></link></para></listitem>
<listitem><para><link linkend="mousebutton"><sgmltag class="starttag">mousebutton</sgmltag></link></para></listitem>
<listitem><para><link linkend="msg"><sgmltag class="starttag">msg</sgmltag></link></para></listitem>
<listitem><para><link linkend="msgaud"><sgmltag class="starttag">nmsgaud</sgmltag></link></para></listitem>
<listitem><para><link linkend="msgentry"><sgmltag class="starttag">msgentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="msgexplan"><sgmltag class="starttag">msgexplan</sgmltag></link></para></listitem>
<listitem><para><link linkend="msginfo"><sgmltag class="starttag">msginfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="msglevel"><sgmltag class="starttag">msglevel</sgmltag></link></para></listitem>
<listitem><para><link linkend="msgmain"><sgmltag class="starttag">msgmain</sgmltag></link></para></listitem>
<listitem><para><link linkend="msgorig"><sgmltag class="starttag">msgorig</sgmltag></link></para></listitem>
<listitem><para><link linkend="msgrel"><sgmltag class="starttag">msgrel</sgmltag></link></para></listitem>
<listitem><para><link linkend="msgset"><sgmltag class="starttag">msgset</sgmltag></link></para></listitem>
<listitem><para><link linkend="msgsub"><sgmltag class="starttag">msgsub</sgmltag></link></para></listitem>
<listitem><para><link linkend="msgtext"><sgmltag class="starttag">msgtext</sgmltag></link></para></listitem>
<listitem><para><link linkend="note"><sgmltag class="starttag">note</sgmltag></link></para></listitem>
<listitem><para><link linkend="olink"><sgmltag class="starttag">olink</sgmltag></link></para></listitem>
<listitem><para><link linkend="objectinfo"><sgmltag class="starttag">objectinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="option"><sgmltag class="starttag">option</sgmltag></link></para></listitem>
<listitem><para><link linkend="optional"><sgmltag class="starttag">optional</sgmltag></link></para></listitem>
<listitem><para><link linkend="orderedlist"><sgmltag class="starttag">orderedlist</sgmltag></link></para></listitem>
<listitem><para><link linkend="orgdiv"><sgmltag class="starttag">orgdiv</sgmltag></link></para></listitem>
<listitem><para><link linkend="orgname"><sgmltag class="starttag">orgname</sgmltag></link></para></listitem>
<listitem><para><link linkend="otheraddr"><sgmltag class="starttag">otheraddr</sgmltag></link></para></listitem>
<listitem><para><link linkend="othercredit"><sgmltag class="starttag">othercredit</sgmltag></link></para></listitem>
<listitem><para><link linkend="othername"><sgmltag class="starttag">othername</sgmltag></link></para></listitem>
<listitem><para><link linkend="pob"><sgmltag class="starttag">pob</sgmltag></link></para></listitem>
<listitem><para><link linkend="pagenums"><sgmltag class="starttag">pagenums</sgmltag></link></para></listitem>
<listitem><para><link linkend="para"><sgmltag class="starttag">para</sgmltag></link></para></listitem>
<listitem><para><link linkend="paramdef"><sgmltag class="starttag">paramdef</sgmltag></link></para></listitem>
<listitem><para><link linkend="parameter"><sgmltag class="starttag">parameter</sgmltag></link></para></listitem>
<listitem><para><link linkend="part"><sgmltag class="starttag">part</sgmltag></link></para></listitem>
<listitem><para><link linkend="partintro"><sgmltag class="starttag">partintro</sgmltag></link></para></listitem>
<listitem><para><link linkend="phone"><sgmltag class="starttag">phone</sgmltag></link></para></listitem>
<listitem><para><link linkend="phrase"><sgmltag class="starttag">phrase</sgmltag></link></para></listitem>
<listitem><para><link linkend="postcode"><sgmltag class="starttag">postcode</sgmltag></link></para></listitem>
<listitem><para><link linkend="preface"><sgmltag class="starttag">preface</sgmltag></link></para></listitem>
<listitem><para><link linkend="prefaceinfo"><sgmltag class="starttag">prefaceinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="primary"><sgmltag class="starttag">primary</sgmltag></link></para></listitem>
<listitem><para><link linkend="primaryie"><sgmltag class="starttag">primaryie</sgmltag></link></para></listitem>
<listitem><para><link linkend="printhistory"><sgmltag class="starttag">printhistory</sgmltag></link></para></listitem>
<listitem><para><link linkend="procedure"><sgmltag class="starttag">procedure</sgmltag></link></para></listitem>
<listitem><para><link linkend="productname"><sgmltag class="starttag">productname</sgmltag></link></para></listitem>
<listitem><para><link linkend="productnumber"><sgmltag class="starttag">productnumber</sgmltag></link></para></listitem>
<listitem><para><link linkend="programlisting"><sgmltag class="starttag">programlistingco</sgmltag></link></para></listitem>
<listitem><para><link linkend="prompt"><sgmltag class="starttag">prompt</sgmltag></link></para></listitem>
<listitem><para><link linkend="property"><sgmltag class="starttag">property</sgmltag></link></para></listitem>
<listitem><para><link linkend="pubdate"><sgmltag class="starttag">pubdate</sgmltag></link></para></listitem>
<listitem><para><link linkend="publisher"><sgmltag class="starttag">publisher</sgmltag></link></para></listitem>
<listitem><para><link linkend="publishername"><sgmltag class="starttag">publishername</sgmltag></link></para></listitem>
<listitem><para><link linkend="pubsnumber"><sgmltag class="starttag">pubsnumber</sgmltag></link></para></listitem>
<listitem><para><link linkend="qandadiv"><sgmltag class="starttag">qandadiv</sgmltag></link></para></listitem>
<listitem><para><link linkend="qandaentry"><sgmltag class="starttag">qandaentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="qandaset"><sgmltag class="starttag">qandaset</sgmltag></link></para></listitem>
<listitem><para><link linkend="question"><sgmltag class="starttag">question</sgmltag></link></para></listitem>
<listitem><para><link linkend="quote"><sgmltag class="starttag">quote</sgmltag></link></para></listitem>
<listitem><para><link linkend="refclass"><sgmltag class="starttag">refclass</sgmltag></link></para></listitem>
<listitem><para><link linkend="refdescriptor"><sgmltag class="starttag">refdescriptor</sgmltag></link></para></listitem>
<listitem><para><link linkend="refentry"><sgmltag class="starttag">refentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="refentryinfo"><sgmltag class="starttag">refentryinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="refentrytitle"><sgmltag class="starttag">refentrytitle</sgmltag></link></para></listitem>
<listitem><para><link linkend="referenceinfo"><sgmltag class="starttag">referenceinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="refmeta"><sgmltag class="starttag">refmeta</sgmltag></link></para></listitem>
<listitem><para><link linkend="refmiscinfo"><sgmltag class="starttag">refmiscinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="refname"><sgmltag class="starttag">refname</sgmltag></link></para></listitem>
<listitem><para><link linkend="refnamediv"><sgmltag class="starttag">refnamediv</sgmltag></link></para></listitem>
<listitem><para><link linkend="refpurpose"><sgmltag class="starttag">refpurpose</sgmltag></link></para></listitem>
<listitem><para><link linkend="refsect1"><sgmltag class="starttag">refsect1</sgmltag></link></para></listitem>
<listitem><para><link linkend="refsect1info"><sgmltag class="starttag">refsect1info</sgmltag></link></para></listitem>
<listitem><para><link linkend="refsect2"><sgmltag class="starttag">refsect2</sgmltag></link></para></listitem>
<listitem><para><link linkend="refsect2info"><sgmltag class="starttag">refsect2info</sgmltag></link></para></listitem>
<listitem><para><link linkend="refsect3"><sgmltag class="starttag">refsect3info</sgmltag></link></para></listitem>
<listitem><para><link linkend="refsect3info"><sgmltag class="starttag">refsect3info</sgmltag></link></para></listitem>
<listitem><para><link linkend="refsynopsisdiv"><sgmltag class="starttag">refsynopsisdiv</sgmltag></link></para></listitem>
<listitem><para><link linkend="refsynopsisdivinfo"><sgmltag class="starttag">refsynopsisdivinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="reference"><sgmltag class="starttag">reference</sgmltag></link></para></listitem>
<listitem><para><link linkend="releaseinfo"><sgmltag class="starttag">releaseinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="remark"><sgmltag class="starttag">remark</sgmltag></link></para></listitem>
<listitem><para><link linkend="replaceable"><sgmltag class="starttag">replaceable</sgmltag></link></para></listitem>
<listitem><para><link linkend="returnvalue"><sgmltag class="starttag">returnvalue</sgmltag></link></para></listitem>
<listitem><para><link linkend="revdescription"><sgmltag class="starttag">revdescription</sgmltag></link></para></listitem>
<listitem><para><link linkend="revhistory"><sgmltag class="starttag">revhistory</sgmltag></link></para></listitem>
<listitem><para><link linkend="revnumber"><sgmltag class="starttag">revnumber</sgmltag></link></para></listitem>
<listitem><para><link linkend="revremark"><sgmltag class="starttag">revremark</sgmltag></link></para></listitem>
<listitem><para><link linkend="revision"><sgmltag class="starttag">revision</sgmltag></link></para></listitem>
<listitem><para><link linkend="row"><sgmltag class="starttag">row</sgmltag></link></para></listitem>
<listitem><para><link linkend="sbr"><sgmltag class="starttag">sbr</sgmltag></link></para></listitem>
<listitem><para><link linkend="sgmltag"><sgmltag class="starttag">sgmltag</sgmltag></link></para></listitem>
<listitem><para><link linkend="screen"><sgmltag class="starttag">screen</sgmltag></link></para></listitem>
<listitem><para><link linkend="screenco"><sgmltag class="starttag">screenco</sgmltag></link></para></listitem>
<listitem><para><link linkend="screeninfo"><sgmltag class="starttag">screeninfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="screenshot"><sgmltag class="starttag">screenshot</sgmltag></link></para></listitem>
<listitem><para><link linkend="secondary"><sgmltag class="starttag">secondary</sgmltag></link></para></listitem>
<listitem><para><link linkend="secondaryie"><sgmltag class="starttag">secondaryie</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect1"><sgmltag class="starttag">sect1</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect1info"><sgmltag class="starttag">sect1info</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect2"><sgmltag class="starttag">sect2</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect2info"><sgmltag class="starttag">sect2info</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect3"><sgmltag class="starttag">sect3</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect3info"><sgmltag class="starttag">sect3info</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect4"><sgmltag class="starttag">sect4</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect4info"><sgmltag class="starttag">sect4info</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect5"><sgmltag class="starttag">sect5</sgmltag></link></para></listitem>
<listitem><para><link linkend="sect5info"><sgmltag class="starttag">sect5info</sgmltag></link></para></listitem>
<listitem><para><link linkend="section"><sgmltag class="starttag">section</sgmltag></link></para></listitem>
<listitem><para><link linkend="sectioninfo"><sgmltag class="starttag">sectioninfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="see"><sgmltag class="starttag">see</sgmltag></link></para></listitem>
<listitem><para><link linkend="seealso"><sgmltag class="starttag">seealso</sgmltag></link></para></listitem>
<listitem><para><link linkend="seealsoie"><sgmltag class="starttag">seealsoie</sgmltag></link></para></listitem>
<listitem><para><link linkend="seeie"><sgmltag class="starttag">seeie</sgmltag></link></para></listitem>
<listitem><para><link linkend="seg"><sgmltag class="starttag">seg</sgmltag></link></para></listitem>
<listitem><para><link linkend="seglistitem"><sgmltag class="starttag">seglistitem</sgmltag></link></para></listitem>
<listitem><para><link linkend="segmentedlist"><sgmltag class="starttag">segmentedlist</sgmltag></link></para></listitem>
<listitem><para><link linkend="seriesinfo"><sgmltag class="starttag">seriesinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="seriesvolnums"><sgmltag class="starttag">seriesvolnums</sgmltag></link></para></listitem>
<listitem><para><link linkend="set"><sgmltag class="starttag">set</sgmltag></link></para></listitem>
<listitem><para><link linkend="setindex"><sgmltag class="starttag">setindex</sgmltag></link></para></listitem>
<listitem><para><link linkend="setindexinfo"><sgmltag class="starttag">setindexinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="setinfo"><sgmltag class="starttag">setinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="shortaffil"><sgmltag class="starttag">shortaffil</sgmltag></link></para></listitem>
<listitem><para><link linkend="shortcut"><sgmltag class="starttag">shortcut</sgmltag></link></para></listitem>
<listitem><para><link linkend="sidebar"><sgmltag class="starttag">sidebar</sgmltag></link></para></listitem>
<listitem><para><link linkend="sidebarinfo"><sgmltag class="starttag">sidebarinfo</sgmltag></link></para></listitem>
<listitem><para><link linkend="simpara"><sgmltag class="starttag">simpara</sgmltag></link></para></listitem>
<listitem><para><link linkend="simplelist"><sgmltag class="starttag">simplelist</sgmltag></link></para></listitem>
<listitem><para><link linkend="simplemsgentry"><sgmltag class="starttag">simplemsgentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="simplesect"><sgmltag class="starttag">simplesect</sgmltag></link></para></listitem>
<listitem><para><link linkend="spanspec"><sgmltag class="starttag">spanspec</sgmltag></link></para></listitem>
<listitem><para><link linkend="state"><sgmltag class="starttag">state</sgmltag></link></para></listitem>
<listitem><para><link linkend="step"><sgmltag class="starttag">step</sgmltag></link></para></listitem>
<listitem><para><link linkend="street"><sgmltag class="starttag">street</sgmltag></link></para></listitem>
<listitem><para><link linkend="structfield"><sgmltag class="starttag">structfield</sgmltag></link></para></listitem>
<listitem><para><link linkend="structname"><sgmltag class="starttag">structname</sgmltag></link></para></listitem>
<listitem><para><link linkend="substeps"><sgmltag class="starttag">substeps</sgmltag></link></para></listitem>
<listitem><para><link linkend="subject"><sgmltag class="starttag">subject</sgmltag></link></para></listitem>
<listitem><para><link linkend="subjectset"><sgmltag class="starttag">subjectset</sgmltag></link></para></listitem>
<listitem><para><link linkend="subjectterm"><sgmltag class="starttag">subjectterm</sgmltag></link></para></listitem>
<listitem><para><link linkend="subscript"><sgmltag class="starttag">subscript</sgmltag></link></para></listitem>
<listitem><para><link linkend="subtitle"><sgmltag class="starttag">subtitle</sgmltag></link></para></listitem>
<listitem><para><link linkend="superscript"><sgmltag class="starttag">superscript</sgmltag></link></para></listitem>
<listitem><para><link linkend="surname"><sgmltag class="starttag">surname</sgmltag></link></para></listitem>
<listitem><para><link linkend="symbol"><sgmltag class="starttag">symbol</sgmltag></link></para></listitem>
<listitem><para><link linkend="synopfragment"><sgmltag class="starttag">synopfragment</sgmltag></link></para></listitem>
<listitem><para><link linkend="synopsis"><sgmltag class="starttag">synopsis</sgmltag></link></para></listitem>
<listitem><para><link linkend="systemitem"><sgmltag class="starttag">systemitem</sgmltag></link></para></listitem>
<listitem><para><link linkend="tbody"><sgmltag class="starttag">tbody</sgmltag></link></para></listitem>
<listitem><para><link linkend="tfoot"><sgmltag class="starttag">tfoot</sgmltag></link></para></listitem>
<listitem><para><link linkend="tgroup"><sgmltag class="starttag">tgroup</sgmltag></link></para></listitem>
<listitem><para><link linkend="thead"><sgmltag class="starttag">thead</sgmltag></link></para></listitem>
<listitem><para><link linkend="table"><sgmltag class="starttag">table</sgmltag></link></para></listitem>
<listitem><para><link linkend="term"><sgmltag class="starttag">term</sgmltag></link></para></listitem>
<listitem><para><link linkend="tertiary"><sgmltag class="starttag">tertiary</sgmltag></link></para></listitem>
<listitem><para><link linkend="tertiaryie"><sgmltag class="starttag">tertiaryie</sgmltag></link></para></listitem>
<listitem><para><link linkend="textobject"><sgmltag class="starttag">textobject</sgmltag></link></para></listitem>
<listitem><para><link linkend="tip"><sgmltag class="starttag">tip</sgmltag></link></para></listitem>
<listitem><para><link linkend="title"><sgmltag class="starttag">title</sgmltag></link></para></listitem>
<listitem><para><link linkend="titleabbrev"><sgmltag class="starttag">titleabbrev</sgmltag></link></para></listitem>
<listitem><para><link linkend="toc"><sgmltag class="starttag">toc</sgmltag></link></para></listitem>
<listitem><para><link linkend="tocback"><sgmltag class="starttag">tocback</sgmltag></link></para></listitem>
<listitem><para><link linkend="tocchap"><sgmltag class="starttag">tocchap</sgmltag></link></para></listitem>
<listitem><para><link linkend="tocentry"><sgmltag class="starttag">tocentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="tocfront"><sgmltag class="starttag">tocfront</sgmltag></link></para></listitem>
<listitem><para><link linkend="toclevel1"><sgmltag class="starttag">toclevel1</sgmltag></link></para></listitem>
<listitem><para><link linkend="toclevel2"><sgmltag class="starttag">toclevel2</sgmltag></link></para></listitem>
<listitem><para><link linkend="toclevel3"><sgmltag class="starttag">toclevel3</sgmltag></link></para></listitem>
<listitem><para><link linkend="toclevel4"><sgmltag class="starttag">toclevel4</sgmltag></link></para></listitem>
<listitem><para><link linkend="toclevel5"><sgmltag class="starttag">toclevel5</sgmltag></link></para></listitem>
<listitem><para><link linkend="tocpart"><sgmltag class="starttag">tocpart</sgmltag></link></para></listitem>
<listitem><para><link linkend="token"><sgmltag class="starttag">token</sgmltag></link></para></listitem>
<listitem><para><link linkend="trademark"><sgmltag class="starttag">trademark</sgmltag></link></para></listitem>
<listitem><para><link linkend="type"><sgmltag class="starttag">type</sgmltag></link></para></listitem>
<listitem><para><link linkend="ulink"><sgmltag class="starttag">ulink</sgmltag></link></para></listitem>
<listitem><para><link linkend="userinput"><sgmltag class="starttag">userinput</sgmltag></link></para></listitem>
<listitem><para><link linkend="varargs"><sgmltag class="starttag">varargs</sgmltag></link></para></listitem>
<listitem><para><link linkend="varlistentry"><sgmltag class="starttag">varlistentry</sgmltag></link></para></listitem>
<listitem><para><link linkend="varname"><sgmltag class="starttag">varname</sgmltag></link></para></listitem>
<listitem><para><link linkend="variablelist"><sgmltag class="starttag">variablelist</sgmltag></link></para></listitem>
<listitem><para><link linkend="videodata"><sgmltag class="starttag">videodata</sgmltag></link></para></listitem>
<listitem><para><link linkend="videoobject"><sgmltag class="starttag">videoobject</sgmltag></link></para></listitem>
<listitem><para><link linkend="void"><sgmltag class="starttag">void</sgmltag></link></para></listitem>
<listitem><para><link linkend="volumenum"><sgmltag class="starttag">volumenum</sgmltag></link></para></listitem>
<listitem><para><link linkend="warning"><sgmltag class="starttag">warning</sgmltag></link></para></listitem>
<listitem><para><link linkend="wordasword"><sgmltag class="starttag">wordasword</sgmltag></link></para></listitem>
<listitem><para><link linkend="xref"><sgmltag class="starttag">xref</sgmltag></link></para></listitem>
<listitem><para><link linkend="year"><sgmltag class="starttag">year</sgmltag></link></para></listitem>
</itemizedlist>
</chapter>
<chapter id="credits-and-license">
<title>Credits and License</title>
<para>Document copyright 2000, 2001 Lauri Watts
<email>lauri@kde.org</email></para>
<para>
This reference was written with substantial help and input from the
following people who definitely deserve credit:
</para>
<itemizedlist>
<listitem><para>Frederik Fouvry</para></listitem>
<listitem><para>Eric Bischoff</para></listitem>
<listitem><para>Michael McBride</para></listitem>
<listitem><para>Lee Wee Tiong</para></listitem>
<listitem><para>Philip Rodrigues</para></listitem>
<listitem><para>Eyal Lotem
<email>GNUPeaker@yahoo.com</email></para></listitem>
<listitem><para>Malte Starostik
<email>malte.starostik@t-online.de</email></para></listitem>
<listitem><para>Antonio Larossa Jiminez</para></listitem>
</itemizedlist>
&underFDL;
</chapter>
<appendix id="appendix-entities">
<title>Entities</title>
<para>TODO</para>
</appendix>
</book>