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.
5311 lines
190 KiB
5311 lines
190 KiB
<?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
|
|
<email>trinity-devel@lists.pearsoncomputing.net</email>.
|
|
</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><foreignphrase
|
|
lang="de">Wort</foreignphrase></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><quote>as
|
|
is</quote>.</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–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><sect1
|
|
id="how-to-obtain-kapp"></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><para/Blah blah/ or <para>Blah
|
|
blah</></markup></seg>
|
|
<seg><markup><para>Blah blah</para></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>%parameterentity</markup> or
|
|
<markup>&generalentity</markup></seg>
|
|
<seg><markup>%parameterentity;</markup> or
|
|
<markup>&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><MediaObject></markup> or
|
|
<markup><MEDIAOBJECT></markup></seg>
|
|
<seg><markup><mediaobject></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><date>2000-12-31</date></markup>
|
|
<markup><releaseinfo>1.02.03</releaseinfo></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><!ENTITY "LMB" "left mouse button"></markup> <lineannotation>becomes</lineannotation>
|
|
<markup><!ENTITY "BGS" "bouton gauche de la souris"></markup></screen>
|
|
|
|
<para>
|
|
Languages that decline nouns like German and Russian can use something
|
|
like the following:
|
|
</para>
|
|
|
|
<screen><markup>
|
|
<!ENTITY "LMB" "linke Maustaste">
|
|
<!ENTITY "LMBn" "linken Maustaste">
|
|
</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;,
|
|
⪚.
|
|
</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><userinput><command>ls</command>
|
|
<option>-l</option>
|
|
<parameter>$<envar>TDEDIR</envar></parameter>
|
|
</userinput></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><userinput>
|
|
<command>export</command>
|
|
<parameter>$<envar>TDEDIR</envar>=<filename>
|
|
/usr/local/tde</filename></parameter></userinput></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>
|
|
<?xml version="1.0" ?>
|
|
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
|
|
<!-- Define an entity for your application if it is not part of TDE
|
|
CVS -->
|
|
<!ENTITY <replaceable>kmyapplication</replaceable> "<application>KMyApp</application>">
|
|
<!ENTITY kappname "<replaceable>&kmyapplication;</replaceable>"><!-- replace kmyapplication here
|
|
do *not* replace kappname-->
|
|
<!ENTITY package "<replaceable>tde-module</replaceable>"><!-- tdebase, tdeadmin, etc. Leave
|
|
this unchanged if your
|
|
application is not maintained in TDE GIT -->
|
|
<!ENTITY % addindex "IGNORE">
|
|
<!ENTITY % English "INCLUDE"> <!-- ONLY If you are writing non-English
|
|
original documentation, change
|
|
the language here -->
|
|
]></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>&kmyapplication;</quote>) as follow:
|
|
</para>
|
|
|
|
<example>
|
|
<title>Setting up the global <quote>kappname</quote> entity</title>
|
|
|
|
<screen>
|
|
From:
|
|
<markup>
|
|
<!ENTITY kappname "&kmyapplication;" -- this only *seems* redundant -->
|
|
</markup>
|
|
To:
|
|
<markup>
|
|
<!ENTITY kappname "&kate;" -- this only *seems* redundant -->
|
|
</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, ⪚
|
|
<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><?xml version="1.0" ?>
|
|
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
|
|
<!ENTITY kappname "&amor;">
|
|
<!ENTITY package "tdetoys">
|
|
<!ENTITY % addindex "IGNORE">
|
|
<!ENTITY % English "INCLUDE">
|
|
]></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="&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">&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 – 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 Übersetzung</foreignphrase></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Reviewer</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><foreignphrase lang="fr">Traduction franç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
|
|
(⪚ <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>&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><releaseinfo>1.4</releaseinfo></markup>, and you
|
|
do not need to make it
|
|
<markup><releaseinfo>1.04.00</releaseinfo></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 — 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, ⪚, 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><!-- TRANS:ROLES_OF_TRANSLATORS
|
|
--></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>
|
|
<bookinfo>
|
|
<title>The &kmyapplication; Handbook</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<!-- This is just put in as an example. For real documentation, please
|
|
define a general entity in entities/contributor.entities, e.g.
|
|
<!ENTITY George.N.Ugnacious "<personname><firstname>George</firstname><othername>N.</othername><surname>Ugnacious</surname></personname>">
|
|
<!ENTITY George.N.Ugnacious.mail "<email>gnu@tde.org</email>">
|
|
and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element.
|
|
-->
|
|
<personname>
|
|
<firstname>George</firstname>
|
|
<othername>N.</othername>
|
|
<surname>Ugnacious</surname>
|
|
</personname>
|
|
<email>gnu@tde.org</email>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
|
|
|
<copyright>
|
|
<year>2002</year>
|
|
<holder>George N. Ugnacious</holder>
|
|
</copyright>
|
|
<!-- Translators: put here the copyright notice of the translation -->
|
|
<!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
|
|
and in the FDL itself on how to use it. -->
|
|
<legalnotice>&FDLNotice;</legalnotice>
|
|
|
|
<!-- 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. -->
|
|
|
|
<date>2003-01-10</date>
|
|
<releaseinfo>1.1.</releaseinfo>
|
|
|
|
<!-- Abstract about this handbook -->
|
|
|
|
<abstract>
|
|
<para>
|
|
&kmyapplication; is an application specially designed to do nothing you would
|
|
ever want.
|
|
</para>
|
|
</abstract>
|
|
|
|
<!-- 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. -->
|
|
|
|
<keywordset>
|
|
<keyword>TDE</keyword>
|
|
<keyword>tdeutils</keyword>
|
|
<keyword>Kapp</keyword>
|
|
<keyword>nothing</keyword>
|
|
<keyword>nothing else</keyword>
|
|
</keywordset>
|
|
|
|
</bookinfo>
|
|
</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>
|
|
<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></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>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</markup>
|
|
</screen>
|
|
</example>
|
|
|
|
<example>
|
|
<title>A <sgmltag class="starttag">table</sgmltag> template</title>
|
|
<screen width="40">
|
|
<markup>
|
|
<table>
|
|
<title></title>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</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 <action>closes the dialog</action>.</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><mousebutton>left</mousebutton></markup> or
|
|
the entity <sgmltag class="genentity">LMB</sgmltag>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><markup><mousebutton>middle</mousebutton></markup> or
|
|
the entity <sgmltag class="genentity">MMB</sgmltag>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><markup><mousebutton>right</mousebutton></markup> or
|
|
the entity <sgmltag class="genentity">RMB</sgmltag>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><markup><mousebutton>wheel</mousebutton></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>
|
|
<varlistentry>
|
|
<term><menuchoice>
|
|
<shortcut>
|
|
<keycombo action="simul">&Ctrl;
|
|
<keycap>C</keycap></keycombo>
|
|
</shortcut>
|
|
<guimenu>Edit</guimenu>
|
|
<guimenuitem>Copy</guimenuitem>
|
|
</menuchoice></term>
|
|
<listitem><para><action>Copy the selected text</action> to the
|
|
clipboard</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><menuchoice>
|
|
<shortcut><keycombo action="simul">&Ctrl;
|
|
<keycap>V</keycap>
|
|
</keycombo></shortcut>
|
|
<guimenu>Edit</guimenu>
|
|
<guimenuitem>Paste</guimenuitem>
|
|
</menuchoice></term>
|
|
<listitem><para><action>Paste</action> the contents of
|
|
the clipboard at the cursor.</para></listitem>
|
|
</varlistentry>
|
|
</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
|
|
<filename><replaceable>/usr/local/foo/bar</replaceable></filename></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 ⪚ <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>Kate</application</sgmltag> is the
|
|
name of the editor, but <sgmltag
|
|
class="starttag">command>kate</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, ⪚ <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 —
|
|
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 % 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 (⪚,
|
|
<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><userinput><command>tar</command>
|
|
<option>zxvf</option>
|
|
<replaceable>filename.tar.gz</replaceable></userinput></markup>
|
|
and <markup><userinput><command>ps</command>
|
|
<option>ax</option></userinput></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>$<envar>TDEDIR</envar></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, ⪚ <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 — 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 (⪚ <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>
|
|
<qandaset>
|
|
<qandaentry>
|
|
<question>
|
|
</question>
|
|
<answer>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandaset>
|
|
</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 </imagedata>, 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>
|
|
<screenshot>
|
|
<screeninfo>An example image</screeninfo>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="example.png" format="PNG" />
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>An example image</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</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 ⪚
|
|
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, ⪚
|
|
<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">*.tar.gz</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 (⪚
|
|
<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, ⪚ <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 (⪚ 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 (⪚ 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">
|
|
|
|
<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>
|
|
</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>
|
|
<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>
|
|
</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, ⪚ <methodname>KFoo::Kfoo()</methodname>.Destructors look like
|
|
Constructors, but have a <literal>~</literal> after the :: ⪚
|
|
<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>
|
|
<screenco>
|
|
<areaspec>
|
|
<area coords="2 65" id="currentdir"/>
|
|
<area coords="3 65" id="updir"/>
|
|
<area coords="4 75" id="hiddenfile"/>
|
|
<area coords="10 75" id="backupfile"/>
|
|
<area coords="13 70" id="hiddendir"/>
|
|
|
|
<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>
|
|
</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>
|
|
<screen>
|
|
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 -> /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>
|
|
</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>
|
|
<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>
|
|
</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>
|
|
<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>
|
|
</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>
|
|
<para><application>KWord</application>
|
|
<indexterm><primary>KWord</primary><secondary>KOffice</secondary></indexterm>
|
|
is a graphical, <acronym>WYSIWYG</acronym> word processor, and is part of
|
|
KOffice.</para>
|
|
</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>
|