Move Tutorials from tdebase. Add docbook & markup tutorials. Tutorials need

editing and updating. Thus the default configuration is -DBUILD_TUTORIALS=OFF.

29 files changed, 8126 insertions, 1 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index dac8dc5..712575d 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -75,6 +75,7 @@ option( BUILD_KSIG                 "Build kde email signature manager" ${BUILD_A
 option( BUILD_NOATUN_PLUGINS       "Build noatun plugins" ${BUILD_ALL} ) # need tdemultimedia
 option( BUILD_RENAMEDLG_PLUGINS    "Build KRenameDlg plugins" ${BUILD_ALL} )
 option( BUILD_TDEFILE_PLUGINS      "Build additional tdefileplugins" ${BUILD_ALL} )
+option( BUILD_TUTORIALS            "Build tutorial help handbooks" OFF )
 
 
 ##### configure checks ##########################
@@ -109,6 +110,7 @@ tde_conditional_add_subdirectory( BUILD_KSIG                 ksig )
 tde_conditional_add_subdirectory( BUILD_NOATUN_PLUGINS       noatun-plugins )
 tde_conditional_add_subdirectory( BUILD_RENAMEDLG_PLUGINS    renamedlgplugins)
 tde_conditional_add_subdirectory( BUILD_TDEFILE_PLUGINS      tdefile-plugins)
+tde_conditional_add_subdirectory( BUILD_TUTORIALS            tutorials)
 
 ##### write configure files #####################
 
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6812bd2..85c6cde 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,3 @@
-
 KDE_LANG = en
 KDE_DOCS = AUTO
 SUBDIRS = $(AUTODIRS)
diff --git a/doc/tutorials/CMakeLists.txt b/doc/tutorials/CMakeLists.txt
new file mode 100644
index 0000000..6bc5f18
--- /dev/null
+++ b/doc/tutorials/CMakeLists.txt
@@ -0,0 +1,9 @@
+#################################################
+#
+#  Improvements and feedback are welcome
+#
+#  This file is released under GPL >= 2
+#
+#################################################
+
+tde_auto_add_subdirectories()
diff --git a/doc/tutorials/Makefile.am b/doc/tutorials/Makefile.am
new file mode 100644
index 0000000..85c6cde
--- /dev/null
+++ b/doc/tutorials/Makefile.am
@@ -0,0 +1,4 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
+SUBDIRS = $(AUTODIRS)
+
diff --git a/doc/tutorials/docprimer/CMakeLists.txt b/doc/tutorials/docprimer/CMakeLists.txt
new file mode 100644
index 0000000..a4e5cd9
--- /dev/null
+++ b/doc/tutorials/docprimer/CMakeLists.txt
@@ -0,0 +1,9 @@
+#################################################
+#
+#  Improvements and feedback are welcome
+#
+#  This file is released under GPL >= 2
+#
+#################################################
+
+tde_create_handbook( DESTINATION khelpcenter/docprimer )
diff --git a/doc/tutorials/docprimer/Makefile.am b/doc/tutorials/docprimer/Makefile.am
new file mode 100644
index 0000000..4169155
--- /dev/null
+++ b/doc/tutorials/docprimer/Makefile.am
@@ -0,0 +1,3 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/tutorials/docprimer/index.docbook b/doc/tutorials/docprimer/index.docbook
new file mode 100644
index 0000000..28792b1
--- /dev/null
+++ b/doc/tutorials/docprimer/index.docbook
@@ -0,0 +1,2160 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kde-authors '<personname><surname>The &kde; Documentation Team</surname></personname>'>
+  <!ENTITY meinproc "<command>meinproc</command>">
+  <!ENTITY checkxml "<command>checkXML</command>">
+  <!ENTITY svn "<application>Subversion</application>">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"><!-- change language only here -->
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &tde; Documentation Primer</title>
+
+<authorgroup>
+<author>&kde-authors;</author>
+<author>
+<firstname>Carlos</firstname><surname>Woelz</surname>
+</author>
+<author>&tde-authors;</author>
+</authorgroup>
+
+<copyright>
+<year>2004</year>
+<holder>The KDE Documentation Team</holder>
+</copyright>
+<copyright>
+<year>2004</year>
+<holder>Carlos Woelz</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>
+This document provides information to start writing documentation for &tde;.
+Please report any errors or omissions to
+<email>trinity-devel@lists.pearsoncomputing.net</email>.
+</para>
+</abstract>
+
+<keywordset>
+<keyword>TDE</keyword>
+<keyword>Writing</keyword>
+<keyword>Documentation</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="intro">
+<title>Introduction</title>
+
+<para>
+The objective of this guide is to present all information required to make the
+experience of writing &tde; documentation as easy as possible. 
+The next chapter gives some information about what skills you'll need for the task.
+It is important to note that this guide is a joint effort of the &tde;
+English Documentation Team and the &tde; Quality Team. You can ask for support
+from both teams at any time.</para>
+
+<para>The <emphasis>&tde; English Documentation Team</emphasis> exists to
+provide end-user documentation for the whole of &tde;. It's a big task, but an
+important one. Although &tde; aims to be easy to use, not everything is obvious
+without some help, and, in a project this big, even an experienced user
+can't know every corner of &tde;.</para>
+<para>The team is made up of people doing several different tasks:
+<itemizedlist>
+<listitem><para>Writing documentation for individual applications</para>
+</listitem>
+<listitem><para>Writing wider documentation for the whole of &tde; (like
+the User Guide, or this document).</para>
+</listitem>
+<listitem><para>Proofreading and/or updating documentation to ensure
+that it is correct and up-to-date.</para>
+</listitem>
+</itemizedlist>
+Contributors to all of these areas are always welcome. You can
+choose the area you would like to contribute to, based on your skills
+and what you enjoy doing. If you need any help with documentation issues,
+do not hesitate to ask at the &tde; Documentation mailing list,
+<email>kde-doc-english@kde.org</email>, or on <acronym>IRC</acronym> in the channel #kde-docs on
+<systemitem class="domainname">irc.freenode.net</systemitem>.</para>
+
+
+<para>
+The <emphasis>&tde; Quality Team</emphasis> provides support for
+new contributors, and to coordinates the efforts of the volunteers.
+The <ulink url="http://quality.kde.org">&tde; Quality Team Website</ulink>
+provides guides to help you with some general development tasks,
+such as getting the sources,
+<ulink url="http://quality.kde.org/develop/cvsguide/">Building
+&tde; From Source Step By Step</ulink>, and
+<ulink url="http://quality.kde.org/develop/cvsguide/managestep.php">
+Working with Subversion</ulink>, &etc;. If these guides are not sufficient, and you
+are having problems with &tde; development, we provide support for new contributors
+at the &tde; Quality mailing list, <email>kde-quality@kde.org</email>, or on IRC
+in the channel #kde-quality on
+<filename class="directory">irc.freenode.net</filename>.
+</para>
+
+</chapter>
+
+
+<chapter id="getting-started">
+<title>Getting Started</title>
+
+<para>If you got this far reading this document, you're probably interested in
+helping with &tde; documentation. If so, welcome aboard! We're always
+happy to have new contributors, and whatever your skills, you can help
+make &tde; even better.
+<!-- Where to find us - mailing list, IRC, i18n.kde.org/doc --></para>
+
+
+<sect1 id="requirements">
+<title>Things You'll Need</title>
+
+<para>To write documentation, there are only three things that are absolutely
+necessary: some English knowledge, knowing what you want to document, and
+access to a relatively recent version of the application you want to
+document.</para>
+
+<note><para>Notice that the list of requirements does
+<emphasis>not</emphasis> contain a requirement that you learn DocBook,
+or any of the other tools we use. We're very happy to receive
+documentation written in plain text. We would much rather have the
+content and have to add formatting than have no content at all.</para>
+</note>
+
+<sect2 id="requirements-english">
+<title>English Knowledge</title>
+
+<para>All &tde; documentation is originally written in English, so you
+have to be able to write English to a reasonable level. That said, you
+<emphasis>don't</emphasis> need to be a native speaker, and you don't
+need to write word-perfect English. There are native English-speaking
+proofreaders on the documentation team, and we would much rather have
+<emphasis>some</emphasis> documentation that needs a little tweaking,
+than no documentation at all. If you don't feel comfortable writing in
+English, you might like to contribute to one of the &tde; translation
+teams. You can find more information about translation on <ulink
+url="http://i18n.kde.org">http://i18n.kde.org</ulink>.</para>
+
+<para>If you're a fluent English speaker with an eye for detail, you
+might be interested in joining the proofreading
+team. Just drop an email to <email>kde-doc-english@kde.org</email> if
+you'd like to help the proofreaders.</para>
+<!-- What about moving this to the other task section in the end? -->
+
+
+</sect2>
+<sect2 id="requirements-what-to-write">
+<title>Deciding What to Write About</title>
+<para>&tde; is a very large project, with many different parts and
+programs. Because of this, it can be hard to know where to start if you
+want to contribute. There are a few rules of thumb that can help you
+decide what to write about:
+<itemizedlist>
+<listitem><para>Find a topic that you'll enjoy writing about; It will
+increase your motivation and help you to produce better documentation.</para>
+</listitem>
+<listitem><para>Write about an application you know well. You'll be able
+to spend more time on writing and less time trying to work out how the
+application works. On the other hand, documenting an application can be
+a good way to learn about how it works, especially if you like a challenge!</para>
+</listitem>
+</itemizedlist>
+</para>
+
+<para>
+If you are looking for an application to document, or just checking the status
+of the application you want to work with, the
+<ulink url="http://wiki.kde.org/tiki-index.php?page=KDE+Quality+Team">
+&tde; Quality Team Wiki</ulink> contains lists of applications, organized
+by modules, and their general status, including documentation status, and who
+is working on it. Not all modules and applications are included or up to date,
+but it is certainly worth checking.</para>
+
+<para>If you start documenting one of the listed applications, please add your
+name to the wiki pages as well. But If you just can't find an application to
+work with, write to <email>kde-doc-english@kde.org</email> and ask for
+suggestions. There's always something available to do, but there's no obligation
+to work on a particular application. Also, contributing to a document doesn't
+force you into keeping that document up-to-date (although if you can do that,
+it's very welcome!).
+</para>
+
+<para>Another place to check is the &tde; bug list at <ulink
+url="http://bugs.kde.org">http://bugs.kde.org</ulink>.  This is usually
+more detailed than the wiki, and provides a place to list specific small
+changes that are needed to documents.  These are often nice small jobs
+to get you started contributing.  A set of quick links to ready made
+queries are available from the Documentation Project's <ulink
+url="http://i18n.kde.org/doc/current.php">
+http://i18n.kde.org/doc/current.php</ulink> page.</para>
+
+<para>It is also helpful to the team to file more bugs like these
+above.  You will need a bugzilla account, and a recent copy of &tde;.
+Simply open an application, choose
+<menuchoice><guimenu>Help</guimenu><guimenuitem><replaceable>appname</replaceable>
+Handbook</guimenuitem></menuchoice>.  Then just read through the document,
+following along in the application.  &tde; applications are a moving
+target to document, and sometimes the documentation has not yet caught
+up with a change to the interface or behavior of an application.  Feel
+free to file bugs for any of these issues you find, in order of urgency:</para>
+
+<itemizedlist>
+<listitem><para>Inaccurate information about how an application
+works</para><para>For instance, if you previously needed to save
+changes to a file before they take effect in the &GUI;, and this now
+happens automatically, text referring to manual saving should be
+removed, or it will confuse readers.</para>
+<!-- This example is terrible, can someone find a better one? -->
+</listitem>
+<listitem><para>GUI options or menu items (or sometimes, entire
+dialogs)</para><para>This often happens in configuration dialogs, when
+new items are added, a new grouping of existing options may be
+created.</para>
+</listitem>
+<listitem><para>New Features that are available and are not yet
+documented.</para></listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="requirements-access">
+<title>Access to a Recent Version</title>
+
+<para>To make sure that the documentation you write is up-to-date,
+you'll need to run a recent version of the application you are working with.
+This normally means a recent beta version, a version of your application
+compiled from sources or a version of &tde; compiled from sources in the &svn;
+repository. If you think that compiling from sources is too burdensome, and you
+cannot get some recent beta packages, there are still some interesting
+possibilities to work around this requirement:</para>
+
+<itemizedlist>
+<listitem><para>
+Write about a stable application: there are many apps with a stable interface 
+which are still lacking good documentation. In this case, the last stable version
+provided by your distribution will be sufficient to write about it, no
+compiling required.
+</para></listitem>
+
+<listitem><para>
+Using a remote desktop connection to preview the development version is
+an ideal solution to this problem. The FreeNX terminal server technology
+enables decent desktop performance even with dial up Internet
+connections. We are planning to offer this service to &tde; documenters, but
+the infrastructure is not yet in place (as of May
+2005). You may ask the <email>kde-quality@kde.org</email> mailing list
+about it, if you think this is the way to go. 
+<!-- Also, Kurt's NX stuff will hopefully make this unnecessary Real -->
+<!-- Soon Now. Once that happens, write about it here -->
+</para></listitem>
+
+</itemizedlist>
+
+<para>If you want to try out building &tde; from sources, the &tde; Quality
+website provides
+<ulink url="http://quality.kde.org/develop/cvsguide/buildstep.php">a detailed,
+step by step building guide</ulink>. You can find even more information at the
+<ulink url="http://developer.kde.org/build">&tde; Developers Website</ulink>.
+If you face any problems in the
+compiling process you can't solve by reading the building guide, don't hesitate
+to as for help on <email>kde-quality@kde.org</email>.</para>
+</sect2>
+
+</sect1>
+
+</chapter>
+
+<chapter id="guidelines">
+<title>&tde; Writing Recommendations and Guidelines</title>
+
+<para>To maintain a uniform documentation set, there are some consistency rules
+to be followed, that you should know before starting. In this chapter you will
+find guidelines about targeting your audience, English usage, and what to cover
+when you are documenting an application.</para>
+
+<para>We also offer some general writing tips to help you to
+get started, provided by experienced &tde; documenters.</para>
+
+<sect1 id="guidelines-audience">
+<title>Writing for your Audience</title>
+
+<para>Since &tde; is used by people with a wide range of abilities, from
+completely new users to long-time gurus, the documentation should be
+appropriate to this audience. Therefore, in general, documentation
+shouldn't assume too much about the knowledge of the reader, without
+being patronizing. There are no hard-and-fast rules, but here are some
+tips that should help:</para>
+<itemizedlist>
+<listitem><para>Remember that the audience varies with the application: for
+example, a server control module has a very different user base than a user of a
+game, and the manuals should reflect this. Don't insult the administrator
+intelligence, and don't assume knowledge for the gamer that might not be
+there.</para>
+</listitem>
+<listitem>
+<para>Keep a logical progression of difficulty: Keep the first few pages
+of the document simple, and accessible to users who have never seen the
+application before. More technical information should appear towards the
+end of the document.</para>
+</listitem>
+</itemizedlist>
+
+<para>Remember also that different types of documentation have different
+purposes:</para>
+
+<variablelist>
+<varlistentry>
+<term>Application Handbooks</term>
+<listitem>
+<para>These may go into great depths on the configuration, behavior and
+sometimes the philosophy of an application.  There is scope to cover
+corner cases of configuration, commonly asked questions, and advanced
+troubleshooting techniques.</para> <para>They should also always contain
+a complete reference to all the available menu functions and
+configuration options for the application (but while these are required,
+they should be certainly be considered a minimum of information to
+provide.)</para>
+<para>The Application Handbook should be answering the question:
+<quote>What are all the things I can do with this application?</quote></para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>User Guide</term>
+<listitem>
+<para>A much higher level overview of &tde; and its applications.  This
+aims to be the first stop for users to look for information, and should
+be task based.</para>
+<para>When writing for the User Guide, you should assume a working
+default installation of &tde;, and you do not need to cover all cases of
+unusual configurations, only the very common variations, nor should you
+cover in-depth troubleshooting.  You might provide answers to some very
+common configuration errors (or not, as appropriate) and refer to the
+Application Manual, the Application's Website, mailing list, and any
+appropriate man pages for more detailed information.</para>
+<para>Most people reading this guide do not have an actual problem, they
+simply want to achieve a goal, and don't yet know how, or where to find
+that information.</para>
+<para>The User Guide should be answering the question: <quote>How do I
+do <replaceable>this common task, &eg; send an email, play a
+movie</replaceable>?</quote>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>What's This Help</term>
+<listitem>
+<para>A very focused and specific type of assistance, about a single
+configuration or interface item.  Again you should not really attempt to
+cover all cases here, only common ones, and explain what the option
+does, not why it is there.  Refer users to the Application Handbook if
+appropriate, for more information.</para>
+<para>Provide an example of the expected input, if that is not clear
+from the context.</para>
+<para>The What's This Help is most often answering the question: <quote>Do I
+need to fill in this box? If so, what do I put in it?</quote></para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+
+<sect1 id="guidelines-english-usage">
+<title>English Usage Guidelines and Recommendations</title>
+
+<para>&tde; documentation is written in
+standard US English (rather than any other regional variety of
+English). We have a set of standard forms of certain words (such as
+<quote>email</quote> instead of <quote>e-mail</quote>) to improve
+consistency across all documentation. Work is underway to expand and
+formalize this list, but for the moment, it is located at <ulink
+url="http://www.kde.me.uk/index.php?page=Consistency+rules">http://www.kde.me.uk/index.php?page=Consistency+rules</ulink>.
+There are also standard names for &tde; widgets, which are listed in
+<xref linkend="widget-names" /></para> 
+
+<para>A good way to catch simple errors
+is to read the text out loud, or have someone else read it to
+you. Passages that don't flow easily or have obviously awkward construction
+of the type you may miss on the screen, will usually become blindingly
+obvious when you hear them. This is especially the case with detecting
+really long sentences, as you will run out of breath and turn
+blue.</para>
+
+<para>Some tips about writing readable sentences:
+<itemizedlist>
+<listitem><para>Use complete sentences. Not fragments. Like these ones.</para>
+</listitem>
+<listitem>
+<para>Avoid run-on sentences, sentences that cover several different
+subjects, or sentences that could be broken up into several sentences;
+avoid sentences that can fill a whole paragraph all by themselves and
+that are really long, like this one, which is all of the above.</para>
+</listitem>
+<listitem>
+<para>
+Use a comma before <quote>and</quote> in compound sentences, &eg;
+<quote>Use the left mouse button to select and copy text, and the
+middle mouse button to paste it.</quote></para>
+</listitem>
+<listitem>
+<para>Keep to logical sentence order.</para>
+<para>For example, <quote>&konqueror; is a web browser with the
+ability to browse file systems and it includes a javascript
+interpreter.</quote> (Do you see why this is awkward?)</para>
+</listitem>
+<listitem>
+<para>Try not to use the same word several times in the same sentence.
+An exception to this, is an application command or technical word,
+where this repetition is necessary, and improves clarity.</para>
+</listitem>
+<listitem>
+<para>Do not start sentences with any of <quote>and,</quote>
+<quote>so,</quote> <quote>but,</quote> <quote>because,</quote> or
+<quote>however.</quote></para>
+</listitem>
+<listitem>
+<para>Try to avoid contractions, rather spell out both words; &eg;,
+<quote>it is</quote> rather than <quote>it's</quote>; <quote>can
+not</quote> rather than <quote>can't</quote></para>
+</listitem>
+<listitem>
+<para>There is no need to worry about simple text formatting such as
+leaving two spaces after punctuation or indenting paragraphs. This is
+all handled by DocBook &XML; and the <acronym>XSLT</acronym>
+stylesheets in use.</para>
+</listitem>
+</itemizedlist>
+</para>
+
+<para>Remember, we have also an active proofreading team, and there is
+always someone to help you with grammar, so just
+write and have fun!</para>
+
+
+</sect1>
+
+<sect1 id="guidelines-include">
+<title>What to Include</title>
+<para>For most applications, a structure something like this would be
+appropriate:
+<orderedlist>
+<listitem>
+<para>Introduction: A basic description of what the application does and
+any noteworthy features, &etc;.</para>
+</listitem>
+<listitem>
+<para>Using <replaceable>KApp</replaceable>: Task-based description of
+the most common uses of the application.</para>
+</listitem>
+<listitem>
+<para>Program reference: Description of all of the features of the
+application. This would usually include a menu reference, but might also
+include command line options, syntax description, &etc;, if they are
+appropriate to the application.</para>
+<para>This is required for all &tde; applications that you at a minimum
+cover any application specific menu entries, and strongly recommended
+that you cover all the standard ones too (in case users are reading the
+manual outside of &tde;, or yours happens to be the first one they read,
+and it provides consistency.  Cut and paste is your friend here.)</para>
+<para>Note that although this is a required section, and for some
+applications it is the only section, it should be considered a
+minimum.</para>
+</listitem>
+<listitem>
+<para>Frequently Asked Questions: List the most common questions and
+problems that users have with the application, and their
+solutions. <quote>How do I ...?</quote>-type questions are especially
+appropriate.</para>
+</listitem>
+<listitem>
+<para>Credits and License: A list of those who contributed to the
+documentation, and a link to the &GNU; Free Documentation License, under
+which all &tde; documentation is licensed.</para>
+<para>This chapter is required for all &tde; documents, and must have
+<emphasis>at least</emphasis> the two license links (one for the
+document, and one for the application)</para>
+</listitem>
+<listitem>
+<para>Installation: This chapter can be automatically generated,
+provided that the application follows the usual &tde; compilation
+procedure (&ie; <command>./configure</command>, <command>make &amp;&amp; make
+install</command>). If you need to add extra information about compiling
+or installing the application, it can go here.</para>
+</listitem>
+</orderedlist>
+</para>
+
+<para>You will find a template document with these sections in
+<filename>trunk/KDE/kdelibs/kdoctools/template.docbook</filename> file in &tde;
+&svn; repository.</para>
+</sect1>
+
+</chapter>
+
+<chapter id="writing-docs">
+<title>Writing Documentation: Procedures and Tools</title>
+
+<para>If you're worried about having to learn a lot of new tools and
+procedures in order to write documentation, you don't need to,
+because the information we've covered so far is everything you need to
+know to be able to contribute. Although we <emphasis>do</emphasis> have
+some tools we use and procedures we follow, it's not vital that everyone
+knows them in detail, especially when starting out.</para>
+
+<para>For example, all
+&tde; documentation is written in DocBook &XML;, but we're very happy to
+receive documentation written in plain text. There are people on the
+documentation team who are very familiar with DocBook, and can easily
+add the markup if the content is there.</para>
+
+<para>Another example: if you are starting to document an application from
+scratch, you don't need to get the sources of the current documentation. But
+if you are starting from existing documentation, you don't need to know
+about how to get the sources, there are other means to do that.</para>
+
+<para>Of course, if you want to learn about DocBook, you can. After a
+little practice, you will probably find that it's not as hard as it
+looks. And if you learn about dealing with a &svn; repository, you will
+be able to integrate yourself to the regular &tde; development process
+(upload your changes, work together with other developers, &etc;)
+</para>
+
+ 
+<sect1 id="getting-the-sources">
+<title>Getting the Documentation Sources</title>
+
+
+<note><para>If you are starting your document from scratch, you probably do not
+need to read this section, and may start working right now.
+</para></note>
+
+<para>
+You are welcome to use plain text to contribute to &tde; documentation.
+It is a great way to start, and we strongly encourage it.
+If you will miss the power of the DocBook format as
+you improve your documentation skills, then you can learn it. In the mean
+time, someone will manually edit the plain text to add the DocBook
+markup and commit it to &tde; &svn; repository, removing the burden of doing most of the
+more complex stuff covered in this very guide. We'll take a look at writing in
+DocBook and using &svn; later in this document, so if you're interested, read on,
+but if you want to use plain text, you can go directly to
+<xref linkend="getting-plain-text" />.
+</para>
+
+<para>Documentation for &tde;, like the rest of the source code, is kept
+in a &svn; repository. &svn; provides a way for
+many developers to work on the same source code (or in our case, the
+same documentation), and has many useful features to help with this. For
+example, previous versions of every file are saved so that any mistakes
+can be quickly backed out, if they can't be easily corrected.</para>
+
+<para>The basic principle behind &svn; is simple: one server stores a
+definitive copy of the files making up a project. This is known as the
+<firstterm>repository</firstterm>. Each developer can download the files to make
+their own private copy, named <firstterm>working copy</firstterm> or
+<firstterm>sandbox</firstterm>. Using &svn;, the developers can upload their
+modifications to the main repository (a process called &quot;committing&quot;)
+or update their own copy to reflect recent changes made by others.
+</para>
+
+<para>There are two main ways edit the contents of a &tde; document you
+want to improve: using plain text or DocBook.</para>
+
+
+<sect2 id="getting-plain-text">
+<title>Working with plain text sources</title>
+
+<para>
+The <ulink url="http://docs.kde.org/index_head.html">docs.kde.org
+website</ulink> displays most of the &tde; documentation in &HTML; format, updated
+daily from the &svn; repository. There are two versions available in the website: the
+<ulink url="http://docs.kde.org/">stable version</ulink> and the
+<ulink url="http://docs.kde.org/index_head.html">&tde; from &svn; version</ulink>.
+You will always use the latest version of the documentation, &ie; the
+<ulink url="http://docs.kde.org/index_head.html">&tde; from &svn; version</ulink>.
+</para>
+<para>
+The <ulink url="http://docs.kde.org/index_head.html">docs.kde.org
+website</ulink> presents a quick and easy method of retrieving
+the latest version of the &tde; documentation. Clicking the name of the
+application you want to document in the list will open the documentation in
+your web browser. Simply copy the text from the website to your favorite
+text editor, edit it , and submit the results in
+plain text to the &tde; Documentation mailing list,
+<email>kde-doc-english@kde.org</email>. Please note that not all &tde;
+applications are listed there. If you cannot find the documentation of
+the application you want to work with, then you can request it by sending a
+message to the &tde; Documentation mailing list.
+</para>
+
+<para>
+Now you know everything you need to start working. When you are
+finished writing, you may want to read <xref linkend="other-tasks" />. Have fun!
+</para>
+
+</sect2>
+
+<sect2 id="getting-docbook">
+<title>Retrieving the DocBook sources</title>
+
+<para>
+The latest DocBook sources are located inside the &tde; repository.
+Now you need to find and retrieve them.
+</para>
+<para>
+The software inside the &tde; repository is divided into
+<firstterm>modules</firstterm>, which are used to organize the different
+software projects inside the repository. Modules are the top-level folders in the
+&svn; repository folder tree, and each one contains a group of related
+applications. These modules are sometimes released in binary
+form as <firstterm>packages</firstterm>. If you know the name of the package
+your application belongs to, you probably know the module name as well, as
+they are frequently the same. You need to know in which module your application
+is, to retrieve its DocBook sources. For instance, &kmail; is in the
+tdepim module, &quanta; in the tdewebdev module, &cervisia; in the tdesdk module
+and so on. If you need any help in this process, don't hesitate to ask. Each
+module contains a folder named &quot;doc&quot;, and inside it, you can find the
+DocBook sources.
+</para>
+
+<para>
+To access the repository, you can use the <command>svn</command> command line application<!--,
+the &cervisia; application--> or browse the <ulink url="http://websvn.kde.org">&tde; WebSVN website (websvn.kde.org)</ulink>.
+</para>
+
+<para>The <ulink url="http://websvn.kde.org">websvn.kde.org</ulink> is a
+web
+based representation of the contents of the &svn; repository. It is easy
+to download files using <ulink url="http://websvn.kde.org">websvn.kde.org</ulink>,
+the operating system or desktop you use does not matter.
+</para>
+
+<para>
+Retrieving your own working copy of the repository has many advantages. You
+will be able to use your working copy to create files containing the changes you
+made, to update your copy with changes made by other documenters, and if you get
+a &tde; &svn; account, to upload your changes directly to the repository.
+But this is out of the scope of this section. Here we will show you simply
+how to retrieve the sources using &svn;<!-- or &cervisia,;--> the easiest way we can.
+You can get more information about these tools (they are really useful)
+by reading the <xref linkend="managing-svn" />.</para>
+
+<procedure>
+<title>Retrieving documentation sources using WebSVN</title>
+
+<step><para>
+Go to <ulink url="http://websvn.kde.org">http://websvn.kde.org</ulink>
+using your favorite web browser. Let's suppose you are looking for
+&cervisia;'s documentation sources.
+</para></step>
+
+<step><para> The &tde; repository is divided into <quote>trunk</quote>
+(also known as HEAD, where development is going on,
+<quote>branches</quote>, where both stable and working branches live,
+and <quote>tags</quote>, where you can retrieve snapshots of sources at
+a release.  Most work for documentation goes on in <quote>trunk</quote>,
+so click there.</para></step>
+
+<step><para>The main &tde; modules are in the <quote>TDE</quote> folder,
+so click on that.
+</para></step>
+
+<step><para>
+Click the &quot;trunk&quot; link to get the main branch listing. Click on &quot;TDE&quot;
+to get the list of modules from a &tde; release.
+</para></step>
+
+<step><para>
+&cervisia; is part of the tdesdk module (&tde; software
+development kit module). Therefore, click the <quote>tdesdk</quote> item on the
+list. The contents of the tdesdk module will be displayed.
+</para></step>
+
+<step><para> Click the <quote>doc</quote> item on the list, to see the
+contents of the documentation folder of the module. The contents of the
+doc (documentation) folder will be displayed.  </para></step>
+
+<step><para>
+Select the application you want to work with from
+the list (in our case, <quote>cervisia</quote>). All &cervisia;'s
+documentation source files will be displayed, being images or DocBook files.
+</para></step>
+
+<step><para>
+Now you reached the list of files that are part of
+&cervisia;'s documentation, including
+images and DocBook sources. The DocBook sources are files in the format
+<filename class="extension">*.docbook</filename>. In this case, there is only
+one file file in this format: <filename>index.docbook</filename>. Click this
+file on the list. A list of <firstterm>revisions</firstterm> (versions)
+of that file will be displayed.
+</para></step>
+
+<step><para>
+Click the <quote>download</quote> link from the revision on the top of
+the list. It is the most recent one. Save the file. Repeat this process
+with all the files you want to download.
+</para></step>
+</procedure>
+
+<para>
+We use &kmail;'s documentation sources as example in the
+following procedures.
+</para>
+
+<procedure>
+<title>Retrieving documentation sources using &svn;</title>
+
+<step><para>
+Check if you have the &svn; client installed (hint: enter <command>svn</command> in the
+terminal screen). If not, install the &svn; package using the tools provided by
+your distribution.
+</para></step>
+
+<step><para>
+Now it is time to download, or <firstterm>checkout</firstterm> the sources.
+Using &svn;, type in the terminal:
+<programlisting>mkdir <replaceable>path/to/working/folder</replaceable>
+cd <replaceable>path/to/working/folder</replaceable>
+svn checkout svn://anonsvn.kde.org/home/kde/<replaceable>trunk/KDE/module</replaceable>/doc/<replaceable>application</replaceable>
+</programlisting>
+where <replaceable>path/to/working/folder</replaceable> is the folder you want
+to install the sources in your system, <replaceable>trunk/KDE/module</replaceable> is the
+application's module location in the repository and <replaceable>application</replaceable> is the
+application name. Remember to use small caps to type the application and
+module names. In our example, &kmail; is in the tdepim module, so you would
+enter:
+<programlisting>svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/kdepim/doc/kmail
+</programlisting>
+Note that only applications which are part of a regular &tde; release are under
+<replaceable>trunk/KDE/</replaceable>. <application>Amarok</application> docs, for instance, is in the
+multimedia module of extragear. Extragear is contains mature applications which are
+not part of a &tde; release. To get <application>Amarok</application> docs, type in the terminal:
+
+<programlisting>svn checkout svn://anonsvn.kde.org/home/kde/trunk/extragear/multimedia/doc/amarok
+</programlisting>
+</para></step>
+</procedure>
+
+<!--FIXME: update this section when Cervisia has svn support
+
+<procedure>
+<title>Retrieving documentation sources using &cervisia;</title>
+
+<step><para>
+Check if you have the &svn; and tdesdk &cervisia;
+applications installed. If not, install the &svn; and tdesdk packages using the
+tools provided by your distribution.
+</para></step>
+
+<step><para>
+It is not really necessary to set up cervisia to download the sources, but you
+may want to do that if you want to do more. For more information about setting
+up &cervisia;, see <xref linkend="managing-svn" />.
+</para></step>
+
+<step><para>
+To store the repository location using &cervisia;, choose the
+<menuchoice><guimenu>Repository</guimenu>
+<guimenuitem>Repositories...</guimenuitem></menuchoice> menu item. Click the
+<guilabel>Add...</guilabel> button. Enter <quote><replaceable>:pserver:anonymous@anoncvs.kde.org:/home/kde</replaceable><quote>
+in the <guilabel>Repository:</guilabel> edit box. Press <guibutton>OK</guibutton>.
+You will see the repository you just entered on the repositories list.
+
+<figure id="screenshot-repositories" float="1">
+<title>A screenshot of &cervisia;'s Configure Access to Repositories dialog</title>
+<mediaobject>
+<imageobject><imagedata format="PNG" fileref="cervisia-repository.png"/></imageobject>
+<textobject><phrase>A screenshot of &cervisia;'s Configure Access to
+Repositories dialog</phrase></textobject>
+</mediaobject>
+</figure>
+</para>
+
+<para>Now you need to login. Select the repository on the list and press the
+<guilabel>Login...</guilabel> button. A pop-up dialog will appear. Just press
+<keycap>enter</keycap>.</para>
+
+<para>If the <guilabel>Status</guilabel> column entry shows
+<guilabel>Logged in</guilabel> instead of <guilabel>Not logged in</guilabel>,
+it means you successfully configured the &tde; repository location in &cervisia;.
+</para></step>
+
+<step><para>
+Now it is time to download, or <firstterm>checkout</firstterm> the sources.
+Choose the <menuchoice><guimenu>Repository</guimenu>
+<guimenuitem>Checkout...</guimenuitem></menuchoice> menu item.
+
+<figure id="screenshot-checkout" float="1">
+<title>A screenshot of &cervisia;'s Checkout dialog</title>
+<mediaobject>
+<imageobject><imagedata format="PNG" fileref="cervisia-checkout.png"/></imageobject>
+<textobject><phrase>A screenshot of &cervisia;'s Checkout dialog</phrase></textobject>
+</mediaobject>
+</figure>
+</para>
+
+<para>
+Select the &tde; repository location in the <guilabel>Repository:</guilabel>
+drop down box. Enter in the <guilabel>Module:</guilabel> edit box the location
+of the documentation sources, in the form  <quote><replaceable>module</replaceable>/doc/<replaceable>application</replaceable><quote>,
+where <replaceable>module</replaceable> is the
+application's module name and <replaceable>application</replaceable> is the
+application name. In our example, since &kmail; is in the tdepim module, you
+should enter <quote><replaceable>tdepim</replaceable>/doc/<replaceable>kmail</replaceable><quote>.
+Enter in the <guilabel>Working folder:</guilabel> edit box
+the folder under which the sources should be downloaded. Press
+<guilabel>OK</guilabel>.
+</para></step>
+</procedure>-->
+
+</sect2>
+</sect1>
+
+<sect1 id="quanta">
+<title>&quanta;</title>
+
+<para>
+&quanta; is a friendly editor for <acronym>SGML</acronym> and &XML;
+documents. &quanta; features syntax highlighting, autocompletion, autoclosing
+and code folding for DocBook tags, easy access for the &tde; documentation
+tools, <link linkend="using-meinproc">&meinproc;</link> and
+<link linkend="using-checkxml">&checkxml;</link>.
+</para>
+
+<screenshot id="screenshot-quanta">
+<screeninfo>A screenshot of &quanta;'s main window</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="quanta.png" format="PNG"/></imageobject>
+<textobject><phrase>A screenshot of &quanta;'s main window</phrase></textobject>
+<caption><para>A screenshot of &quanta;'s main window</para></caption>
+</mediaobject>
+</screenshot>
+
+<para>
+Some of the tools available for DocBook editing are the document
+structure sidebar, tag editor sidebar and, starting with &quanta; 3.4 (which
+is part of &tde; 3.4), &quanta; offers a DocBook toolbar, complete with table
+and list wizards, ui elements, admonitions, &tde; tools and other standard
+tags. While &quanta; offers a visual page editor for html and xhtml
+pages, there is no support yet for DocBook visual editing. We highlight here
+some of these features.
+</para>
+
+
+<variablelist>
+
+
+<varlistentry>
+<term>DocBook Toolbars</term>
+
+<listitem><para>
+The DocBook toobars offer easy access to the most common DocBook tags,
+plus the list, table and image wizards. You can check your DocBook document
+using the <inlinemediaobject><imageobject>
+<imagedata fileref="xmlval.png" format="PNG"/></imageobject>
+</inlinemediaobject><guibutton>checkXML</guibutton> button from the
+<guilabel>Tools</guilabel> toolbar: the output of the script will be displayed
+in he <guilabel>Messages</guilabel> sidebar, in the bottom of &quanta;'s main
+window. If there is no output, that usually means no errors.
+To process the DocBook into html files, use the
+<inlinemediaobject><imageobject>
+<imagedata fileref="" format="PNG"/></imageobject>
+</inlinemediaobject><guibutton>meinproc</guibutton> button on the same toolbar.
+</para>
+
+<note><para>
+Depending on the version of some XML utilities used by &quanta;, the
+<inlinemediaobject><imageobject>
+<imagedata fileref="xmlval.png" format="PNG"/></imageobject>
+</inlinemediaobject><guibutton>checkXML</guibutton> and <inlinemediaobject>
+<imageobject><imagedata fileref="xsltproc.png" format="PNG"/></imageobject>
+</inlinemediaobject><guibutton>meinproc</guibutton> scripts
+can present bugs. Starting from the upcoming &tde; 3.4.2 release, these bugs
+will not exist anymore. But until there, if you experience these bugs, (in
+special if &konqueror; is not starting up when using the
+<guibutton>meinproc</guibutton> script or there is no output when using the
+<guibutton>checkXML</guibutton> script, you can get and install the
+<ulink url="http://kde-files.org/content/show.php?content=26654">updated docbook
+scripts from kde-files.org</ulink> to solve these issues.
+</para></note>
+
+<para><screenshot id="screenshot-quanta-toolbars">
+<screeninfo>A screenshot of &quanta;'s DocBook toolbar</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="quanta-toolbars.png" format="PNG"/></imageobject>
+<textobject><phrase>A screenshot of &quanta;'s DocBook toolbar</phrase></textobject>
+<caption><para>A screenshot of &quanta;'s DocBook toolbar</para></caption>
+</mediaobject>
+</screenshot>
+</para>
+</listitem>
+
+</varlistentry>
+
+
+<varlistentry>
+
+<term>Tag Editor</term>
+
+<listitem><para>
+The tag or attributes editor is located on the right sidebar, and it shows
+the available attributes for the tag which is currently being edited.
+The tag editor helps you to edit the attributes for the current tag: just click
+on the <guilabel>Value</guilabel> column of any attribute to edit it.
+</para>
+
+<para><screenshot id="screenshot-quanta-tag">
+<screeninfo>A screenshot of &quanta;'s attribute editor sidebar</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="quanta-tag.png" format="PNG"/></imageobject>
+<textobject><phrase>A screenshot of &quanta;'s attribute editor sidebar</phrase></textobject>
+<caption><para>A screenshot of &quanta;'s attribute editor sidebar</para></caption>
+</mediaobject>
+</screenshot>
+
+</para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+
+<term>Documentation Sidebar</term>
+
+<listitem><para>
+Another useful feature is the documentation sidebar, which allows you to
+download and use documentation packages as offline reference. This guide is
+also available offline, using &quanta;'s documentation
+sidebar. Just grab and install the
+<ulink url="http://kde-files.org/content/show.php?content=26176">&tde; Doc
+Primer documentation package</ulink>. The documentation sidebar is on the right
+side of the main window.
+</para>
+
+<para><screenshot id="screenshot-quanta-doc-primer">
+<screeninfo>A screenshot of &quanta;'s documentation sidebar</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="quanta-doc-primer.png" format="PNG"/></imageobject>
+<textobject><phrase>A screenshot of &quanta;'s documentation sidebar</phrase></textobject>
+<caption><para>A screenshot of &quanta;'s documentation sidebar, showing the
+&tde; Doc Primer</para></caption>
+</mediaobject>
+</screenshot>
+
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+
+<term>Entities Autocompletion</term>
+
+<listitem><para>
+&quanta; offers autocompletion for entities. However, this feature is
+hardly useful without the &tde; entities definitions. To generate the entities
+list for the &tde;, follow the procedure below:
+</para>
+
+<note><para>
+The autocompletion feature still has some bugs in the 3.4.1 release.
+These bugs are fixed, and will be available starting from the 3.4.2 release.
+</para></note>
+
+<procedure>
+<title>Generating and installing the <filename>entities.tag</filename> file</title>
+
+<step><para>
+Open &quanta;. Choose the <menuchoice><guimenu>DTD</guimenu>
+<guimenuitem>Load &amp; Convert DTD</guimenuitem></menuchoice> menu item.
+</para></step>
+
+<step><para>
+Now, we have to select the right dtd file to convert.
+On the dialog, select the &tde; installation folder (usually
+<filename class="directory">/usr</filename> or
+<filename class="directory">/opt/trinity</filename>. If you cannot find it, type
+<screen><prompt>$</prompt><userinput>tde-config --prefix</userinput></screen>
+on a terminal application. The dtd file we want is named
+<filename>kdex.dtd</filename> under
+<filename class="directory">share/apps/ksgmltools2/customization/dtd/</filename>.
+Select it and press <guibutton>OK</guibutton>. A new Document Type Editing
+Package (DTEP) for kdex will be created.
+</para></step>
+
+<step><para>
+Now that you have converted the dtd, you can either use it directly,
+by choosing the <menuchoice><guimenu>DTD</guimenu>
+<guimenuitem>Change the DTD...</guimenuitem></menuchoice> and selecting the
+kdex dtd. But the best solution is to install the
+<filename>entities.tag</filename> file for automatic use with the &tde;
+docbook dtds.
+</para></step>
+<step><para>
+Now, let's copy the file from the kdex dtep to the kde-docbook
+dtep. You can use a console application or a file manager to perform this action.
+These locations are under the <filename class="directory">TDEHOME</filename>
+folder, the folder that contains your &tde; settings and application data,
+usually, <filename class="directory">~/.trinity</filename>. If you cannot find it, type
+<screen><prompt>$</prompt><userinput>tde-config --localprefix</userinput></screen>
+on a terminal application. The dtep folder is under
+<filename class="directory">TDEHOME/share/apps/quanta/dtep</filename>.
+The simplest way to do copy it is using a terminal application (&eg; &konsole;).
+</para></step>
+
+<step><para>
+Start a console application and enter the command:
+<screen><prompt>$</prompt><command>cp `tde-config --localprefix`/share/apps/quanta/dtep/kdex/entities.tag `tde-config \
+--localprefix`/share/apps/quanta/dtep/kde-docbook-4.1.2/entities.tag</command></screen>
+</para></step>
+
+<step><para>Restart &quanta;.</para></step>
+
+</procedure>
+
+<para>
+<screenshot id="screenshot-quanta-entities">
+<screeninfo>A screenshot of &quanta;'s entities auto-completion feature</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="quanta-entities.png" format="PNG"/></imageobject>
+<textobject><phrase>A screenshot of &quanta;'s entities auto-completion feature</phrase></textobject>
+<caption><para>A screenshot of &quanta;'s entities auto-completion feature</para></caption>
+</mediaobject>
+</screenshot>
+</para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+
+<term>Document Structure</term>
+
+<listitem><para>
+finally, the document structure displays the logical representation of your
+document. By left mouse button clicking on an element, your cursor will taken
+to the element's position in the document. By right mouse button clicking on an
+element, you are presented with a number of actions that deal with navigating
+and updating the tree.
+</para>
+
+<para><screenshot id="screenshot-quanta-structure">
+<screeninfo>A screenshot of &quanta;'s document structure sidebar</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="quanta-doc-structure.png" format="PNG"/></imageobject>
+<textobject><phrase>A screenshot of &quanta;'s document structure sidebar</phrase></textobject>
+<caption><para>A screenshot of &quanta;'s document structure sidebar</para></caption>
+</mediaobject>
+</screenshot>
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>
+&quanta; is part of the tdewebdev module, which is released as part
+of &tde;. Binary packages are available for the majority of the
+distributions. Quanta can be easily extended to support custom scripts,
+toolbars and documentation sidebars. For more information, check the
+application handbook.
+</para>
+
+</sect1>
+
+<sect1 id="kate">
+<title>&kate;</title>
+
+<para>
+&kate; is an extensible and powerful text editor which is part of the
+tdebase module. &kate; can syntax highlight DocBook documents out of the box,
+and is generally a very powerful editor, but you can get even more
+XML specific functionality installing the XML plugin for &kate;.
+</para>
+
+<procedure>
+<title>Installing the XML plugin for &kate;</title>
+
+<step><para>
+The XML plugin for &kate; is available as part of the tdeaddons module, which
+is released as part of &tde;. Binary packages are available for the majority of
+the distributions. Install the binary package using your distribution tools or
+compile tdeaddons to install the plugin.
+</para></step>
+
+<step><para>
+Open the <guilabel>Configure &kate;</guilabel>
+dialog by choosing the 
+<menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure &kate;...</guimenuitem></menuchoice> menu item.
+</para></step>
+
+<step><para>
+Select the <guilabel>Plugins</guilabel> item from the
+<guilabel>Application</guilabel> tree. Check the <guilabel>&kate; XML
+Completion</guilabel> and the <guilabel>&kate; XML Validation</guilabel> boxes.
+</para>
+
+<screenshot id="screenshot-kate-plugin-config">
+<screeninfo>A screenshot of &kate;'s Plugin Manager Configure
+Dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="kate-plugin.png" format="PNG"/></imageobject>
+<textobject><phrase>A screenshot of &kate;'s Plugin Manager Configure
+Dialog</phrase></textobject>
+<caption><para>A screenshot of &kate;'s Plugin Manager Configure
+Dialog</para></caption>
+</mediaobject>
+</screenshot>
+</step>
+
+<step><para>
+Press <guibutton>OK</guibutton>.
+</para></step>
+
+</procedure>
+
+<para>
+With the XML plugin for &kate; installed, you will have autocompletion,
+autoclosing for DocBook tags and entities. Since &tde; documentation uses
+entities widely, this is a very welcome feature. Additional XML tools will be
+available trough the <guimenu>XML</guimenu> menu (in special, trough the
+<guimenuitem>Validate XML</guimenuitem> menu item, which will allow you to
+check your DocBook documents). The output of this action will appear in the
+<guibutton>XML Checker Output</guibutton> button in the side bar located in
+the lower part of &kate;'s main window.
+</para>
+
+<screenshot id="screenshot-kate-validate-xml">
+<screeninfo>A screenshot of &kate;'s Main Window showing the XML Checker
+Output</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="kate-validate-xml.png"
+format="PNG"/></imageobject>
+<textobject><phrase>A screenshot of &kate;'s Main Window showing the XML Checker
+Output</phrase></textobject>
+<caption><para>A screenshot of &kate;'s Main Window showing the XML Checker
+Output</para></caption>
+</mediaobject>
+</screenshot>
+
+</sect1>
+
+
+<sect1 id="emacs-and-psgml">
+<title>Emacs and Psgml</title>
+<para>The venerable &Emacs; editor has a powerful
+<acronym>SGML</acronym> and &XML; editing mode called psgml. The price
+of this power is a steeper learning curve than the other editors, so if
+you haven't used &Emacs; before, you will probably want to try the other
+editors first. If, on the other hand, you're already familiar with
+&Emacs;, then psgml is your best choice.</para>
+
+<para>Installation of psgml is beyond the scope of this document, but it
+should simply be a case of installing appropriate packages for your
+distribution. The relevant configuration for &tde;-related documentation
+is simple. Just tell psgml where the &tde; catalog files are located
+with the following line in your <filename>.emacs</filename> file:
+<programlisting>
+(setq sgml-catalog-files 
+  (list "CATALOG" "<replaceable>TDEDIR</replaceable>/share/apps/ksgmltools2/customization/catalog"))
+</programlisting>
+where you should replace <replaceable>TDEDIR</replaceable> with the path
+to your &tde; installation. You might also want to use the following
+line to instruct &Emacs; to use psgml to open all <literal
+role="extension">.docbook</literal> files:
+<programlisting>
+(setq auto-mode-alist
+      (cons '("\\.docbook$" . sgml-mode) auto-mode-alist))
+</programlisting>
+</para>
+
+<para>There are of course plenty of other settings in psgml mode which
+you can change to your taste: see the psgml <command>info</command>
+documentation for more details. A sample <filename>.emacs</filename>
+file, with some customizations useful for writing &tde; documentation,
+can be found at <ulink
+url="http://people.fruitsalad.org/phil/kde/dot-emacs-psgml">http://people.fruitsalad.org/phil/kde/dot-emacs-psgml</ulink>.</para>
+
+<para>Some basic keystrokes in psgml are:
+
+<variablelist>
+
+<varlistentry>
+<term><keycombo action="seq"><keycombo action="simul">&Ctrl;<keycap>C</keycap>
+</keycombo><keycap>/</keycap></keycombo></term>
+<listitem><para>End current element. This inserts an end tag for the
+currently open element.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><keycombo action="simul"><keycap>Meta</keycap><keysym>Tab</keysym>
+</keycombo></term>
+<listitem><para>Completes the current tag or entity,
+context-sensitively. This will only complete on tags that are allowed at
+the current point in the document. Note that, because indentation is
+rarely used in &tde; documentation, it is generally safe to remap this
+function to just the <keysym>Tab</keysym> key.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><keycombo action="seq">
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
+<keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo>
+<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo>
+</keycombo></term>
+<listitem><para>Fold current element. This compresses the current
+element so that only the starting tag appears. One use of this is to
+fold all the <sgmltag>chapter</sgmltag> elements in a document, to get
+an overview of the document on one screen, and make navigation around a
+long document easier. You can unfold elements with the shortcut <keycombo action="seq">
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
+<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo>
+<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo>
+</keycombo>.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+
+<para>One particularly useful psgml feature that isn't well documented
+is the sgml-parent-document variable. Setting this variable
+appropriately tells psgml that this file is part of a larger
+document. This enables the full range of psgml features for this file,
+such as context-sensitive element completion. To use this feature, place
+the following in a comment at the end of the child file (with the
+arguments adjusted appropriately):
+<programlisting>
+Local Variables:
+sgml-parent-document:("index.docbook" "book" "chapter")
+End:
+</programlisting>
+The first argument is the name of the parent file (which will almost
+always be <filename>index.docbook</filename> in &tde;
+documentation). The second argument is the top-level (or
+<quote>root</quote>) element of the whole document (&ie;, in the parent
+file). The third argument is the top-level element in this file.</para>
+
+</sect1>
+
+
+
+<sect1 id="check-docs">
+<title>Checking and Viewing the Documents</title>
+<para>There are a couple of &tde;-specific tools for manipulating
+DocBook files, namely &meinproc; and
+&checkxml;. &checkxml; (as the name
+suggests) is used to check that documents are valid, well-formed
+&XML;, and &meinproc; converts DocBook files to
+&HTML;. Here's some hints on using each of them:</para>
+
+<sect2 id="using-checkxml">
+<title>Using &checkxml;</title>
+
+<para>&checkxml; is a simple command with only one argument: the file to
+check. However, the output can be a bit daunting, since one small
+mistake can cause a cascade of errors. The trick is to look at the first
+error, fix that error, save the file, and run &checkxml; again. Often,
+fixing that one error will get rid of all the other error messages. When
+running &meinproc;, the same procedure applies.</para>
+<!-- TODO: Some common errors and how to fix them -->
+
+<para>Most errors in DocBook sources fall into one of a few
+categories. Here are descriptions of some of the most common errors and
+their solutions:</para>
+
+<variablelist>
+
+<varlistentry>
+<term>Opening and ending tag mismatch</term>
+<listitem>
+<screen>
+<computeroutput>
+index.docbook:880: parser error : Opening and ending tag mismatch: para 
+line 879 and sect2
+&lt;/sect2&gt;
+        ^
+</computeroutput>
+</screen>
+
+<para>This is possibly the most common type of error. It's
+caused either by an element that hasn't been closed, or by tags that
+overlap. The error above was generated by the following markup:
+<programlisting>
+<markup>
+<![CDATA[
+<sect2>
+...
+878: running &meinproc;, the same procedure applies.</para>
+879: <para>&checkxml; is a simple command with
+880: </sect2>
+...]]>
+</markup>
+</programlisting>
+
+</para>
+
+<para>The <sgmltag class="starttag">para</sgmltag> tag on line 879 has
+not been closed before the <sgmltag class="endtag">sect2</sgmltag> on
+line 880, causing the error. The simple fix in this case is to add a <sgmltag
+class="endtag">para</sgmltag> before the closing <sgmltag
+class="endtag">sect2</sgmltag>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Element does not follow the DTD</term>
+
+<listitem>
+<screen width="80">
+<computeroutput>
+index.docbook:932: element qandaentry: validity error : Element qandaentry content 
+does not follow the DTD, expecting (blockinfo? , revhistory? , question , answer*), got (answer)
+&lt;/para&gt;&lt;/answer&gt;&lt;/qandaentry&gt;
+                             ^
+</computeroutput>
+</screen>
+
+<para>This error is caused by an element in the document not matching
+the requirements of the DocBook <acronym>DTD</acronym> (Document Type
+Definition). The <acronym>DTD</acronym> specifies what each element must
+contain. This list is shown after <errortext>expecting</errortext> in
+the error message. This so-called <quote>content model</quote> is quite
+difficult to understand at first: refer to the Duck Book and the section
+<quote>Understanding Content Models</quote> for full information.</para>
+
+<para>The text after <errortext>got</errortext> shows the content
+actually found in the document.</para>
+
+<para>In the example above, we have a <sgmltag>qandaentry</sgmltag>
+which is missing the required <sgmltag>question</sgmltag> element. This
+was generated by the following input:
+<programlisting>
+<markup>
+<![CDATA[
+<qandaset>
+<qandaentry><answer><para>An answer
+</para></answer></qandaentry>
+</qandaset>
+]]>
+</markup>
+</programlisting>
+</para>
+
+<para>Adding a <sgmltag>question</sgmltag> element before the
+<sgmltag>answer</sgmltag> fixes the problem.</para>
+
+<para>An easy mistake to make is to forget to put a
+<sgmltag>para</sgmltag> element around text in, for example, a
+<sgmltag>listitem</sgmltag> or a
+<sgmltag>sect<replaceable>n</replaceable></sgmltag>. This will be shown
+as <errortext>CDATA</errortext> in the <errortext>got</errortext>
+section of the error.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="using-meinproc">
+<title>Using &meinproc;</title> 
+
+<para>The most common way to run &meinproc; is simply as
+
+<screen><userinput>&meinproc; <filename><replaceable>docbook-file</replaceable></filename></userinput></screen> where
+
+<filename><replaceable>docbook-file</replaceable></filename> is usually
+<filename>index.docbook</filename>. This command creates &HTML; pages
+from the DocBook file. Note that these pages are only viewable in
+&tde;-based browsers (like &konqueror;). If you need to view the &HTML;
+output in another browser (for example, if you're placing it on line),
+use 
+
+<screen><userinput>&meinproc; <option>--stylesheet</option> <filename><replaceable>stylesheet-name</replaceable></filename> <filename><replaceable>docbook-file</replaceable></filename>
+</userinput></screen> 
+
+where
+<filename><replaceable>stylesheet-name</replaceable></filename> is the
+full path to one of the &XSL; stylesheets in <filename
+class="directory">$<envar>TDEDIR</envar>/share/apps/ksgmltools/customization</filename>.
+To produce output suitable for the web, you can use
+<filename>tde-web.xsl</filename> or
+<filename>tde-chunk-online.xsl</filename>. See the
+<filename>README</filename> file in that directory for more details.
+</para>
+</sect2>
+
+</sect1>
+
+</chapter>
+
+
+<chapter id="docbook-intro">
+<title>DocBook Introduction</title>
+
+<para>All &tde; documentation is produced in DocBook &XML; format, and
+writers are encouraged to learn it (although it's by no means necessary,
+and we're very happy to receive documentation written in plain
+text). Although DocBook can look somewhat intimidating to beginners, the
+markup is extremely self-descriptive, and many people find it easier
+than &HTML; to learn.</para>
+
+<para>In this chapter, we'll just take a basic overview of the ideas
+behind DocBook. For detailed information about individual tags and so
+on, please see <ulink url="help:/khelpcenter/markup/index.html">
+The TDE DocBook Markup Guide</ulink>.</para>
+
+<sect1 id="docbook-overview">
+<title>Overview</title>
+<para>DocBook is just an application of &XML;, so if you're familiar
+with &XML;, then you'll feel right at home. If not, don't worry, as most
+of the gory details aren't required knowledge for simply writing and
+updating documentation. A DocBook file (and, indeed, any &XML; file)
+consists of plain text, with tags surrounding some text to tell you (or
+a computer) what that text represents. So, a snippet from a DocBook file
+might look like:
+
+<!-- Gah, this needs wordwrapping to look vaguely sensible, but -->
+<!-- fill-mode doesn't love me, and is making it difficult -->
+<programlisting>
+<sgmltag class="starttag">para</sgmltag>To display the clipboard history, click on the <sgmltag class="genentity">klipper</sgmltag> icon
+ in the <sgmltag class="genentity">tde</sgmltag> panel, or press <sgmltag class="starttag">keycombo
+action="simul"</sgmltag><sgmltag
+ class="genentity">Ctrl</sgmltag><sgmltag
+ class="genentity">Alt</sgmltag><sgmltag
+ class="starttag">keycap</sgmltag>V<sgmltag
+ class="endtag">keycap</sgmltag><sgmltag
+ class="endtag">keycombo</sgmltag>. Previous 
+clipboard entries are shown
+ at the top of the pop-up menu which 
+appears.<sgmltag
+ class="endtag">para</sgmltag>
+</programlisting>
+The <sgmltag class="starttag">para</sgmltag> and <sgmltag
+class="endtag">para</sgmltag> show the start and end, respectively, of a
+paragraph. These delimiting marks are called <quote>tags</quote>, and
+the content they contain (along with the tags) is called an
+<quote>element</quote>. The <sgmltag class="starttag">keycombo</sgmltag>
+tag has an extra piece of information specified: <sgmltag
+class="attribute">action="simul"</sgmltag>. This is called an
+<quote>attribute,</quote> and makes the tag more specific. The words
+surrounded by &amp; and ; are <quote>entities</quote>. They're simply
+variables that expand to some other text, and are widely used in &tde;
+documentation. See <xref linkend="kde-specialities"/> for more
+information about entities. Tags, entities, comments and other parts of
+&XML; that aren't simple text are referred to as <quote>markup.</quote>
+</para>
+</sect1>
+
+<sect1 id="content-and-presentation">
+<title>Content and Presentation</title> 
+
+<para>One of the basic principles behind the use of DocBook in &tde; is
+that content and presentation are strictly separated. DocBook files
+contain the content, and &XSL; files contain the information about
+presentation. This has a number of advantages, some of which are:
+<itemizedlist>
+<listitem>
+<para>When writing, you don't have to worry about whether the
+information is well presented, just that the information you're writing
+is correct and readable.</para>
+</listitem>
+<listitem>
+<para>All &tde; documentation has a similar look, so once readers are
+familiar with conventions in one document, they're familiar with all documents.</para>
+</listitem>
+<listitem>
+<para>Documentation is future-proofed, since by providing as much
+information about content as possible, future formats, search engines,
+&etc; are likely to be catered for easily.</para>
+</listitem>
+</itemizedlist>
+</para>
+
+<para>In practice, this means that you should add markup that describes
+what things <emphasis>are</emphasis> and not how they should appear. So,
+in the example above, the <sgmltag class="starttag">keycombo</sgmltag> (a
+keyboard shortcut) tells the reader (or computer) that the keys &Ctrl;,
+&Alt; and <keycap>V</keycap> should be pressed simultaneously, but
+doesn't say anything about how that should be displayed in the final
+output. (In fact, it appears as <quote><keycombo
+action="simul">&Ctrl;&Alt;<keycap>V</keycap></keycombo></quote>, but it
+could equally be converted to <quote>C-M-V</quote> &agrave; la &Emacs;
+or even some other way of showing keyboard shortcuts. What's important
+is that the DocBook source has the <emphasis>information</emphasis>
+necessary to work out what is being referred to.) 
+</para>
+</sect1>
+
+<!-- I'm not sure how necessary this is, since most of the stuff I was -->
+<!-- going to write is alread covered in Chapter 5 of the DocBook -->
+<!-- reference (Phil)-->
+<sect1 id="docbook-structure">
+<title>Structure</title>
+<para> (&lt;book&gt; &lt;chapter&gt; &lt;sectn&gt;
+&lt;para&gt;)</para>
+</sect1>
+
+<sect1 id="kde-specialities">
+<title>&tde; Specialities</title>
+<para>TDE-isms: entities, necessary bits (credits, translation
+		stuff)</para>
+
+<sect2 id="entities">
+<title>Entities</title>
+<para>Entities (which are simply variables which expand to some other
+text) are an important part of DocBook markup, and are used particularly
+widely in &tde; documentation. For example, there are entities defined
+for almost all &tde; applications. Therefore, when referring to, for
+example, &konqueror; in documentation, you should use:
+<programlisting>
+<sgmltag class="genentity">konqueror</sgmltag> is, among other things, a
+web browser.
+</programlisting>
+</para>
+<para>This has several advantages. Firstly, it ensures that applications
+are capitalized and marked-up consistently across all &tde;
+documentation. This means that you don't have to remember whether the
+help center program is KHelpCenter, KHelpcenter or Khelpcenter: the
+entity (which is always entirely lowercase) automatically expands to the
+correct one. 
+<!-- FIXME: there are probably some i18n advantages too, but I don't -->
+<!-- know them offhand --></para>
+
+<para>There are entities defined for several classes of names:
+<variablelist>
+
+<varlistentry>
+<term>All &tde; applications</term>
+<listitem>
+<para>As mentioned before, all &tde;
+applications have an entity. The entity name is in entirely lowercase,
+and expands to the correctly capitalized version of the application
+name. There is also an entity for &tde; itself: <sgmltag
+class="genentity">tde</sgmltag>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Common English and technology abbreviations</term>
+<listitem>
+<para>For example, <quote>&ie;</quote> is written as <sgmltag
+class="genentity">ie</sgmltag> and <quote>&eg;</quote> as <sgmltag
+class="genentity">eg</sgmltag>. This ensures that the same markup and
+capitalization are used for these abbreviations throughout &tde;
+documentation. Technological abbreviations such as &HTTP; and &XML; also
+have entities, which are capitalized as usual (&ie;, <sgmltag
+class="genentity">HTTP</sgmltag> and <sgmltag
+class="genentity">XML</sgmltag> for the previous examples).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Trademarks</term>
+<listitem>
+<para>Names of companies and their products are often trademarked. For
+this reason, it is important to mark them up with the
+<sgmltag>trademark</sgmltag> tag, using the <sgmltag
+class="attribute">class="registered"</sgmltag> attribute if
+necessary. To reduce effort, and ensure that trademarks are given proper
+acknowledgment, many common technology-related trademarks have been
+given entities. For example, the entity <sgmltag
+class="genentity">X-Window</sgmltag> expands to &X-Window;.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Contributor Names</term>
+<listitem>
+<para>Names of contributors to &tde; documentation have entities of the
+form <sgmltag class="genentity">Firstname.Lastname</sgmltag> (or
+<sgmltag class="genentity">Firstname.Initial.Lastname</sgmltag>). Email
+addresses of contributors have entities of the form <sgmltag
+class="genentity">Firstname.Lastname.mail</sgmltag>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Names of special keys</term>
+<listitem>
+<para>Names of keys on the keyboard are always marked up with either
+<sgmltag>keycap</sgmltag> or <sgmltag>keysym</sgmltag>. Since it can be
+difficult to distinguish between these two tags, entities have been
+created for common keys, &eg;, <sgmltag class="genentity">Ctrl</sgmltag>
+and <sgmltag class="genentity">Alt</sgmltag>.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+
+<para>The definitions of these entities can be found in the following
+locations in &tde; <acronym>3</acronym>:
+<variablelist>
+
+<varlistentry>
+<term>Items not requiring translation (&tde; application names,
+technology abbreviations, trademarks)</term>
+<listitem>
+<para><filename>tdelibs/kdoctools/customization/entities/general.entities</filename></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Contributor names and email addresses</term>
+<listitem>
+<para><filename>tdelibs/kdoctools/customization/entities/contributor.entities</filename></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Language-specific terms and key names</term>
+<listitem>
+<para><filename>tdelibs/kdoctools/customization/en/user.entities</filename></para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+
+</sect2>
+
+<sect2 id="necessary-sections">
+<title>Necessary Sections</title>
+<para>There are several sections that appear in all &tde; DocBook files,
+even though they are not required by DocBook itself:
+<itemizedlist>
+<listitem>
+<para>  
+<programlisting>
+&lt;!ENTITY package "tde-module"&gt;
+  &lt;!ENTITY % addindex "IGNORE"&gt;
+  &lt;!ENTITY % English "INCLUDE"&gt;
+</programlisting>
+</para>
+<para>This appears in the prologue immediately after the
+<acronym>FPI</acronym>. See <ulink url="help:/khelpcenter/markup.html/#prologue">prologue</ulink>
+for more details about this section.</para>
+</listitem>
+<listitem>
+<para><programlisting>&lt;!-- TRANS:ROLES_OF_TRANSLATORS --&gt;</programlisting></para>
+<para>This appears after the <sgmltag
+class="starttag">authorgroup</sgmltag> element, and is a required
+placeholder for use in translation (also known as <quote>i18n</quote>
+from the number of letters between the first and the last of the word <quote>internationalization</quote>).</para>
+</listitem>
+</itemizedlist>
+
+
+</para>
+</sect2>
+</sect1>
+
+</chapter>
+
+<chapter id="managing-documentation">
+<title>Sending the New Documents and Changes to &tde;</title>
+
+<para>As part of the wider &tde; project, there are some things that
+documentation writers need to be aware of. There are a large number of
+other developers working on &tde;, and working together with all of them
+is an important part of what we do.</para>
+
+<sect1 id="release-schedule">
+<title>Respecting the Release Schedule</title>
+<para>String freezes, when we write, etc</para>
+
+<warning>
+<para>This needs reviewing by someone who pays more attention to
+releases than I do.</para>
+<!-- TODO cwoelz: OK, I'll do it. -->
+</warning>
+
+<para>The &tde; release process, in which we go from the fast-moving and
+sometimes unstable world of the &tde; &svn; repository, to a stable, polished product, is never
+exactly the same twice, but there are some common features:</para>
+
+<para>A schedule for the next release of &tde; is published at <ulink
+url="http://developer.kde.org">developer.kde.org</ulink>, with the
+definitive guide to what will be happening and when. There will be two
+or more <quote>freezes</quote>, when changes of a certain type are not
+allowed in the &tde; &svn; repository:
+<variablelist>
+<varlistentry>
+<term>Feature Freeze</term>
+<listitem>
+<para>When feature freeze is active, developers are not allowed to
+commit new features to the repository. This is a good time to start writing, since
+the features available in the application during this period are the
+same as the ones which will be available in the released version.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>String Freeze</term>
+<listitem>
+<para>Text strings appearing in the &tde; user interface and in the
+documentation are not allowed to be changed. This is to allow
+translators to provide thorough translations which will match the
+release. We are still considering how to work during this period of
+freeze. One method which we have tried is to continue writing, but hold
+back all changes to be committed in one go, immediately before the
+release.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+</sect1>
+
+<sect1 id="managing-svn">
+<title>Managing the Sources with &svn;</title>
+
+<para>You can find detailed information about how to use &svn; in conjunction
+with &tde; in the <ulink url="http://quality.kde.org/develop/cvsguide/managestep.php">
+Managing &tde; Sources with Subversion guide</ulink></para>
+
+</sect1>
+
+<!-- FIXME: Thinking better, we must decide if we remove this and simply
+link to the quality site, or keep it. Better remove it.
+
+<sect2 id="svn-checking-out">
+<title><quote>Checking Out:</quote> Getting a copy of the &tde;
+sources</title>
+<para>The first stage in using &svn; is to make your own copy of the &tde;
+source. This is known as <quote>checking out.</quote> To do this, make
+sure the &svn; client is installed on your system, and follow these steps (from
+<ulink url="http://developer.kde.org">developer.kde.org</ulink>):
+<orderedlist>
+<listitem><para>Install the following file as <filename>~/.cvsrc</filename>: 
+<programlisting>cvs -z4 -q
+diff -u3 -p
+update -dP
+checkout -P
+</programlisting>
+</para>
+<para>Please don't use a higher value than -z4. It just creates
+ unnecessary high load on the server which slows down the access for
+ everybody while it certainly does not increase throughput.
+
+<important><para>The <userinput>update -dP</userinput> is essential. Without this it won't work.</para>
+</important></para>
+</listitem>
+
+<listitem><para>Execute the following commands (if you are not using the
+<application>bash</application> shell, substitute the appropriate
+command for <command>export</command>):
+<screen>
+<userinput><command>export
+#ROOT=:pserver:anonymous@anoncvs.kde.org:/home/kde</command></userinput>
+<userinput><command>cvs login</command></userinput>
+</screen>
+</para>
+
+<para>Just press &Enter; if there is a question about a password. If you
+ don't have a <filename>.cvspass</filename> file in your home directory
+ create one (using <userinput><command>touch
+ ~/.cvspass</command></userinput> - note the dot in
+ <filename>.cvspass</filename>) and run <userinput><command>cvs
+ login</command></userinput> again. 
+</para>
+</listitem>
+
+<listitem>
+<para>Run <userinput><command>cvs co arts tdelibs tdebase
+<replaceable>other modules</replaceable></command></userinput> where
+<replaceable>other modules</replaceable> is a list of the other modules
+you need. <filename>arts</filename>, <filename>tdelibs</filename> and
+<filename>tdebase</filename> are the minimum you will need to run a
+&tde; desktop. If you are writing documentation for applications which
+live in any other modules, you will need to add them to
+<replaceable>other modules</replaceable> in the command above.</para>
+</listitem>
+</orderedlist>
+</para>
+</sect2>
+
+<sect2 id="svn-updating">
+<title>Updating Your Sources</title>
+<para>Keeping your copy of the sources up-to-date with the repository is
+as simple as entering the directory of a module you want to update, and
+entering <userinput><command>cvs up</command></userinput>. Only the differences
+between your copy and the repository are downloaded, so this takes less
+bandwidth than running <userinput><command>cvs co</command></userinput>,
+as you did before.</para>
+
+<para>It's a good idea to run <userinput><command>cvs
+up</command></userinput> before modifying files, since this helps
+prevent conflicts (see below).</para>
+
+<para>Running <userinput><command>cvs up</command></userinput> produces a lot of
+output. Most of it consists of a letter followed by a filename. The
+meanings of the most common letters are:
+<variablelist>
+
+<varlistentry>
+<term><computeroutput>P</computeroutput></term>
+<listitem><para>The file has been updated to the latest version in the
+repository. Only the difference between your last copy and the latest
+version (a patch) was sent.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><computeroutput>U</computeroutput></term>
+<listitem><para>The file has been updated to the latest version in the
+repository, but a patch wasn't available, so the whole file was
+sent. This usually means that the file is new since your last update.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><computeroutput>M</computeroutput></term>
+<listitem><para>The file is modified in your private copy. This means
+you have made changes that haven't yet been committed to the repository.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><computeroutput>C</computeroutput></term>
+<listitem><para>There were changes in both your private copy and the
+repository, and they conflicted with one another. See <xref
+linkend="svn-managing-conflicts" /> for more information.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+There are other letters which might appear: for more information, see
+the CVS <command>info</command> page.</para>
+</sect2>
+
+<sect2 id="svn-committing">
+<title><command>cvs commit</command>: Making your changes
+available</title>
+<para>Once you have made changes to your private copy of the
+documentation, you can add these changes to the repository with the
+<command>cvs commit</command> command. Run <userinput><command>cvs
+commit <replaceable>file...</replaceable></command></userinput> where
+<replaceable>file...</replaceable> is a list of all the files that you
+have modified. You will be presented with an editor (the one set in your
+<envar>EDITOR</envar> environment variable) in which you should enter a
+brief log message describing the changes you've made.</para>
+<para>In the log file you can use <userinput>CCMAIL:<replaceable>email
+address</replaceable></userinput> to automatically send a copy of the
+log message to <replaceable>email address</replaceable>. If the change
+is a small one (for example, correcting a small number of typos), you
+can add CVS_SILENT to the log message. This will allow easier filtering
+for those who read the mailing list to which log messages are sent.</para>
+
+<para>Write something about binary files.</para>
+<para>Mention adding new files.</para>
+
+</sect2>
+
+<sect2 id="svn-managing-conflicts">
+<title>Managing Conflicts and Other Problems</title>
+<para>CVS will try to automatically handle merging two sets of changes
+to a file. For example, take this situation:
+<orderedlist>
+<listitem><para>You and another writer are both working on a file, <filename>index.docbook</filename>.</para>
+</listitem>
+<listitem>
+<para>The other writer makes changes to the first half of the file and
+commits them to the CVS repository.</para>
+</listitem>
+<listitem>
+<para>You make changes to the <emphasis>second</emphasis> half of the
+file, but do not commit them (yet).</para>
+</listitem>
+</orderedlist>
+</para>
+
+<para>Now, if you run <userinput><command>cvs up</command></userinput>,
+<command>cvs</command> will add the changes from the other writer to
+your private copy, while leaving your changes in the file.</para>
+
+<para>This works fine if two writers have made changes to different
+parts of the file, but if you make changes to the same part of the file,
+<command>cvs</command> cannot tell which changes should take
+precedence. It will therefore mark your file as having conflicts (shown
+with a <computeroutput>C</computeroutput> in the output of
+<userinput><command>cvs up</command></userinput>), and place markers in
+the file showing both your version and the version of the other
+writer. You must then read through the file and edit it to contain only
+the more appropriate of the two versions.</para>
+
+<para>Another common problem is that you get errors about <quote>sticky
+tags</quote> when trying to commit a file. If this happens, run
+<userinput><command>cvs up -A</command></userinput> and commit again.</para>
+</sect2>
+
+
+</sect1>
+
+-->
+
+<sect1 id="working-with-others">
+<title>Working With Other Documenters and Developers</title>
+
+<para>One important and fun part of working on &tde; is the community of
+other developers who you work with. The people you'll work with most
+often as a documentation writer are the documentation team, the quality
+team (if you're a new contributor) and the maintainer of the application
+that you're working on.</para>
+
+<para>The documentation team is your main resource for help with doc
+writing and a central point of contact to ensure that everyone's work is
+co-ordinated. The main ways to contact the documentation team are via
+the <email>kde-doc-english@kde.org</email> mailing list and on
+<acronym>IRC</acronym> in the fkde-docs channel on the server
+<systemitem class="domainname">irc.freenode.net</systemitem>. If you
+plan to work on a particular application, please tell us, so that we can
+ensure that no-one else is working on it simultaneously, so that effort
+would be duplicated. Also, feel free to contact us with any problems or
+questions you might have about writing documentation. You don't need to
+feel like you're working entirely on your own &ndash; there are plenty
+of people who are able to help.</para>
+
+<para>The &tde; Quality Team provides  more broad support. If you have
+any general questions about &tde; development, or how documentation fits
+into the wider &tde; environment, the Quality Team mailing list is a
+good place to ask: <email>kde-quality@kde.org</email>. If you're not
+sure whether to ask a question on the kde-quality or kde-doc-english
+list, just pick one and ask. Many people who read one list read the
+other, and you'll be pointed to the appropriate list if
+necessary.</para>
+
+<para>Working with programmers is a little less formal. The usual reason
+to contact a programmer is to ask about a feature or behavior of an
+application that you're documenting. To find the appropriate person to
+contact for a particular application, look in the
+<menuchoice><guimenu>Help</guimenu> <guimenuitem>About
+<replaceable>KApp</replaceable></guimenuitem></menuchoice> menu item for
+the maintainer. If you can't find a maintainer, ask on
+<email>kde-doc-english@kde.org</email> or
+<email>kde-devel@kde.org</email>. If asking on the kde-devel list,
+mention that you're writing the documentation for that application
+&ndash; it helps to identify you to those reading a busy list. In
+general, programmers and other developers are happy to help, and willing
+to work with you, so don't feel afraid of asking them for information,
+and building up a working relationship.</para>
+
+</sect1>
+
+<sect1 id="updating-documentation">
+<title>Updating Documentation</title>
+
+<para>With the pace of change of &tde; applications, documentation can
+rapidly become out-of-sync with the application it is describing. To
+keep its value, documentation needs to be updated. Often this is simply
+a case of reading the existing documentation, and checking each
+description of an item against the latest version of the
+application. For example, are there new items in the menus that are not
+described in the documentation?</para>
+
+<para>Sometimes, more extensive updates are needed. If new features of
+the application significantly change the way it works, then new sections
+of the documentation may be needed, or reorganization of the existing
+content might be necessary. In particularly severe cases, an entire
+rewrite might be necessary.</para>
+
+</sect1>
+
+<sect1 id="licenses">
+<title>Licenses for &tde; Documentation</title>
+
+<para>&tde; uses the <acronym>FDL</acronym> (Free Documentation License) for
+all documentation.  This license has several variants, some of which place
+restrictions on how content is used in other contexts.</para>
+
+<para>The specific terms we use are:</para>
+
+<literallayout>Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.</literallayout>
+
+<para>This is the only version of the license that is safe to use for
+documentation that is to be distributed with &tde;.</para>
+
+<para>The items that may differ in other uses of the <acronym>FDL</acronym>
+are as follows:</para>
+
+<variablelist>
+<varlistentry>
+<term>with no Invariant Sections</term>
+<listitem>
+<para>Invariant sections are, as you might expect, sections that
+<emphasis>must not</emphasis> be altered in any reproduction of the content.
+The reasoning behind this, is so nobody can make a subjective claim, and
+attribute it to you, by altering your words.</para>
+
+<para>For instance, if you say <quote>Foo is a terrible piece of
+software</quote> and the section is marked invariant, the developers of
+<quote>Foo</quote> can not take your writing, change it to say <quote>Foo is
+a great piece of software</quote> and still attribute that opinion to
+you.</para>
+
+<para>For many people, this restriction is incompatible with the
+<acronym>GPL</acronym> and therefore some distributions choose not to
+include any user manuals that contain <quote>Invariant Sections</quote>.
+Since they must be reproduced verbatim, this also means we are not able
+to reuse such content in our own manuals, without including this
+statement.</para>
+
+<para>For this reason, <quote>Invariant Sections</quote> are not permitted
+in documentation that is to be distributed with &tde;, nor can we safely
+reuse content from other sources, if they include Invariant Sections.</para>
+
+<para>It is not normally appropriate to write opinion pieces in &tde;
+documentation. Such content should be restricted to your own website, or
+documentation that is not distributed with &tde;, so the fact we outlaw
+<quote>Invariant Sections</quote> in &tde; documentation is not normally a
+problem.  If you think you have a special case, please raise it with the
+documentation team, and understand that including such sections may prevent
+some distributions adding your manual (or the software itself) to their
+distribution.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>with Front-Cover Texts <replaceable>names of
+sections</replaceable></term><term>with Back-Cover Texts <replaceable>names
+of sections</replaceable></term>
+<listitem>
+<para>As with <quote>Invariant Sections</quote>, these are texts that may
+not be altered, and must be included in any reuse of any of the content.  It
+also means we would have to alter our license to match that of the content
+we have reused.  This leads to similar problems as that of the
+<quote>Invariant Sections</quote>.</para>
+
+<para>This one mainly comes up if we want to use <acronym>FDL</acronym>
+content found from other sources (for instance, books or websites.)  In
+these cases, the best approach is to ask the authors to permit relicensing,
+and offer to include their front/back cover texts anyway, but without having
+to change our license terms.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<warning> 
+<para>The terms of the <acronym>FDL</acronym> as used by &tde;
+documentation, are entirely <acronym>GPL</acronym> compatible, and do
+not restrict the reuse of the content.  Any deviation from these terms,
+or any change in license could restrict distribution of your software or
+documentation, and should only be undertaken with full knowledge of the
+consequences, and with written permission of all copyright
+holders.</para>
+</warning>
+
+</sect1>
+
+<sect1 id="bugs-kde-org">
+<title>Using bugs.kde.org</title>
+<para>Note how we use b.k.o (general to-do items). Also point to Carlos'
+guide on quality.k.o</para>
+
+<para>The &tde; bug tracking system, located at <ulink
+url="http://bugs.kde.org">http://bugs.kde.org</ulink>, is now part of
+the documentation team's toolkit. Issues with the &tde; documentation
+can be filed in the <quote>docs</quote>
+product of the bug tracker. Incorrect or outdated content, missing
+content, outdated screenshots and typos are all appropriate reasons to
+file bugs.</para>
+
+<para>When filing bugs, especially for incorrect or outdated content, be
+specific about what's wrong. For example, if a certain page of a
+configuration dialog is incorrectly documented, say which page it is in
+the bug report. That way, someone fixing the bug can quickly find the
+appropriate part of the application and the documentation, and make the
+necessary changes with a minimum of effort.</para>
+
+<para>For more information on using the &tde; bug tracking system, see
+<ulink
+url="http://quality.kde.org/develop/howto/howtobugs.php">http://quality.kde.org/develop/howto/howtobugs.php</ulink>.</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="other-tasks">
+<title>Leveraging your Newly Acquired Knowledge</title>
+
+<para> After finishing documenting an application,
+you can leverage the knowledge you gained in the process and improve
+the application's level of quality in other areas. The Quality Team provide
+guides on how to perform many of these tasks.</para>
+
+<para><itemizedlist>
+<listitem><para><ulink url="http://quality.kde.org/develop/howto/howtodocs.php">
+Writing context help and configuration descriptions</ulink>: the handbook
+is not the only source of help available for &tde; applications. Context help,
+or <emphasis>whatsthis</emphasis> provides invaluable support for users, and
+you will find it easy to write, especially after writing the handbook.
+Documenting configuration options available through the KConfig framework may
+require additional research, but configuration descriptions are often the only
+documentation available for configuration options.
+<!-- FIXME: Improve wording -->
+</para>
+</listitem>
+<listitem><para><ulink url="http://quality.kde.org/develop/howto/howtoui.php">
+Performing usability analysis and tests</ulink>: to document your applications,
+you probably tested most of the application functionality in a systematic way.
+Please take the time read the guide and report the usability issues and
+suggestions that appeared in the process.</para>
+</listitem>
+<listitem><para><ulink url="http://quality.kde.org/develop/howto/howtopromo.php">
+Writing guides and articles about the application</ulink>: promotion is the key
+for a successful open source project, as widespread use means
+usually more probability of attracting prospect contributors, developers,
+documenters, translators, &etc;.
+</para></listitem>
+</itemizedlist>
+</para>
+
+</chapter>
+
+<chapter id="credits">
+<title>Credits and License</title>
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+</chapter>
+
+<appendix id="widget-names">
+<title>Widget Names</title>
+<para>Steal from (and extend) the <quote>Visual Guide to
+&tde;</quote>.</para>
+
+</appendix>
+
+
+
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+fill-column:72
+End:
+
+vim:tabstop=2:shiftwidth=2:expandtab 
+-->
diff --git a/doc/tutorials/docprimer/kate-plugin.png b/doc/tutorials/docprimer/kate-plugin.png
new file mode 100644
index 0000000..8633ffe
--- /dev/null
+++ b/doc/tutorials/docprimer/kate-plugin.png
diff --git a/doc/tutorials/docprimer/kate-validate-xml.png b/doc/tutorials/docprimer/kate-validate-xml.png
new file mode 100644
index 0000000..5d4e17b
--- /dev/null
+++ b/doc/tutorials/docprimer/kate-validate-xml.png
diff --git a/doc/tutorials/docprimer/quanta-doc-primer.png b/doc/tutorials/docprimer/quanta-doc-primer.png
new file mode 100644
index 0000000..b30f874
--- /dev/null
+++ b/doc/tutorials/docprimer/quanta-doc-primer.png
diff --git a/doc/tutorials/docprimer/quanta-doc-structure.png b/doc/tutorials/docprimer/quanta-doc-structure.png
new file mode 100644
index 0000000..c8bd3bb
--- /dev/null
+++ b/doc/tutorials/docprimer/quanta-doc-structure.png
diff --git a/doc/tutorials/docprimer/quanta-entities.png b/doc/tutorials/docprimer/quanta-entities.png
new file mode 100644
index 0000000..dc2a4a9
--- /dev/null
+++ b/doc/tutorials/docprimer/quanta-entities.png
diff --git a/doc/tutorials/docprimer/quanta-tag.png b/doc/tutorials/docprimer/quanta-tag.png
new file mode 100644
index 0000000..436692e
--- /dev/null
+++ b/doc/tutorials/docprimer/quanta-tag.png
diff --git a/doc/tutorials/docprimer/quanta-toolbars.png b/doc/tutorials/docprimer/quanta-toolbars.png
new file mode 100644
index 0000000..d34a759
--- /dev/null
+++ b/doc/tutorials/docprimer/quanta-toolbars.png
diff --git a/doc/tutorials/docprimer/quanta.png b/doc/tutorials/docprimer/quanta.png
new file mode 100644
index 0000000..6dfb9aa
--- /dev/null
+++ b/doc/tutorials/docprimer/quanta.png
diff --git a/doc/tutorials/docprimer/xmlval.png b/doc/tutorials/docprimer/xmlval.png
new file mode 100644
index 0000000..180729f
--- /dev/null
+++ b/doc/tutorials/docprimer/xmlval.png
diff --git a/doc/tutorials/docprimer/xsltproc.png b/doc/tutorials/docprimer/xsltproc.png
new file mode 100644
index 0000000..54de744
--- /dev/null
+++ b/doc/tutorials/docprimer/xsltproc.png
diff --git a/doc/tutorials/markup/CMakeLists.txt b/doc/tutorials/markup/CMakeLists.txt
new file mode 100644
index 0000000..cebfe1b
--- /dev/null
+++ b/doc/tutorials/markup/CMakeLists.txt
@@ -0,0 +1,9 @@
+#################################################
+#
+#  Improvements and feedback are welcome
+#
+#  This file is released under GPL >= 2
+#
+#################################################
+
+tde_create_handbook( DESTINATION khelpcenter/markup )
diff --git a/doc/tutorials/markup/Makefile.am b/doc/tutorials/markup/Makefile.am
new file mode 100644
index 0000000..4169155
--- /dev/null
+++ b/doc/tutorials/markup/Makefile.am
@@ -0,0 +1,3 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/tutorials/markup/index.docbook b/doc/tutorials/markup/index.docbook
new file mode 100644
index 0000000..fa84114
--- /dev/null
+++ b/doc/tutorials/markup/index.docbook
@@ -0,0 +1,5317 @@
+<?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>&lt;foreignphrase
+lang="de"&gt;Wort&lt;/foreignphrase&gt;</markup>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Underlining and CAPITALIZING entire words are leftovers from the days of
+typewriters. They are no longer appropriate for today's documents.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Do not use quotation marks in your documentation. If you want a word to
+appear within quotation marks, simply enclose it between <sgmltag
+class="element">quote</sgmltag> tags.
+</para>
+<informalexample>
+<para>
+This software is provided <markup>&lt;quote&gt;as
+is&lt;/quote&gt;.</markup>
+</para>
+</informalexample>
+</listitem>
+
+<listitem>
+<para>
+There are three different <quote>dashes</quote> that are commonly found
+in documentation.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+The hyphen combines two or more words into one. For example,
+<quote>mother-in-law</quote>. The hyphen can be entered directly from
+the keyboard. 
+</para>
+</listitem>
+<listitem>
+<para>
+The en-dash is used to seperate numbers/dates/&etc;. For example,
+<quote>Sections 1&ndash;3 review basic concepts</quote>. The en-dash
+can be encoded using <sgmltag class="genentity">ndash</sgmltag>.
+</para>
+</listitem>
+<listitem>
+<para>
+The em-dash is used to separate sentences, or to show that something is
+missing. This is rarely used in technical documentation, but it can be
+used to show that one sentence is interrupted by another. The em-dash
+can be encoded using <sgmltag class="genentity">mdash</sgmltag>.
+</para>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem>
+<para>
+When trying to decide between an ordered and unordered list, simply ask
+yourself the following question:  <quote>Does the order of the listed
+items matter?</quote> or <quote>If I change the order of the listed
+items, does that change the meaning of the list?</quote>. If you answer
+<quote>No</quote> to either question, then an unordered list is likely
+the logical choice.
+</para>
+</listitem>
+
+<listitem>
+<para>
+All <sgmltag class="starttag">chapter</sgmltag> and <sgmltag
+class="starttag">sect<replaceable>N</replaceable></sgmltag> tags must
+have an <sgmltag class="attribute">id</sgmltag>. The <sgmltag
+class="attribute">id</sgmltag> must be in all lower case, and with
+dashes separating words. For example, <markup>&lt;sect1
+id="how-to-obtain-kapp"&gt;</markup>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+All elements must have a full closing tag unless they are empty
+elements. Empty elements must still be closed with a /.
+</para>
+<segmentedlist>
+<segtitle>Incorrect</segtitle>
+<segtitle>Correct</segtitle>
+<seglistitem>
+<seg><markup>&lt;para/Blah blah/ or &lt;para&gt;Blah
+blah&lt;/&gt;</markup></seg>
+<seg><markup>&lt;para&gt;Blah blah&lt;/para&gt;</markup></seg>
+</seglistitem>
+</segmentedlist>
+</listitem>
+
+<listitem>
+<para>
+No attribute minimization.
+</para>
+<segmentedlist>
+<segtitle>Incorrect</segtitle>
+<segtitle>Correct</segtitle>
+<seglistitem>
+<seg><markup>attribute=value</markup> or
+<markup>attribute='value'</markup></seg>
+<seg><markup>attribute="value"</markup></seg>
+</seglistitem>
+</segmentedlist>
+</listitem>
+
+<listitem>
+<para>
+All entities must end with a semi-colon:
+</para>
+
+<segmentedlist>
+<segtitle>Incorrect</segtitle>
+<segtitle>Correct</segtitle>
+<seglistitem>
+<seg><markup>&percnt;parameterentity</markup> or
+<markup>&amp;generalentity</markup></seg>
+<seg><markup>&percnt;parameterentity;</markup> or
+<markup>&amp;generalentity;</markup></seg>
+</seglistitem>
+</segmentedlist>
+</listitem>
+
+<listitem>
+<para>
+Element GIs (the first word in a tag) must be written in lower case
+only.
+</para>
+<segmentedlist>
+<segtitle>Incorrect</segtitle>
+<segtitle>Correct</segtitle>
+<seglistitem>
+<seg><markup>&lt;MediaObject&gt;</markup> or
+<markup>&lt;MEDIAOBJECT&gt;</markup></seg>
+<seg><markup>&lt;mediaobject&gt;</markup></seg>
+</seglistitem>
+</segmentedlist>
+<para>
+Entities are also case sensitive, and will result in validation errors
+if the case is wrong.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Specify date and application's version in the format:
+</para>
+
+<screen>
+  <markup>&lt;date&gt;2000-12-31&lt;/date&gt;</markup>
+  <markup>&lt;releaseinfo&gt;1.02.03&lt;/releaseinfo&gt;</markup>
+</screen>
+
+<para>
+The <sgmltag class="starttag">date</sgmltag> is the date of the last
+update. The <sgmltag class="starttag">releaseinfo</sgmltag> always
+matches the version number of the application that is described in the
+documentation (if any). A translated version of a documentation always
+has the same <sgmltag class="starttag">date</sgmltag> and <sgmltag
+class="starttag">releaseinfo</sgmltag> as the English original. Please
+respect this, it is the only way to manage efficiently both the writing
+and the translation processes.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The list of entities for applications is maintained centrally. Entity
+names are the application name completely in lower case. In case the
+name you need does not exist yet, send a mail to
+<email>kde-docbook@kde.org</email> to have it added. You may add it in
+the prologue for validation purposes (in case it's new), but don't
+forget to remove it when you submit the document, because there should
+not be any <quote>extra</quote> entities defined in the document
+prologue.
+</para>
+</listitem>
+
+<listitem>
+<para>
+For language-independent entities, use
+<filename>kdelibs/kdoctools/customization/entities/general.entities</filename>
+and for language-specific entities, use
+<filename>kdelibs/kdoctools/customization/<replaceable>lang</replaceable>/user.entities</filename>. Try
+to avoid clashes with existing &tde; entities.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The <filename>en/user.entities</filename> file should be updated
+keeping in mind that translation must be possible. Here is an example of
+how this translation can be managed:
+</para>
+
+<example>
+<title>Managing translatable entities</title>
+
+<para>
+<sgmltag class="genentity">LMB</sgmltag> is en entity which stands for
+<quote>Left Mouse Button</quote>
+</para>
+
+<para>
+When translating to French for example, do not translate only the entity
+contents, please also translate the entity name to <sgmltag
+class="genentity">BGS</sgmltag> (or <sgmltag
+class="genentity">bgs</sgmltag>), to reflect the change in the
+initials:
+</para>
+
+<screen>  <markup>&lt;!ENTITY "LMB" "left mouse button"&gt;</markup> <lineannotation>becomes</lineannotation>
+  <markup>&lt;!ENTITY "BGS" "bouton gauche de la souris"&gt;</markup></screen>
+
+<para>
+Languages that decline nouns like German and Russian can use something
+like the following:
+</para>
+
+<screen><markup>
+  &lt;!ENTITY "LMB" "linke Maustaste"&gt;
+  &lt;!ENTITY "LMBn" "linken Maustaste"&gt;
+</markup></screen>
+</example>
+</listitem>
+
+<listitem>
+<para>
+If you feel that some elements don't make fine enough a distinction,
+feel free to use the attribute <sgmltag class="attribute">role</sgmltag>
+(but please tell the DocBook team, as otherwise you may find your
+document to be suddenly invalid). 
+</para>
+</listitem>
+
+<listitem>
+<para>
+Use <sgmltag class="starttag">qandaset</sgmltag> for
+&FAQ;s, not an <sgmltag
+class="starttag">itemizedlist</sgmltag>. Please split up a
+&FAQ; into several chapters or sections if it gets big.
+The &HTML; files get too big otherwise, which the users
+may not like.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Abbreviations and acronyms should be marked up as well.
+</para>
+
+<para>
+Use the DocBook tags <sgmltag class="starttag">abbrev</sgmltag> and
+<sgmltag class="starttag">acronym</sgmltag> respectivly.
+</para>
+
+<para>
+Please keep them apart: acronyms are things like &GUI;, &tde;,
+<acronym>GPL</acronym>, while abbreviations are things like &etc;, &ie;,
+&eg;.
+</para>
+
+<para>
+There are entities for the most common ones.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Use <sgmltag class="starttag">glossterm</sgmltag> or <sgmltag
+class="starttag">firstterm</sgmltag> each time you introduce a
+technically significant new word.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Keep in mind that the <quote>$</quote> sign is introduced by the shell,
+and is not part of an environment variable's name:
+</para>
+
+<informalexample>
+<para>
+<userinput><command>ls</command> <option>-l</option>
+<parameter>$<envar>TDEDIR</envar></parameter></userinput> is marked up
+as</para>
+<screen><markup>&lt;userinput&gt;&lt;command&gt;ls&lt;/command&gt;
+&lt;option&gt;-l&lt;/option&gt;
+&lt;parameter&gt;$&lt;envar&gt;TDEDIR&lt;/envar&gt;&lt;/parameter&gt;
+&lt;/userinput&gt;</markup></screen>
+<para><userinput><command>export</command>
+<parameter>$<envar>TDEDIR</envar>=<replaceable>/usr/local/tde</replaceable></parameter></userinput>
+is marked up as:</para>
+<screen><markup>&lt;userinput&gt;
+&lt;command&gt;export&lt;/command&gt;
+&lt;parameter&gt;$&lt;envar&gt;TDEDIR&lt;/envar&gt;=&lt;filename&gt;
+/usr/local/tde&lt;/filename&gt;&lt;/parameter&gt;&lt;/userinput&gt;</markup></screen>
+</informalexample>
+</listitem>
+
+<listitem>
+<para>
+Only use <sgmltag class="starttag">ulink</sgmltag> for &URL;'s and not
+for files, unlike <sgmltag class="starttag">A</sgmltag> in
+<acronym>HTML</acronym>. Don't use it for email addresses either, they
+have their own element, <sgmltag class="starttag">email</sgmltag>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The elements <sgmltag class="starttag">beginpage</sgmltag> and <sgmltag
+class="starttag">bridgehead</sgmltag> are disallowed and have been
+removed from the &tde; customized <acronym>DTD</acronym>. (They are not
+meant for new technical documentation.) <sgmltag
+class="starttag">revisionhistory</sgmltag> has been removed also: we are
+using <acronym>SVN</acronym> already.
+</para>
+</listitem>
+
+</itemizedlist>
+
+</chapter>
+
+<chapter id="purpose">
+<title>Purpose of this document</title>
+
+<para>
+The purpose of this document is to describe how markup has been standardized within
+&tde; documentation only.
+</para>
+
+<para>
+This document is <emphasis>not</emphasis> to be considered more
+authoritative than the DocBook documentation, including the O'Reilly
+Duck book. However, there are places where the &tde;
+<acronym>DTD</acronym> is more restrictive than, or just differs from,
+the <acronym>OASIS</acronym> <acronym>DTD</acronym>, and these are noted
+in this document. In these cases, follow the instructions here.
+</para>
+
+<para>
+Please read and make use of the other documentation available to you,
+which is much more comprehensive. This document is not intended to be
+more than a quick reference for &tde; authors, to clarify how the
+DocBook &XML; elements are used within the &tde; Documentation.
+</para>
+
+<sect1>
+<title>Other reference material</title>
+
+<para>
+Please take a look at the following reference material, rather than
+relying on this document to answer all your questions.
+</para>
+
+<variablelist>
+<varlistentry>
+<term><ulink url="http://www.docbook.org/">The Duck book</ulink></term>
+<listitem>
+<para>
+The complete DocBook <acronym>SGML</acronym> (and now
+&XML;) reference. Available as a download in several
+formats, so you can keep a copy on  your hard drive for reference. Also
+available for sale in hard copy - if you see  yourself doing a lot of
+DocBook Authoring, you definitely ought to consider buying it. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><ulink
+url="http://opensource.bureau-cornavin.com/crash-course/">The Crash
+Course to Docbook</ulink></term>
+<listitem>
+<para>
+A non-&tde; specific crash course to marking up documentation. This is the
+starting point for all &tde; documents, including the markup issues discussed
+here. Note that the current version is written for
+<acronym>SGML</acronym>, but the concepts are still correct for &XML;.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>The &tde; Documentation Template</term>
+<listitem>
+<para>
+Covers many things not mentioned here, including required and optional
+chapters, the preferred way to mark up the prologue and bookinfo
+sections, and how to deal with licensing and credits. It can be found
+in <filename>kdelibs/kdoctools/template.docbook</filename> in <acronym>CVS</acronym>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><ulink url="http://www.millin.de/linux_docbook_xmlbuch.html">DocBook-XML</ulink> (in German)</term>
+<listitem>
+<para>A very nice book, in German only unfortunately, but comes highly recommended.</para>
+</listitem>
+</varlistentry>
+
+
+</variablelist>
+
+</sect1>
+</chapter>
+
+<chapter id="prologue">
+<title>The Prologue</title>
+
+<screen><markup>
+&lt;?xml version="1.0" ?&gt;
+&lt;!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  &lt;!-- Define an entity for your application if it is not part of TDE
+       CVS --&gt;
+  &lt;!ENTITY <replaceable>kmyapplication</replaceable> "&lt;application&gt;KMyApp&lt;/application&gt;"&gt;
+  &lt;!ENTITY kappname "<replaceable>&amp;kmyapplication;</replaceable>"&gt;&lt;!-- replace kmyapplication here
+                                            do *not* replace kappname--&gt;
+  &lt;!ENTITY package "<replaceable>tde-module</replaceable>"&gt;&lt;!-- tdebase, tdeadmin, etc. Leave
+                                     this unchanged if your
+                                     application is not maintained in TDE GIT --&gt;
+  &lt;!ENTITY % addindex "IGNORE"&gt;
+  &lt;!ENTITY % English "INCLUDE"&gt; &lt;!-- ONLY If you are writing non-English
+                                     original documentation, change
+                                     the language here --&gt;
+]&gt;</markup></screen>
+
+
+<para>
+In general, this needs minimal changing from the template. The items
+you <emphasis>must</emphasis> change are the entities
+<quote>kappname</quote>, <quote>package</quote>, and <quote>English</quote>.
+</para>
+
+<para>
+The entity <quote>kappname</quote> looks like it's redundant (as the
+comment in the template notes), but it is important. This allows us to
+use one global text in all documents, and still refer to the specific
+application by its correct name. So it should be changed to refer to
+this new entity, but this time you should only change the part in quotes
+(<quote>&amp;kmyapplication;</quote>) as follow:
+</para>
+
+<example>
+<title>Setting up the global <quote>kappname</quote> entity</title>
+
+<screen>
+From:
+<markup>
+&lt;!ENTITY kappname "&amp;kmyapplication;" -- this only *seems* redundant --&gt;
+</markup>
+To:
+<markup>
+&lt;!ENTITY kappname "&amp;kate;" -- this only *seems* redundant --&gt;
+</markup>
+</screen>
+</example>
+
+<para>In short: change any occurrence of <quote>kmyapplication</quote>
+to the real name of your application. Do <emphasis>not</emphasis> use
+<quote>kappname</quote> or <quote>kapp</quote> directly in a document
+yourself.</para>
+
+<para>The entity <quote>package</quote> is used similarly. It allows
+us to insert a single piece of <quote>boilerplate</quote> text into
+every document, and have the correct package name inserted when the
+document is compiled. Use the cvs module name, in lower case, &eg;
+<quote>tdeedu</quote> or <quote>tdebase</quote>.</para>
+
+<para>The entity <sgmltag class="paramentity">addindex</sgmltag> is a toggle. If
+set to <quote>INCLUDE</quote> a document index will be automatically
+generated. It is normally set instead to <quote>IGNORE</quote>, and should
+not be changed unless you really do want to generate an index. You can find
+out more about indexes in <xref linkend="references-indexes-glossary"/>.</para>
+
+<example>
+<title>A &tde; User Manual Prolog</title>
+
+<para>Here is an example of a completely set up prolog, as it normally
+looks. This is the prolog from the &amor; documentation</para>
+
+<screen><markup>&lt;?xml version="1.0" ?&gt;
+&lt;!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  &lt;!ENTITY kappname "&amp;amor;"&gt;
+  &lt;!ENTITY package "tdetoys"&gt;
+  &lt;!ENTITY % addindex "IGNORE"&gt;
+  &lt;!ENTITY % English "INCLUDE"&gt;
+]&gt;</markup></screen>
+</example>
+
+<note>
+<para>
+The entity <quote>English</quote> should be changed to reflect your
+language, if you are either writing original documentation in another
+language, or you are translating a document. For &tde; the original
+documentation should always be in English, so you should not need to change
+this when writing. For informational purposes, the currently supported
+languages are:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+Afrikaans
+</para>
+</listitem>
+<listitem>
+<para>
+British-English
+</para>
+</listitem>
+<listitem>
+<para>
+Bulgarian
+</para>
+</listitem>
+<listitem>
+<para>
+Catalan
+</para>
+</listitem>
+<listitem>
+<para>
+Czech
+</para>
+</listitem>
+<listitem>
+<para>
+Danish
+</para>
+</listitem>
+<listitem>
+<para>
+German
+</para>
+</listitem>
+<listitem>
+<para>
+Greek
+</para>
+</listitem>
+<listitem>
+<para>
+English
+</para>
+</listitem>
+<listitem>
+<para>
+Spanish
+</para>
+</listitem>
+<listitem>
+<para>
+Estonian
+</para>
+</listitem>
+<listitem>
+<para>
+Finnish
+</para>
+</listitem>
+<listitem>
+<para>
+Faroese
+</para>
+</listitem>
+<listitem>
+<para>
+French
+</para>
+</listitem>
+<listitem>
+<para>
+Hebrew
+</para>
+</listitem>
+<listitem>
+<para>
+Hungarian
+</para>
+</listitem>
+<listitem>
+<para>
+Indonesian
+</para>
+</listitem>
+<listitem>
+<para>
+Italian
+</para>
+</listitem>
+<listitem>
+<para>
+Japanese
+</para>
+</listitem>
+<listitem>
+<para>
+Dutch
+</para>
+</listitem>
+<listitem>
+<para>
+Norwegian (Note, this is only for compatibility, either Norwegian-Bokmal or
+Norwegian-Nynorsk should be used in preference.)
+</para>
+</listitem>
+<listitem>
+<para>
+Norwegian-Bokmal
+</para>
+</listitem>
+<listitem>
+<para>
+Norwegian-Nynorsk
+</para>
+</listitem> 
+<listitem>
+<para>
+Polish
+</para>
+</listitem>
+<listitem>
+<para>
+Portuguese
+</para>
+</listitem>
+<listitem>
+<para>
+Brasilian-Portuguese
+</para>
+</listitem>
+<listitem>
+<para>
+Romanian
+</para>
+</listitem>
+<listitem>
+<para>
+Russian
+</para>
+</listitem>
+<listitem>
+<para>
+Slovak
+</para>
+</listitem>
+<listitem>
+<para>
+Slovenian
+</para>
+</listitem>
+<listitem>
+<para>
+Serbian
+</para>
+</listitem>
+<listitem>
+<para>
+Swedish
+</para>
+</listitem>
+<listitem>
+<para>
+Turkish
+</para>
+</listitem>
+<listitem>
+<para>
+Ukrainian
+</para>
+</listitem>
+<listitem>
+<para>
+Walloon
+</para>
+</listitem>
+<listitem>
+<para>
+Xhosa
+</para>
+</listitem>
+<listitem>
+<para>
+Continental-Chinese
+</para>
+</listitem>
+<listitem>
+<para>
+Traditional-Chinese
+</para>
+</listitem>
+</itemizedlist>
+</note>
+
+<sect1 id="book-and-bookinfo">
+<title><sgmltag class="element">book</sgmltag> and the <sgmltag
+class="element">bookinfo</sgmltag> section</title>
+
+<para>
+The <sgmltag class="element">bookinfo</sgmltag> section is most easily prepared
+by copying the &tde; template.
+</para>
+
+<variablelist>
+<varlistentry>
+<term><sgmltag class="starttag">book lang="&amp;language"</sgmltag>
+<anchor id="book"/>
+</term>
+<listitem>
+<para>
+Contains the entire document. Most important thing to remember is the <sgmltag
+class="attribute">lang</sgmltag> attribute, which must contain exactly <sgmltag
+class="attvalue">&amp;language;</sgmltag>, and must not be changed. To set the
+language for the document, change the entity as described in the <link
+linkend="prologue">prologue</link> section.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">bookinfo</sgmltag>
+<anchor id="bookinfo"/>
+</term>
+<listitem>
+<para>
+Wraps the <quote>meta</quote> information &ndash; information about
+the document, not about the application it is documenting. Required in
+&tde; documentation. No attributes.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">authorgroup</sgmltag>
+<anchor id="authorgroup"/>
+</term>
+<listitem>
+<para>
+Wraps the author information, and may also contain <sgmltag
+class="starttag">othercredit</sgmltag> information. Required in &tde;
+documentation. No attributes.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">author</sgmltag>
+<anchor id="author"/>
+</term>
+<listitem>
+<para>
+Required element in the header section of all &tde; documentation. Use this
+element <emphasis>only</emphasis> for the author(s) of the document. Other
+contributers (developers, translators, and so on) should be credited in the
+<link linkend="othercredit"><sgmltag
+class="starttag">othercredit</sgmltag></link> section. No attributes.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">personname</sgmltag><anchor id="personname"/></term>
+<listitem>
+<para>Used to wrap a person's name. You can use this directly in the
+text as well, but here it should be used to contain each author or
+contributor name.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">firstname</sgmltag><anchor id="firstname"/></term>
+<listitem>
+<para>
+The contributor's first name.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">othername</sgmltag><anchor
+id="othername"/></term>
+<listitem>
+<para>
+If the author normally uses more than a first and surname, you can add
+further names here.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">surname</sgmltag><anchor
+id="surname"/></term>
+<listitem>
+<para>
+The author's surname.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">email</sgmltag></term>
+<listitem>
+<para>
+An email address for the maintainer of the document is required for
+&tde; documentation. You do not have to use your primary private
+address, and you may be able to arrange for someone else (the
+developer perhaps) to receive the email regarding the document. In
+any case, there must be an address for users and translators to
+contact regarding errors and document bugs.
+</para>
+
+<note><para>In previous versions of DocBook, <sgmltag
+class="starttag">email</sgmltag> could not be used directly inside
+<sgmltag class="starttag">author</sgmltag>. Since DocBook XML V 4.2
+(used by &tde; for documents after &tde; 3.1.x), this is possible,
+which simplifies this markup considerably.</para></note>
+
+<para>
+In other contexts in the document, <sgmltag
+class="starttag">email</sgmltag> is used to contain any email address,
+and is not used inside the <sgmltag class="element">address</sgmltag>
+element. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">othercredit role=""</sgmltag>
+<anchor id="othercredit"/></term>
+<listitem>
+<para>
+Similary to <sgmltag class="element">author</sgmltag>, this is a wrapper around
+information describing other contributors to the document. Include here the
+contributor's name and email address as you do for the author. See the template
+for more details.
+</para>
+
+<para>
+The <sgmltag class="attribute">role</sgmltag> attribute is required, and can
+contain any one of the following:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>Translator</para>
+</listitem>
+<listitem>
+<para>Developer</para>
+</listitem>
+<listitem>
+<para>Reviewer</para>
+</listitem>
+<listitem>
+<para>Graphist</para>
+</listitem>
+<listitem>
+<para>Musician</para>
+</listitem>
+</itemizedlist>
+
+<para>
+The <sgmltag class="element">othercredit</sgmltag> element also includes the
+<sgmltag class="element">contrib</sgmltag> element.
+</para>
+
+<variablelist>
+<varlistentry>
+<term><sgmltag class="starttag">contrib</sgmltag>
+<anchor id="contrib"/></term>
+<listitem>
+<para>
+The role this contributor played in the document or application preparation.
+This could contain something like:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>Developer</para>
+</listitem>
+<listitem>
+<para><foreignphrase lang="de">Deutsche &Uuml;bersetzung</foreignphrase></para>
+</listitem>
+<listitem>
+<para>Reviewer</para>
+</listitem>
+<listitem>
+<para><foreignphrase lang="fr">Traduction fran&ccedil;aise</foreignphrase></para>
+</listitem>
+</itemizedlist>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">corpauthor</sgmltag>
+<anchor id="corpauthor"/></term>
+<listitem>
+<para>
+This is used in very specific circumstances, where an organization
+(&eg; <quote>The TDE Team</quote>) is being credited with authorship of
+a document. Authors writing about applications should not use this
+and should credit themselves. If you do find a need to use this,
+please be sure to include a maintainer's name and email address in the
+credits chapter of the document.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">copyright</sgmltag>
+<anchor id="copyright"/></term>
+<listitem>
+<para>
+This is a wrapper for copyright information. <sgmltag
+class="element">copyright</sgmltag> must contain these elements:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><sgmltag class="starttag">year</sgmltag><anchor id="year"/></term>
+<listitem>
+<para>
+Add one <sgmltag class="element">year</sgmltag> element for each year
+in which the document was changed or added to. Don't put more than
+one year in each tag, rather add more <sgmltag
+class="element">year</sgmltag> elements, and use the 4 digit
+<quote>YYYY</quote> format.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">holder</sgmltag><anchor id="holder"/></term>
+<listitem>
+<para>
+The usual full name of the copyright holder(s). If there is more
+than one copyright holder (the document was previously maintained by
+another person, or is written collaboratively), then add more <sgmltag
+class="element">copyright</sgmltag> sections, rather than trying to
+fit multiple names in the one section.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>
+Copyright is automatically held by the author of the document, but the
+<sgmltag class="element">copyright</sgmltag> element is still required
+for all &tde; documentation. None of the elements contained have any
+attributes.
+</para>
+<para>Please do <emphasis>not</emphasis> add more names or years to
+existing <sgmltag class="starttag">holder</sgmltag> or <sgmltag
+class="starttag">year</sgmltag> elements. Add more, if they are
+required, or have multiple <sgmltag
+class="element">copyright</sgmltag> sections.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">legalnotice</sgmltag><anchor
+id="legalnotice"/></term>
+<listitem>
+<para>
+This contains, of course, a legal notice. This is absolutely required for any
+&tde; document. In the context of this section, it should contain the
+<sgmltag>&amp;FDLNotice;</sgmltag> entity, which inserts some information into
+the document about the document's license (and <emphasis>not</emphasis> the
+license of the application you are describing.)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="date"><sgmltag class="starttag">date</sgmltag></term>
+<listitem>
+<para>
+<emphasis>The date is very important.</emphasis> It is used not only by
+scripts for automatic processing of documentation, but is also central
+to revision control and co-ordination of translations. You must change
+the date if you have changed the <emphasis>original</emphasis> document,
+and you must <emphasis>not</emphasis> change the date if you are a
+translator. The format of the date is very important. It
+<emphasis>must</emphasis> be in the <acronym>ISO</acronym>, with
+<quote>literal</quote> delimiters, in the form
+<quote>yyyy-mm-dd</quote>. Please be extremely careful about this,
+and triple check it before you send in the document. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="releaseinfo"><sgmltag class="starttag">releaseinfo</sgmltag></term>
+<listitem>
+<para>
+This should match exactly the version of the
+<emphasis>application</emphasis> you are documenting. It should
+normally conform to the format X.x.xx (where X is a major version
+number and x are minor version numbers, however, you no longer have to
+pad the content to this length. That is to say, if the application has
+released version <quote>1.4</quote>, you may write
+<markup>&lt;releaseinfo&gt;1.4&lt;/releaseinfo&gt;</markup>, and you
+do not need to make it
+<markup>&lt;releaseinfo&gt;1.04.00&lt;/releaseinfo&gt;</markup></para>
+<para>This is <emphasis>not</emphasis> the version of the document.
+There are no attributes, and this element is required in &tde;
+documentation.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="abstract"><sgmltag class="starttag">abstract</sgmltag></term>
+<listitem>
+<para>
+In &tde; Documentation, the abstract is required. It should be a short
+one- or two-sentence summary of the document. The abstract is not the
+place to put version or contact information, but it should say something
+about the application and its purpose. For example <quote>KFoo is a
+small fast network enabled foo generator, suitable for both beginner and
+advanced foo users.</quote>. 
+</para>
+<para>The abstract is your chance to sum up the application in a small
+paragraph &mdash; in &khelpcenter; it shows up on the first page as
+your document is selected, and the abstract frequently shows up in the
+summary of your document in web searches. A short overview of the
+application you are writing about is very valuable in this situation,
+<quote>This is the KFoo handbook and describes KFoo 1.2.</quote> on
+its own, is not.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="keywordset"><sgmltag class="starttag">keywordset</sgmltag></term>
+<listitem>
+<para>
+A wrapper for a set of keywords suitable for search engines. Required
+for &tde; Documentation, and there are no attributes. The <sgmltag
+class="element">keywordset</sgmltag> should contain several
+<sgmltag class="starttag">keyword</sgmltag>s.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="keyword"><sgmltag class="starttag">keyword</sgmltag></term>
+<listitem>
+<para>
+Add one <sgmltag class="starttag">keyword</sgmltag> inside the <sgmltag
+class="starttag">keywordset</sgmltag> for each search term. You must
+include at a minimum the terms <quote>TDE</quote>, the name of the
+application you are documenting, and the name of the package it is found
+in, for example <quote>tdegames</quote>. The keywords should be in
+order from most general first (that is, <acronym>TDE</acronym>) through
+less general, to the most specific. Add two or three more relevant words
+that people might search with, &eg;, for the application &kwrite; you
+might add <quote>editor</quote> and <quote>text</quote>. This is
+required for &tde; Documentation, and there are no attributes.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="translator-hooks"><markup>&lt;!-- TRANS:ROLES_OF_TRANSLATORS
+--&gt;</markup></term>
+<listitem>
+<para>
+This line is specific to &tde; documentation. Although it's a comment,
+it is <emphasis>absolutely</emphasis> required in documents. It is
+used by the translation system as a placeholder for the translation
+teams to add their own role info. Translators should add more <sgmltag
+class="element">othercredit</sgmltag> sections here as appropriate.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<example>
+<title>The bookinfo section from the &tde; template</title>
+<screen width="40"><markup>
+&lt;bookinfo&gt;
+&lt;title&gt;The &amp;kmyapplication; Handbook&lt;/title&gt;
+
+&lt;authorgroup&gt;
+&lt;author&gt;
+&lt;!-- This is just put in as an example. For real documentation, please
+     define a general entity in entities/contributor.entities, e.g.
+&lt;!ENTITY George.N.Ugnacious "&lt;personname&gt;&lt;firstname&gt;George&lt;/firstname&gt;&lt;othername&gt;N.&lt;/othername&gt;&lt;surname&gt;Ugnacious&lt;/surname&gt;&lt;/personname&gt;"&gt;
+&lt;!ENTITY George.N.Ugnacious.mail "&lt;email&gt;gnu@tde.org&lt;/email&gt;"&gt;
+and use `&amp;George.N.Ugnacious; &amp;George.N.Ugnacious.mail;' in the author element.
+ --&gt;
+&lt;personname&gt;
+&lt;firstname&gt;George&lt;/firstname&gt;
+&lt;othername&gt;N.&lt;/othername&gt;
+&lt;surname&gt;Ugnacious&lt;/surname&gt;
+&lt;/personname&gt;
+&lt;email&gt;gnu@tde.org&lt;/email&gt;
+&lt;/author&gt;
+&lt;/authorgroup&gt;
+
+&lt;!-- TRANS:ROLES_OF_TRANSLATORS --&gt;
+
+&lt;copyright&gt;
+&lt;year&gt;2002&lt;/year&gt;
+&lt;holder&gt;George N. Ugnacious&lt;/holder&gt;
+&lt;/copyright&gt;
+&lt;!-- Translators: put here the copyright notice of the translation --&gt;
+&lt;!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
+     and in the FDL itself on how to use it. --&gt;
+&lt;legalnotice&gt;&amp;FDLNotice;&lt;/legalnotice&gt;
+
+&lt;!-- Date and version information of the documentation
+Don't forget to include this last date and this last revision number, we
+need them for translation coordination !
+Please respect the format of the date (YYYY-MM-DD) and of the version
+(V.MM.LL), it could be used by automation scripts.
+Do NOT change these in the translation. --&gt;
+
+&lt;date&gt;2003-01-10&lt;/date&gt;
+&lt;releaseinfo&gt;1.1.&lt;/releaseinfo&gt;
+
+&lt;!-- Abstract about this handbook --&gt;
+
+&lt;abstract&gt;
+&lt;para&gt;
+&amp;kmyapplication; is an application specially designed to do nothing you would
+ever want.
+&lt;/para&gt;
+&lt;/abstract&gt;
+
+&lt;!-- This is a set of Keywords for indexing by search engines.
+Please at least include TDE, the TDE package it is in, the name
+ of your application, and a few relevant keywords. --&gt;
+
+&lt;keywordset&gt;
+&lt;keyword&gt;TDE&lt;/keyword&gt;
+&lt;keyword&gt;tdeutils&lt;/keyword&gt;
+&lt;keyword&gt;Kapp&lt;/keyword&gt;
+&lt;keyword&gt;nothing&lt;/keyword&gt;
+&lt;keyword&gt;nothing else&lt;/keyword&gt;
+&lt;/keywordset&gt;
+
+&lt;/bookinfo&gt;
+</markup></screen>
+</example>
+</sect1>
+</chapter>
+
+<chapter id="section-tags">
+<title>Chapters and Sections</title>
+
+<variablelist>
+<varlistentry>
+<term id="chapter"><sgmltag class="starttag">chapter
+id=""</sgmltag></term>
+<listitem>
+<para>
+Use chapters to break up the document into smaller chunks. A chapter
+break should occur when a major subject change happens. Use sections
+within the chapter when the subject changes, but you are still
+discussing a particular aspect of a larger subject.
+</para>
+
+<para>
+For example, going from discussing how to use the application, to how to
+configure the application would be worthy of a new chapter. Moving from
+discussing how to specifically configure the application on SuSE, to how
+to specifically configure the application on &RedHat;, would be a new
+section in a larger <quote>Configuration</quote> chapter.
+</para>
+
+<para>
+Chapters must have an <sgmltag class="attribute">id</sgmltag>. This is
+the only attribute used in &tde; documentation. For &tde; Documents,
+this id must be in lower case, and with a hyphen (-) to separate words.
+Please don't use spaces, underscores, or run the words together. For
+<acronym>HTML</acronym> generation, the chapter id and most <sgmltag
+class="starttag">sect1</sgmltag> id's are used to name the separate
+<abbrev>HTML</abbrev> pages, so take care to make them sensible and
+descriptive. For translators, these id's should be translated, but you
+will need to take care to also translate references to the id's in
+<sgmltag class="starttag">link</sgmltag> and <sgmltag
+class="starttag">xref</sgmltag> elements in other parts of the document.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="title">
+<sgmltag class="starttag">title</sgmltag></term>
+<listitem>
+<para>
+Titles are used in many places, but the most common is the Chapter and
+Section headings. Make sure to use sensible titles, as these will also
+be that chapter's (or section's) entry in the table of contents, so people
+will rely on these to find the part of the document they are interested
+in.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="sect1"><sgmltag class="starttag">sect1 id=""</sgmltag>,
+<sgmltag class="starttag">sect2</sgmltag>, <sgmltag
+class="starttag">sect3</sgmltag>, <sgmltag
+class="starttag">sect4</sgmltag>, <sgmltag
+class="starttag">sect5</sgmltag></term>
+<listitem>
+<anchor id="sect2"/><anchor id="sect3"/><anchor id="sect4"/><anchor
+id="sect5"/>
+<para>
+Use sections to break chapters up into smaller pieces. Use similar
+criteria on where to divide them as you would for chapters.
+</para>
+
+<para>
+Sections require a <sgmltag class="starttag">title</sgmltag>. Sections
+are nested according to the number - a <sgmltag
+class="starttag">sect2</sgmltag> can contain any number of <sgmltag
+class="starttag">sect3</sgmltag>, which can contain <sgmltag
+class="starttag">sect4</sgmltag>, but a <sgmltag
+class="starttag">sect2</sgmltag> can't directly contain a <sgmltag
+class="starttag">sect4</sgmltag>.
+</para>
+
+<para>
+<sgmltag class="starttag">sect1</sgmltag> requires an id attribute, and
+you can use id's on the other section tags if you want to later link
+directly to them from other parts of the document. <sgmltag
+class="attribute">id</sgmltag> is the only attribute used in &tde;
+Documentation.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="sect1info"><sgmltag class="starttag">sect1info</sgmltag>,
+<sgmltag class="starttag">sect2info</sgmltag>, <sgmltag
+class="starttag">sect3info</sgmltag>, <sgmltag
+class="starttag">sect4info</sgmltag>, <sgmltag
+class="starttag">sect5info</sgmltag></term> <listitem><anchor
+id="sect2info"/><anchor id="sect3info"/><anchor id="sect4info"/><anchor
+id="sect5info"/> 
+<para>
+The section info elements are rarely used in &tde; Documentation.
+They are appropriate for documents where some smaller sections are
+contributed by third parties, or where the document covers multiple
+applications. The contents are more or less the same as those of the
+<sgmltag class="starttag">bookinfo</sgmltag> section, although they
+tend to be briefer.</para>
+<para>Please ensure if you use these elements that you add the
+translation placeholder comments as you do in the prolog.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="appendix">
+<sgmltag class="starttag">appendix</sgmltag></term>
+<listitem>
+<para>
+The standard installation instructions for all applications are
+contained in an <sgmltag class="starttag">appendix</sgmltag>, and are
+normally required for &tde; documents. Although the installation
+instructions as found in the template are reasonably complete, and
+need no customization for most applications, authors are very strongly
+encouraged to expand on them. For example, links to web pages, where
+to find libraries, plugins, screenshots of the application in a
+particular configuration, or any other information you can think of.
+</para>
+
+<para>If the application is only distributed with &tde;, there is
+little use in repeating the same installation instructions for every
+manual. You may leave it out entirely, unless you have further
+information to add.</para>
+
+<para>
+For other purposes, appendices are used infrequently in &tde;
+Documentation. An appendix can be found, for example, in the &kppp;
+document, containing such things as Hayes Modem commands. Only use an
+appendix if you think it's very necessary. In most cases, the
+information it would contain would be better moved to the main document.
+In the example of &kppp;, this information is vital to a few people, but
+extremely uninteresting to the majority, so it was placed in an
+appendix.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</chapter>
+
+<chapter id="links">
+<title>The linking elements</title>
+
+<variablelist>
+<varlistentry>
+<term id="link"><sgmltag class="starttag">link
+linkend=""</sgmltag></term>
+
+<listitem>
+<para>
+The most common link. Use this to turn a word or phrase into a link to
+another part of the document. <sgmltag
+class="attribute">linkend</sgmltag> is the only attribute we use.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="ulink"><sgmltag class="starttag">ulink url=""</sgmltag></term>
+<listitem>
+<para>A link that refers to a document using it's
+<acronym>URI</acronym>. Use this for websites and ftp sites, but not
+for <link linkend="email">email addresses</link>, which have their own
+specific tag. Please do <emphasis>not</emphasis> use this to link to
+other documents on the local system.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="anchor">
+<sgmltag class="starttag">anchor id=""/</sgmltag></term>
+<listitem>
+<para>
+Marks a place in the document, which you can use to link to. Note that
+the <sgmltag class="attribute">id</sgmltag> attribute on any other
+element where it is valid, will automatically generate an
+<acronym>HTML</acronym> anchor in generated <acronym>HTML</acronym>, so
+you do not need to duplicate these. Use anchors only when you need to
+jump into the middle of a longer page, for example, to a particular menu
+item, or to a particular option in a preference dialog.
+</para>
+<note>
+<para>
+<sgmltag class="emptytag">anchor</sgmltag> is an empty element, and must
+be closed with a /.
+</para>
+</note>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="xref"><sgmltag class="emptytag">xref
+linkend=""</sgmltag></term>
+<listitem>
+<para>
+A cross reference to another part of the document. Use this when you
+want to refer to the section without the name. This is one of very few
+unclosed elements allowed. <sgmltag class="attribute">linkend</sgmltag>
+is the only attribute we currently use.
+</para>
+<note>
+<para>
+<sgmltag class="emptytag">xref</sgmltag> is an empty element, and must
+be closed with a /.
+</para>
+</note>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="email">
+<sgmltag class="starttag">email</sgmltag></term>
+<listitem>
+<para>
+Use this to enclose an email address. Don't add <quote>mailto:</quote>
+to the email address, and don't use <sgmltag class="starttag">ulink
+url=""</sgmltag> for email addresses. No attributes required.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</chapter>
+
+<chapter id="lists">
+<title>Lists</title>
+
+<variablelist>
+<varlistentry>
+<term id="listitem"><sgmltag class="starttag">listitem</sgmltag></term>
+<listitem>
+<para>
+<sgmltag class="starttag">listitem</sgmltag> is the main building block
+of almost all the lists. It should always contain some other markup,
+usually a <sgmltag class="starttag">para</sgmltag>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="orderedlist"><sgmltag
+class="starttag">orderedlist</sgmltag></term>
+<listitem>
+<para>
+Use this type of list when the order of the items matters, but they are
+not a set of steps that are carried out to achieve something. A good
+example is a list of things in order of importance.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="itemizedlist"><sgmltag
+class="starttag">itemizedlist</sgmltag></term>
+<listitem>
+<para>
+Use an itemized list when the order of the items is not
+important.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="variablelist"><sgmltag
+class="starttag">variablelist</sgmltag></term>
+<listitem>
+<para>
+A list that has two sections for each entry. Examples: A menu item, and
+what the menu item does, An action, and its result, or a term and its
+definition. This is a very common type of list. (Almost this entire
+document is composed of variable lists.)
+</para>
+<para>
+<sgmltag class="starttag">variablelist</sgmltag> contains the following
+elements:
+</para>
+
+<variablelist>
+<varlistentry>
+<term id="varlistentry"><sgmltag
+class="starttag">varlistentry</sgmltag></term>
+<listitem>
+<para>
+A <sgmltag class="starttag">varlistentry</sgmltag> is a wrapper around
+each pair in the variable list.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="term"><sgmltag class="starttag">term</sgmltag></term>
+<listitem>
+<para>
+To reuse the above examples, the <sgmltag
+class="starttag">term</sgmltag> for each pair would be the menu item you
+are describing, the action, or the term you are defining. You can use
+the <sgmltag class="attribute">id</sgmltag> attribute for this element,
+which is quite convenient in long lists such as a menu reference,
+enabling you to link directly to a particular menu item from another
+part of the document.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><sgmltag class="starttag">listitem</sgmltag></term>
+<listitem>
+<para>
+As described above the <sgmltag class="starttag">listitem</sgmltag> is
+used inside a <sgmltag class="starttag">varlistentry</sgmltag> to hold
+the second part of the pair: The result of choosing that menu item, for
+example, the consequences of an action, or the definition of the term.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="procedure"><sgmltag
+class="starttag">procedure</sgmltag></term>
+<listitem>
+<para>
+Use a procedure list when you are listing a sequence of steps which are
+performed in a particular order.
+</para>
+<para>
+A procedure contains only one tag:
+</para>
+
+<variablelist>
+<varlistentry><term id="step"><sgmltag
+class="starttag">step</sgmltag></term>
+<listitem>
+<para>
+A step is one of the sequence of events that make up a
+procedure.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="substeps"><sgmltag class="starttag">substeps</sgmltag></term>
+<listitem>
+<para>A step can contain substeps</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="simplelist"><sgmltag
+class="starttag">simplelist</sgmltag></term>
+<listitem>
+<para>
+A simple list is just that - a simple list, with no formatting
+required. A simple list can contain only one type of element:
+</para>
+
+<variablelist>
+<varlistentry><term id="member"><sgmltag
+class="starttag">member</sgmltag></term>
+<listitem>
+<para>
+Members of a simple list.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="segmentedlist">
+<sgmltag class="starttag">segmentedlist</sgmltag></term>
+<listitem>
+<para>
+A Segmented list is a very particular type of list. Use
+sparingly, as it's very difficult to get these right, and most content
+appropriate for a segmented list could just as well fit the table model. 
+</para>
+
+<example>
+<title>A Segmented List</title>
+
+<screen><markup>
+&lt;segmentedlist&gt;
+&lt;segtitle&gt;Name&lt;/segtitle&gt;
+&lt;segtitle&gt;Occupation&lt;/segtitle&gt;
+&lt;segtitle&gt;Favorite Food&lt;/segtitle&gt;
+&lt;seglistitem&gt;
+&lt;seg&gt;Tux&lt;/seg&gt;
+&lt;seg&gt;Linux Mascot&lt;/seg&gt;
+&lt;seg&gt;Herring&lt;/seg&gt;
+&lt;/seglistitem&gt;
+&lt;seglistitem&gt;
+&lt;seg&gt;Konqui&lt;/seg&gt;
+&lt;seg&gt;The TDE Dragon&lt;/seg&gt;
+&lt;seg&gt;Gnomes&lt;/seg&gt;
+&lt;/seglistitem&gt;
+&lt;/segmentedlist&gt;</markup></screen>
+
+<segmentedlist><segtitle>Name</segtitle>
+<segtitle>Occupation</segtitle>
+<segtitle>Favorite Food</segtitle>
+
+<seglistitem><seg>Tux</seg>
+<seg>Linux Mascot</seg>
+<seg>Herring</seg></seglistitem>
+
+<seglistitem><seg>Konqui</seg>
+<seg>The TDE Dragon</seg>
+<seg>Gnomes</seg></seglistitem></segmentedlist>
+</example>
+
+<para>The segmented list contains the following elements:</para>
+
+<variablelist>
+
+<varlistentry>
+<term id="segtitle"><sgmltag class="starttag">segtitle</sgmltag></term>
+<listitem>
+<para>
+The title each segment will have
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="seglistitem"><sgmltag
+class="starttag">seglistitem</sgmltag></term>
+<listitem>
+<para>
+A set of entries in the list
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="seg"><sgmltag class="starttag">seg</sgmltag></term>
+<listitem>
+<para>
+The contents of the entries in the list. In each
+<sgmltag class="starttag">seglistitem</sgmltag> there is one
+<sgmltag class="starttag">seg</sgmltag> for each
+<sgmltag class="starttag">segtitle</sgmltag>.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</chapter>
+
+<chapter id="tables">
+<title>Tables</title>
+
+<variablelist>
+
+<varlistentry>
+<term id="informaltable"><sgmltag
+class="starttag">informaltable</sgmltag></term>
+<listitem>
+<para>
+This is the table type used most in &tde; Documentation. Please be very
+sure that what you are marking up as a table, is actually tabular data,
+as in many cases a <sgmltag class="starttag">variablelist</sgmltag> is
+more appropriate. Please do not use any of the presentation attributes
+to make tables <quote>look nice</quote>. The only attribute currently
+allowed in &tde; Documents is <sgmltag class="attribute">pgwide</sgmltag>.
+</para>
+ 
+<para>
+An <sgmltag class="starttag">informaltable</sgmltag> must contain a
+<sgmltag class="starttag">tgroup cols=""</sgmltag> entry. Informal
+tables have no specific title, if you wish the table to be titled and to
+have an entry in the table of contents, you should use <link
+linkend="table"><sgmltag class="starttag">table</sgmltag></link>. Do
+not use any attributes other than <sgmltag
+class="attribute">pgwide</sgmltag> on tables or informal tables for
+&tde; documentation.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="table"><sgmltag class="starttag">table</sgmltag></term>
+<listitem>
+<para>
+A formal table with a title. Tables will have their own separate entry
+in the table of contents. Other than the addition of a title, they are
+marked up the same as an <sgmltag
+class="starttag">informaltable</sgmltag>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="tgroup"><sgmltag class="starttag">tgroup
+cols=""</sgmltag></term>
+<listitem>
+<para>
+A <sgmltag class="starttag">tgroup</sgmltag> is a required element in a
+table. The <sgmltag class="attribute">cols</sgmltag> attribute is
+required, and should be completed with the number of columns the table
+is to hold. No other attributes used in &tde; Documentation.
+</para>
+
+<para>
+A <sgmltag class="element">tgroup</sgmltag> must contain a <sgmltag
+class="element">tbody</sgmltag>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="tbody"><sgmltag class="starttag">tbody</sgmltag></term>
+<listitem>
+<para>
+A <sgmltag class="element">tbody</sgmltag> is a required element in a
+table. There are no attributes. The <sgmltag
+class="element">tbody</sgmltag> contains rows.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="row"><sgmltag class="starttag">row</sgmltag></term>
+<listitem>
+<para>
+A <sgmltag class="element">row</sgmltag> corresponds directly with the
+rows of the table. Rows contain <sgmltag
+class="starttag">entry</sgmltag> tags, one for each column in the table,
+as specified by the <sgmltag class="attribute">cols</sgmltag> attribute
+on the <link linkend="tgroup"><sgmltag
+class="starttag">tgroup</sgmltag></link> tag.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="entry"><sgmltag class="starttag">entry</sgmltag></term>
+<listitem>
+<para>
+The entry is the basic building block of a table. Each entry corresponds
+to one  <quote>data cell</quote>  in the table.  There must be  as many
+<sgmltag  class="starttag">entry</sgmltag>  tags  in  each  row  as  the
+<sgmltag   class="attribute">cols</sgmltag>  attribute   on   the  <link
+linkend="tgroup"><sgmltag  class="starttag">tgroup</sgmltag></link> tag.
+There are no attributes used in &tde; Documentation. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="thead"><sgmltag class="starttag">thead</sgmltag></term>
+<listitem>
+<para>
+<sgmltag class="starttag">thead</sgmltag> can be used to create a
+heading row for the table. It must appear before the <sgmltag
+class="element">tbody</sgmltag> element, and should normally contain one
+<sgmltag class="element">row</sgmltag> and as many <sgmltag
+class="element">entry</sgmltag> elements as the rest of the table.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="tfoot"><sgmltag class="starttag">tfoot</sgmltag></term>
+<listitem>
+<para><sgmltag class="starttag">tfoot</sgmltag> is not currently used in
+&tde; Documentation. If you want to use it, please see the Duck book
+for information.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<example>
+<title>An <sgmltag class="starttag">informaltable</sgmltag>
+template</title>
+<screen width="40">
+<markup>
+&lt;informaltable&gt;
+&lt;tgroup cols="2"&gt;
+&lt;tbody&gt;
+&lt;row&gt;
+&lt;entry&gt;&lt;/entry&gt;
+&lt;entry&gt;&lt;/entry&gt;
+&lt;/row&gt;
+&lt;/tbody&gt;
+&lt;/tgroup&gt;
+&lt;/informaltable&gt;
+</markup>
+</screen>
+</example>
+
+<example>
+<title>A <sgmltag class="starttag">table</sgmltag> template</title>
+<screen width="40">
+<markup>
+&lt;table&gt;
+&lt;title&gt;&lt;/title&gt;
+&lt;tgroup cols="2"&gt;
+&lt;tbody&gt;
+&lt;row&gt;
+&lt;entry&gt;&lt;/entry&gt;
+&lt;entry&gt;&lt;/entry&gt;
+&lt;/row&gt;
+&lt;/tbody&gt;
+&lt;/tgroup&gt;
+&lt;/table&gt;
+</markup>
+</screen>
+</example>
+
+</chapter>
+
+<chapter id="gui">
+<title>The &GUI;  elements, menus, toolbars and
+shortcuts.</title>
+
+<variablelist>
+
+<varlistentry>
+<term id="action"><sgmltag class="starttag">action</sgmltag></term>
+<listitem>
+<para>
+The result of a user action. This does not need to be a complete
+sentence, or even more than a single word. For example, <quote>This
+button &lt;action&gt;closes the dialog&lt;/action&gt;.</quote> The main
+place you will find this in &tde; Documentation is in the Menu and
+Command reference chapters of the manuals.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="guibutton"><sgmltag
+class="starttag">guibutton</sgmltag></term>
+<listitem>
+<para>
+The text on a button that you click on. Icons, Radio buttons and check
+boxes are not considered buttons in this sense.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="guiicon"><sgmltag class="starttag">guiicon</sgmltag></term>
+<listitem>
+<para>
+The name or description of an icon.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="guilabel"><sgmltag class="starttag">guilabel</sgmltag></term>
+<listitem>
+<para>
+The text of anything that is labelled on screen, and isn't a button,
+icon, menu, or menu item. For example, the name of a dialog box, the
+name of a tab in that dialog box, and the name of a label by a checkbox.
+</para>
+<para>Take care that the text exactly matches the label on screen. If
+it has a <literal>:</literal> on the dialog box, put the
+<literal>:</literal> into your documentation. Match the
+capitalization.  There is a script in the tde-i18n module called
+<filename>check-gui-texts</filename> which you can use to help check
+that your text matches exactly what is in the application. During
+translation, the translators can use this script to generate
+translations from their translations of the &GUI; itself, but this
+will only work if the English text matches precisely.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="guimenu"><sgmltag class="starttag">guimenu</sgmltag></term>
+<listitem>
+<para>
+The top level name of a menu (that is, the name you can see on the menu
+bar when the menu isn't open).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="guimenuitem"><sgmltag
+class="starttag">guimenuitem</sgmltag></term>
+<listitem>
+<para>
+The final item you select on the menu, that actually performs an action.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="guisubmenu"><sgmltag
+class="starttag">guisubmenu</sgmltag></term>
+<listitem>
+<para>
+A submenu. That is, a menu which has items both above and below it in
+the hierarchy.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="keycap"><sgmltag class="starttag">keycap</sgmltag></term>
+<listitem>
+<para>
+A keycap is a key as it is labelled on your keyboard.
+<keycap>Home</keycap> is a keycap on a standard English keyboard.
+<keycap>Alt Gr</keycap> is a standard key on many European keyboards.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="keycode"><sgmltag class="starttag">keycode</sgmltag></term>
+<listitem>
+<para>
+The internal identifier for a key on the keyboard. Used very
+infrequently, but you may find need for it, for example when describing
+entries in rc files.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="keysym"><sgmltag class="starttag">keysym</sgmltag></term> 
+<listitem>
+<para>
+Right arrow is the <sgmltag class="starttag">keysym</sgmltag> for the
+<sgmltag class="starttag">keycap</sgmltag> that looks like
+<keycap>-></keycap>. Please note this is a &tde; specific use of
+<sgmltag class="starttag">keysym</sgmltag>, and does not precisely
+follow the examples in the Duck Book.
+</para>
+</listitem>  
+</varlistentry>
+
+<varlistentry>
+<term id="menuchoice"><sgmltag
+class="starttag">menuchoice</sgmltag></term>
+<listitem>
+<para>
+A menuchoice describes a menu entry. You should use <sgmltag
+class="starttag">menuchoice</sgmltag> anywhere you are describing how
+to reach a menu item. In normal text, there are no particular
+requirements. In a menu reference, the <sgmltag
+class="starttag">menuchoice</sgmltag> should also contain a <sgmltag
+class="starttag">shortcut</sgmltag> element describing the keyboard
+shortcut, and the contents should also be marked up with <sgmltag
+class="starttag">accel</sgmltag> as appropriate. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="shortcut"><sgmltag class="starttag">shortcut</sgmltag></term>
+<listitem>
+<para>
+A key combination that is a shortcut for a menu item. This is
+<emphasis>only</emphasis> used inside <sgmltag
+class="starttag">menuchoice</sgmltag> and contains <sgmltag
+class="starttag">keycombo</sgmltag> or <sgmltag
+class="starttag">keycap</sgmltag> that is defined as the keyboard
+shortcut in the menu. In the markup, it appears before the actual menu
+entries inside the <sgmltag class="starttag">menuchoice</sgmltag> You do
+not need to describe the shortcut every time the menu item is mentioned
+in the text, although it may be appropriate to do so on some occasions.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="mousebutton"><sgmltag
+class="starttag">mousebutton</sgmltag></term>
+<listitem>
+<para>
+The normal name of a mouse button. It will be normally be one
+of:</para>
+
+<itemizedlist>
+<listitem>
+<para><markup>&lt;mousebutton&gt;left&lt;/mousebutton&gt;</markup> or
+the entity <sgmltag class="genentity">LMB</sgmltag> 
+</para>
+</listitem>
+
+<listitem>
+<para><markup>&lt;mousebutton&gt;middle&lt;/mousebutton&gt;</markup> or
+the entity <sgmltag class="genentity">MMB</sgmltag>
+</para>
+</listitem>
+
+<listitem>
+<para><markup>&lt;mousebutton&gt;right&lt;/mousebutton&gt;</markup> or
+the entity <sgmltag class="genentity">RMB</sgmltag>.
+</para>
+</listitem>
+
+<listitem>
+<para><markup>&lt;mousebutton&gt;wheel&lt;/mousebutton&gt;</markup>
+</para>
+</listitem>
+</itemizedlist>
+
+<para>Wheel is used only in specific instructions for applications that
+support it, of course.</para>
+
+<para>
+Use the entities where possible, they are a lot less typing and
+are simple to remember (which is why we have provided them.)  If you are
+translating, check with your team leader, as the entities above are
+<emphasis>not</emphasis> translated, but you may have your own language
+specific ones to use in their place.
+</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="keycombo"><sgmltag class="starttag">keycombo
+action=""</sgmltag></term>
+<listitem>
+<para>
+A keycombo is a sequence or combination of keypresses that are performed
+together. A keycombo can contain <sgmltag
+class="starttag">keycap</sgmltag>, <sgmltag class="starttag">keysym</sgmltag> or <sgmltag class="starttag">mousebutton</sgmltag>, or
+any combination of these, in any order.</para> <para>It is normal to
+have them in the order <literal>modifier</literal>,
+<literal>Alpha-numeric</literal>, <literal>Mouse</literal>. That is,
+<keycombo>&Ctrl;<keycap>A</keycap></keycombo>, not
+<keycombo><keycap>A</keycap>&Ctrl;</keycombo>, unless pressing
+<keycap>A</keycap> then &Ctrl; actually is the shortcut.
+</para>
+
+<para>
+Keycombo requires an <sgmltag class="attribute">action</sgmltag>
+attribute, describing exactly how the keys (or mouse buttons) are
+combined. The choices are:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+<sgmltag class="attvalue">Click</sgmltag>
+</para>
+</listitem>
+
+<listitem>
+<para>
+<sgmltag class="attvalue">Double-Click</sgmltag>
+</para>
+</listitem>
+
+<listitem>
+<para><sgmltag class="attvalue">Other</sgmltag>
+</para>
+</listitem>
+
+<listitem>
+<para><sgmltag class="attvalue">Press</sgmltag>
+</para>
+</listitem>
+
+<listitem>
+<para><sgmltag class="attvalue">Seq</sgmltag>
+</para>
+</listitem>
+
+<listitem>
+<para><sgmltag class="attvalue">Simul</sgmltag>
+</para>
+</listitem>
+</itemizedlist>
+
+<para>
+You will most likely need to use <sgmltag class="attvalue">Seq</sgmltag>
+(for a sequence of keys that are pressed one after the other), or
+<sgmltag class="attvalue">Simul</sgmltag> for a combination of keys that
+are pressed at the same time. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="accel"><sgmltag class="starttag">accel</sgmltag></term>
+<listitem>
+<para>
+The accelerator key that can be used to access a <acronym>GUI</acronym>
+menu without a mouse. This is indicated in the menu by an underlined
+letter. Although we previously used this in the menu references, we
+have since decided not to, the maintenance is too high, and it causes
+an enormous amount of work during translation.
+</para>
+</listitem>
+</varlistentry> 
+
+</variablelist>
+
+<example>
+<title>An example from a menu reference entry</title>
+
+<screen width="40">
+<markup>
+&lt;varlistentry&gt;
+&lt;term&gt;&lt;menuchoice&gt;
+&lt;shortcut&gt;
+&lt;keycombo action="simul"&gt;&amp;Ctrl;
+&lt;keycap&gt;C&lt;/keycap&gt;&lt;/keycombo&gt;
+&lt;/shortcut&gt;
+&lt;guimenu&gt;Edit&lt;/guimenu&gt;
+&lt;guimenuitem&gt;Copy&lt;/guimenuitem&gt;
+&lt;/menuchoice&gt;&lt;/term&gt;
+&lt;listitem&gt;&lt;para&gt;&lt;action&gt;Copy the selected text&lt;/action&gt; to the
+clipboard&lt;/para&gt;&lt;/listitem&gt;
+&lt;/varlistentry&gt;
+
+&lt;varlistentry&gt;
+&lt;term&gt;&lt;menuchoice&gt;
+&lt;shortcut&gt;&lt;keycombo action="simul"&gt;&amp;Ctrl;
+&lt;keycap&gt;V&lt;/keycap&gt;
+&lt;/keycombo&gt;&lt;/shortcut&gt;
+&lt;guimenu&gt;Edit&lt;/guimenu&gt;
+&lt;guimenuitem&gt;Paste&lt;/guimenuitem&gt;
+&lt;/menuchoice&gt;&lt;/term&gt;
+&lt;listitem&gt;&lt;para&gt;&lt;action&gt;Paste&lt;/action&gt; the contents of
+the clipboard at the cursor.&lt;/para&gt;&lt;/listitem&gt;
+&lt;/varlistentry&gt;
+</markup>
+</screen>
+
+<para>
+Please note, this is very complicated markup, and until you have
+written a few it's very hard to follow, but it does get much easier with
+practise! Although indenting is discouraged in general, this is one
+place where you might want to use some indenting and white space to make
+it clearer while writing, at least when you are beginning. There are
+also no rules as to when you must start a new line for a new element, so
+format the markup to suit your own taste while you are writing, if that
+makes it easier for you to follow.
+</para>
+</example>
+
+</chapter>
+
+<chapter id="actions-and-commands">
+<title>Describing actions and commands</title>
+
+<variablelist>
+
+<varlistentry>
+<term id="replaceable"><sgmltag
+class="starttag">replaceable</sgmltag></term>
+<listitem>
+<para>
+Use this for placeholder or sample text, that a user would not
+actually type, but would instead replace with the correct text for
+their environment. For example, <markup>Edit the file
+&lt;filename&gt;&lt;replaceable&gt;/usr/local/foo/bar&lt;/replaceable&gt;&lt;/filename&gt;</markup>,
+because it may already be established that <filename
+class="directory">/usr/local</filename> is only the default location
+of this file, and the user may have it installed to &eg; <filename
+class="directory">/opt/</filename> instead.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="application"><sgmltag
+class="starttag">application</sgmltag></term>
+<listitem>
+<para>
+Use this to mark up the name of any software program mentioned in the
+text. Don't use this to mark up the actual command issued to execute
+the application. For example, <sgmltag
+class="starttag">application&gt;Kate&lt;/application</sgmltag> is the
+name of  the editor, but <sgmltag
+class="starttag">command&gt;kate&lt;/command</sgmltag> is the name of
+the command that starts the <application>Kate</application> 
+application.</para>
+<note>
+<para>
+All &tde; applications, and several non-&tde; but very common
+applications, are provided as entities.
+</para>
+</note>
+
+<para>
+For the &tde; applications, using the entities will save you much
+typing, and will ensure that applications are always referred to with
+their correct name across all documentation. The entity is always the
+application's executable name, in lower case, &eg; <sgmltag
+class="genentity">kcontrol</sgmltag>, <sgmltag
+class="genentity">konqueror</sgmltag> or <sgmltag
+class="genentity">kmail</sgmltag>.
+</para>
+
+<para>
+For non-&tde; applications, one of the major reasons to use the entities
+is that there are legal implications, so far as we are required to
+acknowledge trademarks and copyrights held by others outside our
+organisation. You will find in <xref linkend="appendix-entities"/> a
+list containing a list of the more common non-&tde; application
+entities.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="interface"><sgmltag
+class="starttag">interface</sgmltag></term> 
+<listitem>
+<para>
+Catch all element for gui interface items that do not have a more
+specific tag. You can use this to markup things like the <quote>View
+pane</quote> in &khelpcenter;, or the <quote>Board</quote> in
+&kjumpingcube;. 
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="userinput"><sgmltag
+class="starttag">userinput</sgmltag></term>
+<listitem>
+<para>
+<emphasis>Any</emphasis> text that the user must type, including
+commands and data entry.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="screen"><sgmltag class="starttag">screen</sgmltag></term>
+<listitem>
+<para>
+Used to represent the computer screen (usually to represent a terminal
+or console.)  Text contained in <sgmltag
+class="starttag">screen</sgmltag> is considered to be literal text &mdash;
+line breaks and white space are honored and it will be rendered with a
+mono-spaced font. Don't use screen when what you really want is an
+example, or an informal example.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="command"><sgmltag class="starttag">command</sgmltag></term>
+<listitem>
+<para>
+Text the user enters to instruct the computer or an application
+to do something. <userinput><command>ls
+<option>-al</option></command></userinput> is a command (it's also userinput,
+and has options.)  <userinput><command>/join #tde</command></userinput>
+in an <acronym>irc</acronym> client is a command (and again, is
+userinput.)
+</para>
+
+<para>
+Commands are not <sgmltag class="element">userinput</sgmltag> when you
+are not expecting the user to actually type them, for example in the
+sentence <quote>The output from the <command>ls</command> command should
+show you...</quote>, the text <quote>ls</quote> is a command, but is not
+<sgmltag class="element">userinput</sgmltag> in this context.
+</para>
+
+<para>
+Applications not marked up with the <sgmltag
+class="starttag">application</sgmltag> tag are also considered commands,
+for example, <command>gcc</command>, <command>automake</command> and
+<command>autoconf</command>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="prompt"><sgmltag class="starttag">prompt</sgmltag></term>
+<listitem>
+<para>
+The prompt at which a user types input. For most &tde;
+Documentation, this has been standardised as
+<sgmltag
+class="starttag">prompt</sgmltag><sgmltag class="genentity">percnt</sgmltag><sgmltag
+class="endtag">prompt</sgmltag> (which is the &percnt; character).
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="option"><sgmltag class="starttag">option</sgmltag></term>
+<listitem>
+<para>An optional parameter to a command. Since we write about &UNIX;
+platforms, an option on the commandline is almost always indicated by a
+<quote>-</quote>, but there are exceptions (&eg;,
+<userinput><command>tar</command> <option>zxvf</option>
+<replaceable>filename.tar.gz</replaceable></userinput> or
+<userinput><command>ps</command> <option>ax</option></userinput>, which
+are marked up as
+<markup>&lt;userinput&gt;&lt;command&gt;tar&lt;/command&gt;
+&lt;option&gt;zxvf&lt;/option&gt;
+&lt;replaceable&gt;filename.tar.gz&lt;/replaceable&gt;&lt;/userinput&gt;</markup>
+and <markup>&lt;userinput&gt;&lt;command&gt;ps&lt;/command&gt;
+&lt;option&gt;ax&lt;/option&gt;&lt;/userinput&gt;</markup> respectively.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="envar"><sgmltag class="starttag">envar</sgmltag></term>
+<listitem>
+<para>
+An environment variable. Note that the variable indicator (usually $
+for &UNIX;) is not part of the name of the environment variable, so it
+is correct to do this:
+<markup>$&lt;envar&gt;TDEDIR&lt;/envar&gt;</markup>. There are no
+attributes in use in &tde; Documentation.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="errorcode"><sgmltag class="starttag">errorcode</sgmltag></term>
+<listitem>
+<para>
+A (usually numeric, but not always) error
+code. <errorcode>SIGSEGV</errorcode> is an errorcode, as is
+<errorcode>404</errorcode> as you might receive when you are web
+browsing.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="errorname"><sgmltag class="starttag">errorname</sgmltag></term>
+<listitem>
+<para>
+The actual text of an error message - to reuse the
+<errorcode>404</errorcode> example, the <sgmltag
+class="starttag">errorname</sgmltag> might be <errorname>Page not
+found</errorname>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="errortype"><sgmltag class="starttag">errortype</sgmltag></term>
+<listitem>
+<para>
+The type of error, &eg; <errortype>fatal</errortype>
+or <errortype>recoverable</errortype>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="filename"><sgmltag class="starttag">filename</sgmltag></term>
+<listitem>
+<para>
+Use <sgmltag class="starttag">filename</sgmltag> for all occurrences of
+file names including:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Directory names &mdash; with the attribute <markup>class="directory"</markup>
+</para>
+</listitem>
+<listitem>
+<para>
+Paths
+</para>
+</listitem>
+<listitem>
+<para>
+File names
+</para>
+</listitem>
+<listitem>
+<para>
+File name placeholders (which should also be tagged with
+<sgmltag class="starttag">replaceable</sgmltag>
+</para>
+</listitem>
+</itemizedlist>
+
+<para>
+Do not use <sgmltag class="starttag">filename</sgmltag> for file
+fragments or extensions (&ie; <literal role="extension">*.tgz</literal>
+which should instead be marked up as <link linkend="literal"><sgmltag
+class="starttag">literal role="extension"</sgmltag></link>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="symbol"><sgmltag class="starttag">symbol</sgmltag></term>
+<listitem>
+<para>
+Symbols are things that are replaced by the computer when they are
+processed. It's difficult to say when things are a symbol and when they
+are not - if there is a more specific element to use (&eg; <sgmltag
+class="starttag">envar</sgmltag> or <sgmltag
+class="starttag">constant</sgmltag> then you should use that instead.
+</para>
+</listitem> 
+</varlistentry>
+
+</variablelist>
+
+</chapter>
+
+<chapter id="questions-and-answers">
+<title>Questions and Answers</title>
+
+<variablelist>
+<varlistentry>
+<term id="qandaset"><sgmltag class="starttag">qandaset</sgmltag></term>
+<listitem>
+<para>
+A set of questions and answers, suitable for a
+&FAQ;. <sgmltag class="starttag">qandaset</sgmltag>  must
+contain <sgmltag class="starttag">qandaentry</sgmltag>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="qandaentry"><sgmltag class="starttag">qandaentry</sgmltag></term>
+<listitem>
+<para>
+Each question and answer pair is a <sgmltag
+class="starttag">qandaentry</sgmltag>.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="question"><sgmltag class="starttag">question</sgmltag></term>
+<listitem>
+<para>
+The question being asked. It must be inside a qandaentry, and
+it must have a matching answer.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="answer"><sgmltag class="starttag">answer</sgmltag></term>
+<listitem>
+<para>
+The answer to the matching question in the same qandaset.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<example>
+<title><sgmltag class="starttag">qandaset</sgmltag> Template</title>
+<screen width="40"><markup>
+&lt;qandaset&gt;
+&lt;qandaentry&gt;
+&lt;question&gt;
+&lt;/question&gt;
+&lt;answer&gt;
+&lt;/answer&gt;
+&lt;/qandaentry&gt;
+&lt;/qandaset&gt;
+</markup></screen>
+</example>
+
+</chapter>
+
+<chapter id="screenshots-and-examples">
+<title>Images and Examples</title>
+
+<variablelist>
+
+<varlistentry>
+<term id="screenshot"><sgmltag class="starttag">screenshot</sgmltag></term>
+<listitem>
+<para>
+Wrapper around screenshots. Use this when you are including a
+screenshot in your document.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="screeninfo">
+<sgmltag class="starttag">screeninfo</sgmltag></term>
+<listitem>
+<para>
+Screeninfo is a description of the screenshot. It's common (but not
+required) to reuse this text in the textobject element, as it saves
+translation time. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="mediaobject"><anchor id="inlinemediaobject"/><sgmltag
+class="starttag">mediaobject</sgmltag> and <sgmltag
+class="starttag">inlinemediaobject</sgmltag></term>
+<listitem>
+<para>
+Use <sgmltag class="element">inlinemediaobject</sgmltag> to insert an
+inline image (that is, one that is inside a paragraph of text, or is the
+only item in a table entry. Use <sgmltag
+class="element">mediaobject</sgmltag> for all other images. If the
+image is a screenshot, the <sgmltag
+class="element">mediaobject</sgmltag> should be wrapped with a
+<sgmltag class="element">screenshot</sgmltag> element. mediaobjects
+contain the following items: 
+</para>
+
+<variablelist>
+<varlistentry><term id="imageobject"><sgmltag class="starttag">imageobject</sgmltag></term>
+<listitem>
+<para>
+Imageobject contains information about one specific image. DocBook
+allows you to add more than one imageobject, in order to provide
+alternatives if the user is unable to see the preferred image. We don't
+currently use this functionality in &tde; Documentation, but may do at
+some time in the future.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="imagedata"><sgmltag class="emptytag">imagedata fileref=""
+format=""</sgmltag></term> 
+<listitem>
+<para>
+This element holds the actual image reference. The fileref
+indicates the location of the image. You should always keep images in the same
+directory as the document itself, so you need only put the filename into the
+fileref attribute. The format indicates the type of image you are including.
+For &tde; this should be <sgmltag class="attvalue">PNG</sgmltag>. Do
+<emphasis>not</emphasis> use gif format images for &tde; documents.
+</para>
+<para>
+This is one of few <quote>empty</quote> elements in use in &tde;
+Documentation. This means there is no &lt;/imagedata&gt;, but you
+should <emphasis>always</emphasis> close the element as shown above,
+with a final <quote>/</quote>.
+</para>
+<para>
+Keep the images in the same directory as your
+<filename>index.docbook</filename>, don't create a separate directory to
+store them in.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="textobject"><sgmltag
+class="starttag">textobject</sgmltag></term>
+<listitem>
+<para>
+Encloses the text part of a screenshot, which for &tde; Documentation
+means it contains a <sgmltag class="starttag">phrase</sgmltag> element.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="phrase"><sgmltag class="starttag">phrase</sgmltag></term>
+<listitem>
+<para>
+A short descriptive phrase about the image contents, this element is
+contained in the <sgmltag class="starttag">textobject</sgmltag> element.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="caption"><sgmltag class="starttag">caption</sgmltag></term>
+<listitem>
+<para>
+If you want the image to have a caption when displayed, you can add
+this. It's not required for &tde; documents, but recommended,
+especially if there are several images near each other and there could
+be confusion as to which you are referring in the text.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="informalexample"><sgmltag
+class="starttag">informalexample</sgmltag></term>
+<listitem>
+<para>
+Use this element to enclose any informal examples you use in your
+document. There are no attributes. An informal example can contain
+almost any markup, so feel free to use them liberally. They should
+generally not be part of a paragraph.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="example"><sgmltag class="starttag">example</sgmltag></term>
+<listitem>
+<para>
+An example is a more formal example, which has a title and an entry in
+the table of contents. Use sparingly, because having a hundred examples
+listed in the contents of a 5 page document lessens their usefulness.
+However, don't hesitate to use when you think it's necessary.
+</para>
+<para>
+I've used them in this document to make it easy to quickly go to the
+small <quote>template</quote> examples for complex markup, because you
+can find them directly from the table of contents. Less difficult
+examples in this document have <sgmltag
+class="starttag">informalexample</sgmltag> instead. Use your best
+judgement. As with <sgmltag class="starttag">informalexample</sgmltag>,
+they can contain almost any markup.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<example>
+<title>A screenshot example</title>
+
+<screen width="40">
+<markup>
+&lt;screenshot&gt;
+&lt;screeninfo&gt;An example image&lt;/screeninfo&gt;
+&lt;mediaobject&gt;
+&lt;imageobject&gt;
+&lt;imagedata fileref="example.png" format="PNG" /&gt;
+&lt;/imageobject&gt;
+&lt;textobject&gt;
+&lt;phrase&gt;An example image&lt;/phrase&gt;
+&lt;/textobject&gt;
+&lt;/mediaobject&gt;
+&lt;/screenshot&gt;
+</markup>
+</screen>
+</example>
+</chapter>
+
+<chapter id="other-markup">
+<title>General markup (not covered elsewhere)</title>
+
+<variablelist>
+<varlistentry>
+<term id="abbrev"><sgmltag class="starttag">abbrev</sgmltag></term>
+<listitem>
+<para>
+Abbreviations are shortened forms of longer words.
+</para>
+
+<para>
+Abbreviations are not normally pronounced in speech. Examples are &eg;
+and &ie;. This is a &tde; specific distinction, please stick to
+it.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="acronym"><sgmltag class="starttag">acronym</sgmltag></term>
+<listitem>
+<para>
+Acronyms are shortened forms of words or phrases, often made up of the
+initials of the words in a phrase. Acronyms are normally pronounced in
+speech as well as written. Examples are &GUI; and
+&tde;. As with <sgmltag class="starttag">abbrev</sgmltag>, this is a
+&tde; specific distinction.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="attribution">
+<sgmltag class="starttag">attribution</sgmltag></term>
+<listitem>
+<para>
+If you use <sgmltag class="starttag">quote</sgmltag> or <sgmltag
+class="starttag">blockquote</sgmltag>, the source of the quote (that is,
+<emphasis>who</emphasis> you are quoting) should be cited with this tag.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="blockquote"><sgmltag
+class="starttag">blockquote</sgmltag></term>
+<listitem>
+<para>
+Use this when you want to quote a passage of text that should be set off
+from the main text, for example, an entire paragraph from a book or
+other source. Use <sgmltag class="starttag">quote</sgmltag> to quote a
+passage of text that is not to be set off, for example a short sentence
+or comment from another person. Use both of them as little as you can,
+there are copyright issues to quoting from other works inside &tde;
+Documentation. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="emphasis"><sgmltag class="starttag">emphasis</sgmltag></term>
+<listitem>
+<para>
+Use this to emphasise text. Don't use it to mark up file names,
+commands, or anything else. Use it where you might type in all caps in
+an email, for emphasis of one word or short phrase, and try not to use
+it too much. Emphasis loses it's power when over used.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="computeroutput"><sgmltag
+class="starttag">computerouput</sgmltag></term>
+<listitem>
+<para>
+Text the user can see on the computer screen. For example, a
+listing of a directory as produced after the command
+<command>ls</command> would be <sgmltag
+class="element">computeroutput</sgmltag>. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="epigraph"><sgmltag class="starttag">epigraph</sgmltag></term>
+<listitem>
+<para>
+A short quote or saying at, sometimes used at the beginning of a chapter
+as an introduction. Use sparingly, no attributes used by &tde;.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="equation"><sgmltag class="starttag">equation</sgmltag></term>
+<listitem>
+<para>
+Equation is used if you need to mark up a mathematical equation. You
+are unlikely to need to use this in &tde; Documents.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="hardware"><sgmltag class="starttag">hardware</sgmltag></term>
+<listitem>
+<para>
+Used when referring to a piece of computer hardware, &eg;
+<hardware>Floppy Drive</hardware> or <hardware>Monitor</hardware>.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="lineannotation"><sgmltag
+class="starttag">lineannotation</sgmltag></term>
+<listitem>
+<para>
+A comment, for example in a <sgmltag
+class="starttag">programlisting</sgmltag>. This is
+<emphasis>not</emphasis> for comments contained in the text, it is for
+comments by the author (you) <emphasis>about</emphasis> the text.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="literal"><sgmltag class="starttag">literal</sgmltag></term>
+<listitem>
+<para>
+In &tde; Documentation, this is markup of last resort (or <quote>the
+least of all evils</quote>)  Use it only for things that must be marked
+up, but have no appropriate tag, and preferably only for the following
+things (already decided on:)
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<sgmltag class="starttag">literal
+role="extension"&gt;*.tar.gz&lt;/literal</sgmltag>
+</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="literallayout"><sgmltag
+class="starttag">literallayout</sgmltag></term>
+<listitem>
+<para>
+Use very sparingly, when it is absolutely vital that some text is
+presented exactly as it appears, including white space and line breaks.
+There is almost always a better tag to use than this (screen and
+computeroutput together, or even a screenshot).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="markup"><sgmltag class="starttag">markup</sgmltag></term>
+<listitem>
+<para>
+Use to wrap markup examples, for text that should be represented
+literally. Examples are this document, and documents that have
+<abbrev>HTML</abbrev> markup included literally in them. Other than
+meta-documentation like this, you probably won't have much need for
+<sgmltag class="element">markup</sgmltag>. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="optional"><sgmltag class="starttag">optional</sgmltag></term>
+<listitem>
+<para>
+Optional information, usually in user input. Not used to date in &tde;
+Documentation, but it may be appropriate in some circumstances.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="para"><sgmltag class="starttag">para</sgmltag></term>
+<listitem>
+<para>
+A paragraph. This is the most common tag. You do not need to enclose
+lists, tables, or other markup with <sgmltag
+class="starttag">para</sgmltag>. Sometimes however, you might want to do
+so, especially with <sgmltag class="starttag">screen</sgmltag> and some
+types of lists, when they actually are still part of the current
+paragraph.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="quote"><sgmltag class="starttag">quote</sgmltag></term>
+<listitem>
+<para>
+Use when you are quoting something or someone, inside a sentence. Also
+use if you want a word or phrase to be <quote>enclosed in quotes</quote>
+like this.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="trademark"><sgmltag class="starttag">trademark
+class=""</sgmltag></term>
+<listitem>
+<para>
+Used to denote that a word is a trademark. There is the optional
+attribute <sgmltag class="attribute">class</sgmltag> which should
+contain one of the following, if appropriate:
+</para>
+<itemizedlist>
+<listitem><para>copyright</para></listitem>
+<listitem><para>registered</para></listitem>
+<listitem><para>service</para></listitem>
+<listitem><para>trade</para></listitem>
+</itemizedlist>
+<para>
+If there is no <sgmltag class="attribute">class=""</sgmltag> attribute,
+<quote>trade</quote> is assumed.
+</para>
+<para>
+We have provided entities, marked up appropriately, for very commonly
+met trademarks, including &Qt; (<sgmltag
+class="genentity">Qt</sgmltag>), &UNIX; (<sgmltag
+class="genentity">UNIX</sgmltag>), &Linux; (<sgmltag
+class="genentity">Linux</sgmltag>) and many more.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="sgmltag"><sgmltag class="starttag">sgmltag</sgmltag></term>
+<listitem>
+<para>
+An <acronym>SGML</acronym> tag. This includes &XML; and &XHTML; tags.
+Use this for marking up individual components, but use <sgmltag
+class="starttag">markup</sgmltag> when you need to display a block of
+markup.
+</para>
+<para>
+<sgmltag class="element">sgmltag</sgmltag> will generate the correct
+markup characters for you, based on the <sgmltag
+class="attribute">class</sgmltag> attribute.
+</para>
+
+<para>
+Attribute values available:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+<sgmltag class="attvalue">attvalue</sgmltag>, for the contents of
+an attribute.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">attribute</sgmltag>, for attributes.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">element</sgmltag>, for element names.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">endtag</sgmltag>, for closing tags (&eg;
+<sgmltag class="endtag">para</sgmltag>.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">emptytag</sgmltag>, for tags which are
+<quote>empty</quote>, such as <sgmltag class="emptytag">br</sgmltag> in
+&XHTML;.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">genentity</sgmltag>, for markup up general
+entities. For example, <sgmltag class="genentity">nbsp</sgmltag> in
+&XHTML;.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">numcharref</sgmltag>, to mark up a numbered
+character reference. <sgmltag class="genentity">nbsp</sgmltag>, for
+example, could also be referred to as <sgmltag
+class="numcharref">160</sgmltag>.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">paramentity</sgmltag> <!-- TODO find a very -->
+<!-- short description to put here -->. You are unlikely to need this
+for any &tde; documentation.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">pi</sgmltag> <!-- TODO find a very -->
+<!-- short description to put here -->. Note this is an
+<acronym>SGML</acronym> <acronym>PI</acronym>, not an &XML; one. You
+are very unlikely to need this for any &tde; documentation.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">xmlpi</sgmltag>. An &XML; processing
+instruction, such as <!-- TODO find an example that is common -->
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">starttag</sgmltag>. An opening tag, such as
+<sgmltag class="starttag">para</sgmltag>. Most of this document is
+marked up this way.
+</para>
+</listitem>
+<listitem>
+<para>
+<sgmltag class="attvalue">sgmlcomment</sgmltag>.
+</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="superscript"><sgmltag
+class="starttag">superscript</sgmltag></term>
+<listitem>
+<para>
+Superscript as in x<superscript>2</superscript>. Unlikely to be
+required in most &tde; Documentation.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="msgtext"><sgmltag class="starttag">msgtext</sgmltag></term>
+<listitem>
+<para>
+The actual text of an informational message. Use <sgmltag
+class="starttag">errorname</sgmltag> for error
+messages.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="subscript"><sgmltag
+class="starttag">subscript</sgmltag></term>
+<listitem><para>Used to create things like H<subscript>2</subscript>O.
+Unlikely to be found in most &tde; Documents.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="foreignphrase"><sgmltag class="starttag">foreignphrase
+lang=""</sgmltag></term>
+<listitem>
+<para>
+Use this any time you need to use text in a language different than the
+main language of the document. This should be rare, but may occur
+especially in credits information. The <sgmltag
+class="attribute">lang</sgmltag> attribute should contain the normal two
+letter designation of the language. Please be careful with these, the
+<emphasis>Country</emphasis> and <emphasis>Language</emphasis> codes are
+sometimes different, &eg; <quote>se</quote> is the country code for
+Sweden, but the language code is <quote>sv</quote>. Using
+<quote>uk</quote> for British English would give you possibly unexpected
+results, as this is actually the language code for Ukrainian.
+</para>
+</listitem> 
+</varlistentry>
+</variablelist>
+
+</chapter>
+
+<chapter id="tips-hints-etc">
+<title>Admonitions: Tips, hints, and Warnings.</title>
+
+<para>
+Admonitions are set off from the main body of the text. Use these
+sparingly, as they disturb the flow of the writing, but don't be afraid
+to use them where necessary. Just make sure they
+<emphasis>are</emphasis> necessary when you do use them.
+</para>
+
+<para>
+We have settled on a preliminary order of importance for these elements,
+which differs from that explained in the Duck Book. Note that this
+particular order is for &tde; Documentation only, and use your own
+judgement which is the most appropriate element if your situation
+differs from those outlined.
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term id="warning"><sgmltag class="starttag">warning</sgmltag></term>
+<listitem>
+<para>
+Use warning when data loss could occur if you follow the procedure being
+described.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term id="caution"><sgmltag
+class="starttag">caution</sgmltag></term>
+<listitem>
+<para>
+A note of caution. Use this for example when the reader may lose easily
+recovered or replaceable information (&eg; user settings), or when they
+could cause data loss if they don't correctly follow the procedure being
+outlined.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry><term id="important"><sgmltag
+class="starttag">important</sgmltag></term>
+<listitem>
+<para>
+When there is no danger of data loss, but you wish to make clear to the
+reader a consequence that isn't immediately obvious (&eg; when changing
+the font for one instance of a program also changes the default setting,
+and this isn't clear from the &GUI;.)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term id="note"><sgmltag
+class="starttag">note</sgmltag></term>
+<listitem>
+<para>
+Information the user should be aware of, but is peripheral to the actual
+task being described.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="tip"><sgmltag class="starttag">tip</sgmltag></term>
+<listitem>
+<para>
+When you're giving a hint to make things easier or more productive for
+the reader.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="footnote"><sgmltag class="starttag">footnote
+id=""</sgmltag></term>
+<listitem>
+<para>
+Use very sparingly for things that really are footnotes. An example
+might be to note that the situation being described will be changing at
+some currently unknown future time. Most footnotes would better be
+marked up as notes, or tips. </para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="footnoteref"><sgmltag class="starttag">footnoteref
+linkend=""</sgmltag></term>
+<listitem>
+<para>
+You can refer to a footnote more than once, by using this element to
+refer to it's unique id. The footnote does not need to be in the same
+chapter. Use this very sparingly.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</chapter>
+
+<chapter id="synopsis">
+<title>The synopsis elements</title>
+
+<variablelist>
+
+<varlistentry>
+<term id="cmdsynopsis"><sgmltag
+class="starttag">cmdsynopsis</sgmltag></term>
+<listitem>
+
+<para>
+
+</para>
+
+<example>
+<title>How to markup a command synopsis</title>
+<screen width="40">
+
+&lt;cmdsynopsis&gt;
+&lt;command&gt;more&lt;/command&gt;
+&lt;group choice="opt"&gt;&lt;option&gt;-d&lt;/option&gt;
+&lt;option&gt;l&lt;/option&gt;&lt;option&gt;f&lt;/option&gt;
+&lt;option&gt;p&lt;/option&gt;&lt;option&gt;c&lt;/option&gt;
+&lt;option&gt;s&lt;/option&gt;&lt;option&gt;u&lt;/option&gt;
+&lt;/group&gt;
+&lt;arg&gt;-num&lt;/arg&gt;
+&lt;arg&gt;+/ pattern&lt;/arg&gt;
+&lt;arg&gt;+ linenum&lt;/arg&gt;
+&lt;arg rep="repeat"&gt;&lt;replaceable&gt;file&lt;/replaceable&gt;&lt;/arg&gt;
+&lt;/cmdsynopsis&gt;
+</screen>
+
+<para>This should generate:
+
+<cmdsynopsis>
+<command>more</command>
+<group
+choice="opt"><option>-d</option>
+<option>l</option><option>f</option>
+<option>p</option><option>c</option>
+<option>s</option><option>u</option></group>
+<arg>-num</arg>
+<arg>+/ pattern</arg>
+<arg>+ linenum</arg>
+<arg rep="repeat"><replaceable>file</replaceable></arg>
+</cmdsynopsis>
+</para>
+
+<para>
+There are several very nice examples in the Duck book at <ulink
+url="http://www.docbook.org">www.docbook.org</ulink>
+</para>
+</example>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="funcsynopsis"><sgmltag class="starttag">funcsynopsis</sgmltag></term>
+<listitem>
+
+<example>
+<title>How to markup a function synopsis</title>
+
+<screen>
+<markup>
+&lt;funcsynopsis&gt;
+&lt;funcprototype&gt;
+&lt;funcdef&gt;void &lt;function&gt;setFile&lt;/function&gt;&lt;/funcdef&gt;
+&lt;paramdef&gt;QString &lt;parameter&gt;file&lt;/parameter&gt;&lt;/paramdef&gt;
+&lt;/funcprototype&gt;
+&lt;/funcsynopsis&gt;
+
+&lt;funcsynopsis&gt;
+&lt;funcprototype&gt;
+&lt;funcdef&gt;void &lt;function&gt;setAutoResize&lt;/function&gt;&lt;/funcdef&gt;
+&lt;paramdef&gt;bool &lt;parameter&gt;&lt;replaceable&gt;val&lt;/replaceable&gt;&lt;/parameter&gt;&lt;/paramdef&gt;
+&lt;/funcprototype&gt;
+&lt;/funcsynopsis&gt;
+
+&lt;funcsynopsis&gt;
+&lt;funcprototype&gt;
+&lt;funcdef&gt;QString &lt;function&gt;getVideoCodec&lt;/function&gt;&lt;/funcdef&gt;&lt;void/&gt;
+&lt;/funcprototype&gt;
+&lt;/funcsynopsis&gt;
+</markup>
+</screen>
+
+<para>
+These would generate the following, respectively.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+<funcdef>void <function>setFile</function></funcdef><paramdef>QString <parameter>file</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis>
+<funcprototype>
+<funcdef>void <function>setAutoResize</function></funcdef><paramdef>bool <parameter><replaceable>val</replaceable></parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis>
+<funcprototype>
+<funcdef>QString <function>getVideoCodec</function></funcdef><void/>
+</funcprototype>
+</funcsynopsis>
+
+</example>
+
+<para>A function synopsis can contain the following:</para>
+<variablelist>
+
+<varlistentry>
+<term id="funcprototype"><sgmltag
+class="starttag">funcprototype</sgmltag></term> <listitem><para>Contains
+a prototype of the function. It can contain <sgmltag
+class="starttag">void</sgmltag>, <sgmltag
+class="starttag">varargs</sgmltag>, <sgmltag
+class="starttag">paramdef</sgmltag> or most commonly, a <sgmltag
+class="starttag">funcdef</sgmltag> which actually defines the
+function.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="funcdef"><sgmltag class="starttag">funcdef</sgmltag></term>
+<listitem><para>A function and it's return type. </para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="funcparams"><sgmltag class="starttag">funcparams</sgmltag></term>
+<listitem><para>Contains the list of parameters for the
+function.</para></listitem>
+</varlistentry>
+
+<varlistentry><term id="paramdef"><sgmltag class="starttag">paramdef</sgmltag></term>
+<listitem><para>Information about the parameters of a
+function.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="void"><sgmltag class="starttag">void</sgmltag></term>
+<listitem><para>An empty element in a function indicating there are no
+arguments.</para></listitem>
+</varlistentry>
+
+<varlistentry><term id="varargs"><sgmltag class="starttag">varargs</sgmltag></term>
+<listitem><para>An empty element in a function indicating there are multiple
+arguments, without specifically listing them. This is generally represented
+with an ellipsis (...). For example <function>int
+max(...);</function></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="funcsynopsisinfo"><sgmltag class="starttag">funcsynopsisinfo</sgmltag></term>
+<listitem><para>Not used in &tde; documentation.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="arg"><sgmltag class="starttag">arg</sgmltag></term>
+<listitem><para>Used inside <link linkend="cmdsynopsis"><sgmltag
+class="starttag">cmdsynopsis</sgmltag></link>. Since most &tde;
+applications are &GUI; only, you won't see this very often. See the entry
+for  <link linkend="cmdsynopsis"><sgmltag
+class="starttag">cmdsynopsis</sgmltag></link> for a full explanation and
+example.</para></listitem></varlistentry> 
+
+<varlistentry><term id="group"><sgmltag class="starttag">group</sgmltag></term>
+<listitem><para>Group</para></listitem></varlistentry>
+<varlistentry><term id="sbr"><sgmltag class="starttag">sbr</sgmltag></term>
+<listitem><para>sbr</para></listitem></varlistentry>
+<varlistentry><term id="synopfragment"><sgmltag class="starttag">synopfragment</sgmltag></term>
+<listitem><para>synopfragment</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="modifier"><sgmltag class="starttag">modifier</sgmltag></term>
+<listitem><para>A modifier modifies a class, field, or method synopsis.
+Examples are the words <quote>public</quote>, <quote>private</quote> or
+<quote>virtual</quote></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="fieldsynopsis"><sgmltag class="starttag">fieldsynopsis</sgmltag></term>
+<listitem><para>A field synopsis.</para></listitem>
+</varlistentry>
+
+<!-- 
+
+<varlistentry>
+<term id="classsynopsisinfo"><sgmltag
+class="starttag">classynopsisinfo</sgmltag></term>
+<listitem><para>A class synopsis</para></listitem>
+</varlistentry>
+
+
+
+<varlistentry>
+<term id="methodsynopsis"><sgmltag
+class="starttag">methodsynopsis</sgmltag></term>
+<listitem><para>A method synopsis</para>
+
+
+<classsynopsis language="cpp">
+<ooclass>
+<classname>QWidget</classname>
+</ooclass>
+<methodsynopsis>
+
+<methodname>QWidget::QWidget</methodname>
+<methodparam choice="opt">
+<funcparams>
+<parameter>QWidget* parent = 0</parameter></funcparams>
+</methodparam>
+<methodparam choice="opt">
+<type>const char*</type> <parameter>name = 0</parameter>
+</methodparam>
+</methodsynopsis>
+</classsynopsis>
+
+
+
+<methodsynopsis>
+	      <methodname>QWidget::QWidget</methodname>
+	      <methodparam choice="opt">
+		<funcparams>
+		<parameter>QWidget* parent = 0</parameter></funcparams>
+	      </methodparam>
+	      <methodparam choice="opt">
+		<parameter>const char* name = 0</parameter>
+	      </methodparam>
+	    </methodsynopsis>
+
+<classsynopsis language="cpp">
+<ooclass>
+<classname></classname>
+</ooclass>
+
+<destructorsynopsis>
+<void/>
+</destructorsynopsis>
+
+<fieldsynopsis>
+<varname></varname>
+</fieldsynopsis>
+
+<methodsynopsis>
+<methodname></methodname>
+<methodparam>
+<modifier></modifier> 
+<type></type> 
+<parameter></parameter>
+</methodparam>
+</methodsynopsis>
+<methodsynopsis>
+<methodname></methodname>
+<methodparam>
+<modifier></modifier>
+<type></type>
+<funcparams></funcparams>
+</methodparam>
+</methodsynopsis>
+
+<constructorsynopsis>
+<methodparam>
+<modifier></modifier> 
+<type></type> 
+<parameter></parameter>
+</methodparam>
+</methodsynopsis>
+<methodsynopsis>
+<methodname></methodname>
+<methodparam>
+<modifier></modifier>
+<type></type>
+<funcparams></funcparams>
+</methodparam>
+</constructorsynopsis>
+
+</classsynopsis>
+
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="destructorsynopsis"><sgmltag
+class="starttag">destructorsynopsis</sgmltag></term>
+<listitem><para>A destructor synopsis</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="constructorsynopsis"><sgmltag class="starttag">
+constructorsynopsis</sgmltag></term>
+<listitem><para>A constructor synopsis
+
+<constructorsynopsis>
+<methodname>QWidget::QWidget</methodname>
+<methodparam choice="opt">
+<funcparams><type>QWidget*</type> <parameter>parent = 0</parameter></funcparams>
+</methodparam>
+<methodparam choice="opt">
+<funcparams>
+<type>const char*</type> <parameter>name = 0</parameter></funcparams>
+</methodparam>
+</constructorsynopsis>
+
+<constructorsynopsis>
+	      <methodname>QWidget::QWidget</methodname>
+	      <methodparam choice="opt">
+		<funcparams>
+		<parameter>QWidget* parent = 0</parameter></funcparams>
+	      </methodparam>
+<methodparam choice="opt">
+		<parameter>const char* name = 0</parameter>
+</methodparam>
+    </constructorsynopsis>
+
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="methodparam"><sgmltag class="starttag">
+methodparam</sgmltag></term>
+<listitem><para>A parameter to a method, used inside a <sgmltag
+class="element">methodsynopsis</sgmltag></para></listitem>
+</varlistentry>
+-->
+</variablelist>
+</chapter>
+
+<chapter id="programming">
+<title>Markup for programming</title>
+
+<para>
+For formally marking up code examples or making a synopsis, you should
+study the Duck Book and the <link linkend="synopsis">Synopsis</link>
+chapter. The elements described below are mainly for marking up of
+pieces of source code that appear in the running text. Remember that
+&tde; and &tde; applications are written almost exclusively in C++, so
+our useage may differ in places from the examples in the Duck book,
+which may be describing other programming languages.
+</para>
+
+<para>
+To Developers reading this, remember most of the authors who may be
+documenting your work are unfamiliar with source code, and many of them
+like it that way. Therefore, the explanations here are more concerned
+with how to tell things apart than what they are for, and may make you
+cringe.
+</para>
+
+<para>To everyone reading this, this section is very much under
+construction so to speak. If you already need to use this markup, you
+can ask questions on the tde-docbook mailing list, which is the most
+likely place to get correct and up to date answers.</para>
+
+<variablelist>
+<varlistentry>
+<term id="classname"><sgmltag
+class="starttag">classname</sgmltag></term>
+<listitem>
+<para>
+Used to identify the name of a class in a programming language. In
+&tde; Documentation, you won't see this much in the user documentation,
+except for those applications which contain an <acronym>API</acronym> reference
+chapter, and occasionally in others. You will find it used a lot in the
+<application>TDevelop</application> documentation.
+</para> 
+
+<para>
+For non-programmers, as we're almost exclusively discussing &tde;
+applications written in C++ and using &Qt;, classnames are fairly easy
+to distinguish: They start with a capital Q or K, and are usually one
+word only, in the form of <classname>KApplication</classname> or
+<classname>QListBox</classname>.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="function"><sgmltag class="starttag">function</sgmltag>,
+<sgmltag class="starttag">methodname</sgmltag></term>
+<listitem><anchor id="methodname"/>
+<para>
+A function or <quote>subroutine</quote>. In C++, a function generally
+looks something like this: <function>foo();</function>. The semi-colon
+may not always be present and there may or may not be content inside the
+braces.
+</para> 
+
+<para>
+If you see things that have the form
+<methodname>Kfoo::bar()</methodname> these are not just functions, but
+also methods, so you would use the <sgmltag
+class="starttag">methodname</sgmltag> for these.
+</para>
+
+<para>
+Constructors are methods where the parts before and after the :: are the
+same, &eg; <methodname>KFoo::Kfoo()</methodname>.Destructors look like
+Constructors, but have a <literal>~</literal> after the :: &eg;
+<methodname>Kfoo::~Kfoo()</methodname>. The same things apply as with
+functions and methods: there may or may not be a ; at the end, and there
+may or may not be content inside the braces of a constructor (there is
+never content for a destructor).
+</para>
+
+<para>
+These are normally marked up as <sgmltag
+class="starttag">methodname</sgmltag>, but if you need to make a
+synopsis of a method, there are specific elements available: <link
+linkend="constructorsynopsis"><sgmltag
+class="starttag">constructorsynopsis</sgmltag></link> and <link
+linkend="destructorsynopsis"><sgmltag
+class="starttag">destructorsynopsis</sgmltag></link>
+</para> 
+
+<para>To recap: </para>
+
+<variablelist>
+<varlistentry>
+<term>Function</term>
+<listitem>
+<para>
+<function>foo()</function>
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Methodname</term>
+<listitem>
+<para><methodname>Kfoo::bar()</methodname>
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Constructor</term>
+<listitem>
+<para>
+<methodname>Kfoo::Kfoo()</methodname> These are methods in ordinary
+text, but when making a synopsis, have a more specific tag to use.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Destructor</term>
+<listitem>
+<para><methodname>Kfoo::~Kfoo()</methodname> These are methods in
+ordinary text, but when making a synopsis, have a more specific tag to
+use. 
+</para>
+</listitem> 
+</varlistentry>
+</variablelist>
+
+<para>
+Sometimes you really can't tell the difference, especially when they are
+being mentioned in passing in the text. Also, programmers tend to
+shorten and make shortcuts when referring to snippets of source. If
+it's very unclear what something is, mark it up with <sgmltag
+class="starttag">function</sgmltag> and ask the developer.
+</para>
+
+<tip>
+<para>
+Asking a developer <quote>What is foo?</quote> will likely result in a
+two page explanation of a finer point of C++ programming, which, if you
+could understand it, you wouldn't have needed to ask the question in the
+first place. It saves everyone a lot of time and frustration if you
+word the question <quote>Out of function, method, constructor and
+destructor, which is the best fit for foo?</quote>.
+</para>
+</tip>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="varname"><sgmltag class="starttag">varname</sgmltag></term>
+<listitem>
+<para>
+The name of a variable.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="returnvalue"><sgmltag
+class="starttag">returnvalue</sgmltag></term>
+<listitem>
+<para>
+The value returned by a function.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="token"><sgmltag class="starttag">token</sgmltag></term>
+<listitem>
+<para>
+A token is a placeholder, something that is replaced by an actual value
+during processing. (I need to come up with a useful example for a token)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="constant"><sgmltag class="starttag">constant</sgmltag></term>
+<listitem>
+<para>
+A constant. In the snippet:
+</para>
+<programlisting>enum MyType { Red = 0, Green, Blue, Yellow };</programlisting>
+<para><constant>Red</constant>, <constant>Green</constant>,
+<constant>Blue</constant> and <constant>Yellow</constant> should be
+marked up as <sgmltag class="starttag">constant</sgmltag></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="type"><sgmltag class="starttag">type</sgmltag></term>
+<listitem>
+<para>
+Used to classify a value. In the snippet:
+</para>
+<programlisting>enum MyType { Red = 0, Green, Blue, Yellow };</programlisting>
+<para><type>MyType</type> is a <sgmltag
+class="starttag">type</sgmltag></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="programlisting"><sgmltag
+class="starttag">programlisting</sgmltag></term>
+<listitem>
+<para>
+Use this to wrap any source code examples in your document. You don't
+need to use this for short snippets that are inline in the text, but you
+should use it for any examples longer than a line or two, or that are a
+separate block of text.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="structname"><sgmltag
+class="starttag">structname</sgmltag>,<sgmltag
+class="starttag">structfield</sgmltag></term>
+<listitem><anchor id="structfield"/>
+<para>
+Not used in &tde; Documentation, primarily because they are rare
+in &tde; source code, and are almost certainly never going to require
+marking up.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="parameter"><sgmltag
+class="starttag">parameter</sgmltag></term>
+<listitem>
+<para>
+Parameters can be used for commandlines as well as for code samples.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="classsynopsis"><sgmltag
+class="starttag">classsynopsis</sgmltag></term>
+<listitem>
+<para>
+A class synopsis
+</para>
+
+<classsynopsis class="class" language="cpp">
+<ooclass>
+<classname>DCOPStub</classname>
+</ooclass>
+<classsynopsisinfo>? not sure about what goes here ?</classsynopsisinfo>
+<methodsynopsis><type>enum</type> <methodname>Status</methodname>
+<methodparam>
+<parameter>CallSucceeded</parameter>
+</methodparam>
+<methodparam>
+<parameter>CallFailed</parameter>
+</methodparam>
+</methodsynopsis>
+</classsynopsis>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="initializer"><sgmltag
+class="starttag">initializer</sgmltag></term>
+<listitem>
+<para>
+An initializer
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="exceptionname"><sgmltag
+class="starttag">exceptionname</sgmltag></term>
+<listitem>
+<para>
+An exception name
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<anchor id="constructorsynopsis"/>
+<anchor id="destructorsynopsis"/>
+<anchor id="classsynopsisinfo"/>
+<anchor id="methodparam"/>
+<anchor id="methodsynopsis"/>
+
+</chapter>
+
+<chapter id="callouts">
+<title>Making Callouts</title>
+
+<para>
+Callouts are difficult, so they have their own chapter. Use callouts
+when you want to refer from text to specific parts of an image,
+programlisting, or synopsis. Using callouts with graphics is currently
+unused, and is somewhat problematic, so they will not (yet) be described
+here.
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term id="calloutlist"><sgmltag
+class="starttag">calloutlist</sgmltag></term>
+<listitem>
+<para>
+A list element that contains the callouts themselves. That is, a list
+of the explanations that belong to the indicated areas in the item being
+explained.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="callout"><sgmltag class="starttag">callout
+arearefs=""</sgmltag></term>
+<listitem>
+<para>
+The actual explanation or description of the called out area or line.
+The <sgmltag class="attribute">arearefs</sgmltag> attribute should
+contain the id of the appropriate callout you are referring to.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="programlistingco"><sgmltag
+class="starttag">programlistingco</sgmltag>
+and <sgmltag class="starttag">screenco</sgmltag></term>
+<listitem>
+<para><anchor id="screenco"/>
+Callouts applied to a programlisting or a screen element. Although they
+look more difficult than just embedding the callouts directly in the
+text, they really aren't too hard. The programlistingco contains one
+areaspec, and one programlisting. The screenco contains one areaspec
+and one screen element. The programlisting and screen elements are
+exactly as you would normally have.
+</para>
+<variablelist>
+
+<varlistentry>
+<term id="areaspec"><sgmltag class="starttag">areaspec</sgmltag></term>
+<listitem>
+<para>
+The areaspec contains a list of area elements, each of which describes
+one single callout.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="area"><sgmltag class="emptytag">area coords=""
+id=""</sgmltag></term>
+<listitem>
+<para>
+The area is another of the very few empty elements, so there is no
+<sgmltag class="endtag">area</sgmltag>. The <sgmltag
+class="attribute">id</sgmltag> attribute should contain a unique name
+for the item. The <sgmltag class="attribute">coords</sgmltag> contains
+a pair of numbers which indicate first the line and then the column
+where the co should appear. The line and column refer to the position
+in relation to the container element, <emphasis>not the entire
+document!</emphasis>. That is, in a screenco, the line and column
+numbers refer to the line <emphasis>within the <sgmltag
+class="element">screen</sgmltag> element</emphasis>.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<example>
+<title>Marking up callouts with <sgmltag
+class="starttag">screenco</sgmltag>.</title>
+<screen>
+<markup>
+&lt;screenco&gt;
+	&lt;areaspec&gt;
+	  &lt;area coords="2 65" id="currentdir"/&gt;
+	  &lt;area coords="3 65" id="updir"/&gt;
+	  &lt;area coords="4 75" id="hiddenfile"/&gt;
+	  &lt;area coords="10 75" id="backupfile"/&gt;
+	  &lt;area coords="13 70" id="hiddendir"/&gt;
+
+&lt;screen&gt;
+total 864
+drwx------   8 vampyr   vampyr       4096 Oct  2 18:01 ./             
+drwxr-xr-x  13 root     root         4096 Oct  1 16:32 ../    
+-rw-------   1 vampyr   vampyr         32 Sep  2 14:21 .MCOP-random-seed  
+-rw-------   1 vampyr   vampyr          0 Sep  2 14:42 .Xauthority
+-rw-r--r--   1 vampyr   vampyr       1899 Aug  6 19:32 .Xdefaults
+-rw-------   1 vampyr   vampyr        261 Sep 29 22:59 .bash_history
+-rw-r--r--   1 vampyr   vampyr         24 Aug  6 19:32 .bash_logout
+-rw-r--r--   1 vampyr   vampyr        285 Aug  6 19:34 .bash_profile
+-rw-r--r--   1 root     root          230 Aug  6 19:32 .bash_profile~ 
+-rw-r--r--   1 vampyr   vampyr        559 Aug  6 19:32 .bashrc
+-rw-r--r--   1 vampyr   vampyr       4044 Aug  6 19:32 .emacs
+drwxr-xr-x   7 vampyr   vampyr       4096 Sep 29 17:31 .trinity/
+&lt;/screen&gt;
+&lt;/screenco&gt;
+&lt;calloutlist&gt;
+&lt;callout arearefs="currentdir1"&gt;&lt;para&gt;The current directory.&lt;/para&gt;
+&lt;/callout&gt;
+&lt;callout arearefs="updir1"&gt;
+&lt;para&gt;One directory up in the tree.&lt;/para&gt;
+&lt;/callout&gt;
+&lt;callout arearefs="hiddenfile1"&gt;
+&lt;para&gt;A hidden file, indicated by the . beginning the name.&lt;/para&gt;
+&lt;/callout&gt;
+&lt;callout arearefs="backupfile1"&gt;
+&lt;para&gt;A backup or temporary file, indicated by the ~ ending the name.&lt;/para&gt;
+&lt;/callout&gt;
+&lt;callout arearefs="hiddendir1"&gt;
+&lt;para&gt;A hidden directory, which, like a hidden file, is indicated by the . at
+the start of the name.&lt;/para&gt;
+&lt;/callout&gt;
+&lt;/calloutlist&gt;
+</markup>
+</screen>
+
+<para>
+All this markup above, while it looks complicated is really quite simple
+if you study it closely. It would generate the following:
+</para>
+
+<screenco>
+	<areaspec>
+	  <area coords="2 65" id="currentdir1"/>
+	  <area coords="3 65" id="updir1"/>
+	  <area coords="4 75" id="hiddenfile1"/>
+	  <area coords="10 75" id="backupfile1"/>
+	  <area coords="13 70" id="hiddendir1"/>
+	</areaspec>
+
+<screen>
+total 864
+drwx------   8 vampyr   vampyr       4096 Oct  2 18:01 ./             
+drwxr-xr-x  13 root     root         4096 Oct  1 16:32 ../    
+-rw-------   1 vampyr   vampyr         32 Sep  2 14:21 .MCOP-random-seed  
+-rw-------   1 vampyr   vampyr          0 Sep  2 14:42 .Xauthority
+-rw-r--r--   1 vampyr   vampyr       1899 Aug  6 19:32 .Xdefaults
+-rw-------   1 vampyr   vampyr        261 Sep 29 22:59 .bash_history
+-rw-r--r--   1 vampyr   vampyr         24 Aug  6 19:32 .bash_logout
+-rw-r--r--   1 vampyr   vampyr        285 Aug  6 19:34 .bash_profile
+-rw-r--r--   1 root     root          230 Aug  6 19:32 .bash_profile~ 
+-rw-r--r--   1 vampyr   vampyr        559 Aug  6 19:32 .bashrc
+-rw-r--r--   1 vampyr   vampyr       4044 Aug  6 19:32 .emacs
+drwxr-xr-x   7 vampyr   vampyr       4096 Sep 29 17:31 .trinity/  
+</screen>
+</screenco>
+<calloutlist>
+<callout arearefs="currentdir1"><para>The current directory.</para>
+</callout>
+<callout arearefs="updir1">
+<para>One directory up in the tree.</para>
+</callout>
+<callout arearefs="hiddenfile1">
+<para>A hidden file, indicated by the . beginning the name.</para>
+</callout>
+<callout arearefs="backupfile1">
+<para>A backup or temporary file, indicated by the ~ ending the name.</para>
+</callout>
+<callout arearefs="hiddendir1">
+<para>A hidden directory, which, like a hidden file, is indicated by the . at
+the start of the name.</para>
+</callout>
+</calloutlist>
+</example>
+
+<variablelist>
+<varlistentry><term id="co"><sgmltag class="starttag">co</sgmltag></term>
+<listitem>
+<para>
+Indicates where a callout is. For &tde; <acronym>HTML</acronym>
+documentation, a small numbered graphic will be placed here, and also at
+the location of the explanation. These numbered graphics are links
+between the two places. It is entirely possible to embed the callout
+elements directly in the text you are describing, and this is perhaps
+the easiest way to do it. It isn't the most specific, but working out
+the line coordinates to use the more precise elements is difficult, so
+this way is acceptable for now.
+</para>
+</listitem> 
+</varlistentry>
+</variablelist>
+
+<example>
+<title>Marking up callouts by embedding directly in text</title>
+
+<screen>
+&lt;screen&gt;
+drwxr-xr-x   3 vampyr   vampyr       4096 Aug  6 19:32 .triniity/
+lrwxrwxrwx   1 vampyr   vampyr         15 Sep  3 19:46
+.tdeinit-whiterabbit.magicians.org-:0 -&gt; /tmp/.kinV4m2iI=  &lt;co id="symlink"/&gt;
+-rw-r--r--   1 vampyr   vampyr       2096 Aug  6 19:32 .tderc
+-r--------   1 vampyr   vampyr         21 Sep  2 14:21 .kxmlrpcd
+-rw-r--r--   1 vampyr   vampyr        185 Aug  6 19:32 .mailcap
+-rw-------   1 vampyr   vampyr         31 Sep  2 14:21 .mcoprc
+drwxr-xr-x   4 vampyr   vampyr       4096 Aug  6 19:32 .netscape/
+-rw-------   1 vampyr   vampyr     777947 Sep  2 14:42 .xsession-errors
+drwxr-xr-x   5 vampyr   vampyr       4096 Sep  2 14:42 Desktop/  &lt;co id="dir"/&gt;
+drwx------   2 vampyr   vampyr       4096 Aug  6 19:32 tmp/      
+-rw-r--r--   1 vampyr   vampyr       3836 Oct 13 16:44 notes.txt &lt;co id="file"/&gt;
+&lt;/screen&gt;
+
+&lt;calloutlist&gt;
+&lt;callout arearefs="symlink"&gt;
+&lt;para&gt;A symbolic link, indicated by the -&gt;, and showing the location it is
+linked to.&lt;/para&gt;
+&lt;/callout&gt;
+&lt;callout arearefs="dir"&gt;
+&lt;para&gt;An ordinary directory.&lt;/para&gt;
+&lt;/callout&gt;
+&lt;callout arearefs="file"&gt;
+&lt;para&gt;An ordinary file.&lt;/para&gt;
+&lt;/callout&gt;
+&lt;/calloutlist&gt;
+</screen>
+
+<para>
+Again it's really not as hard as it looks on first glance. This markup
+would generate the following:
+</para>
+
+<screen>
+drwxr-xr-x   3 vampyr   vampyr       4096 Aug  6 19:32 .trinity/
+lrwxrwxrwx   1 vampyr   vampyr         15 Sep  3 19:46
+.tdeinit-whiterabbit.magicians.org-:0 -> /tmp/.kinV4m2iI=  <co id="symlink"/>
+-rw-r--r--   1 vampyr   vampyr       2096 Aug  6 19:32 .tderc
+-r--------   1 vampyr   vampyr         21 Sep  2 14:21 .kxmlrpcd
+-rw-r--r--   1 vampyr   vampyr        185 Aug  6 19:32 .mailcap
+-rw-------   1 vampyr   vampyr         31 Sep  2 14:21 .mcoprc
+drwxr-xr-x   4 vampyr   vampyr       4096 Aug  6 19:32 .netscape/
+-rw-------   1 vampyr   vampyr     777947 Sep  2 14:42 .xsession-errors
+drwxr-xr-x   5 vampyr   vampyr       4096 Sep  2 14:42 Desktop/  <co id="dir"/>
+drwx------   2 vampyr   vampyr       4096 Aug  6 19:32 tmp/      
+-rw-r--r--   1 vampyr   vampyr       3836 Oct 13 16:44 notes.txt <co id="file"/>
+</screen>
+
+<calloutlist>
+<callout arearefs="symlink">
+<para>A symbolic link, indicated by the ->, and showing the location it is
+linked to.</para>
+</callout>
+<callout arearefs="dir">
+<para>An ordinary directory.</para>
+</callout>
+<callout arearefs="file">
+<para>An ordinary file.</para>
+</callout>
+</calloutlist>
+</example>
+
+<variablelist>
+<varlistentry>
+<term id="imageobjectco"><sgmltag
+class="starttag">imageobjectco</sgmltag></term>
+<listitem>
+<para>
+Currently unused in &tde; Documentation.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="mediaobjectco"><sgmltag
+class="starttag">mediaobjectco</sgmltag></term>
+<listitem>
+<para>
+Currently unused in &tde; Documentation.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="areaset">
+<sgmltag class="starttag">areaset</sgmltag></term>
+<listitem>
+<para>
+Currently unused in &tde; Documentation. This and the
+above two elements will be used eventually (just as soon as I figure out
+how they work).
+</para>
+</listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term id="graphicco"><sgmltag class="starttag">graphicco</sgmltag></term>
+<listitem>
+<para>
+Not to be used in &tde; Documentation at all.
+</para>
+</listitem>
+
+</varlistentry>
+</variablelist>
+
+</chapter>
+
+<chapter id="references-indexes-glossary">
+<title>References, indexes, and glossaries</title>
+
+<para>
+These elements are very underused in &tde; Documentation up to this point,
+and we will probably make an effort to implement them more fully at some
+point. In the meantime, you may use them if you wish, so they are
+explained here.
+</para>
+
+<sect1 id="glossaries">
+<title>Making a glossary</title>
+
+<variablelist>
+<varlistentry>
+<term id="glossterm"><sgmltag
+class="starttag">glossterm</sgmltag></term>
+<listitem>
+<para>
+Use this inline to identify words in the text that are explained further
+in a <link linkend="glossary"><sgmltag
+class="starttag">glossary</sgmltag></link> or <link
+linkend="glosslist"><sgmltag
+class="starttag">glosslist</sgmltag></link>. When it's placed inside a
+<sgmltag class="starttag">glossentry</sgmltag> it contains the term that
+glossary entry is defining (see the example below to see this in
+action.)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="glossary"><sgmltag class="starttag">glossary</sgmltag></term>
+<listitem>
+<para>
+Put this where you have the glossary appearing. This is usually
+at the end of the document, perhaps last before the credits section, or before
+an index. A glossary will become a separate section in the book.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="glosslist"><sgmltag class="starttag">glosslist</sgmltag></term>
+<listitem>
+<para>
+Use this if the glossary is fairly short and simple. It can
+appear anywhere a normal list could appear. For &tde; Documentation, a proper
+glossary is preferred, so keep use of <sgmltag
+class="starttag">glosslist</sgmltag> to a minimum, where your glossary
+would only contain a small handful of entries. Use your own judgement
+which is most appropriate. You might use a glosslist for example, to
+explain a list of terms which only appear in one section, but are very
+important to understanding that section and occur several times there,
+so you want the explanations to appear close to the text. 
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry><term id="glossdiv"><sgmltag
+class="starttag">glossdiv</sgmltag></term>
+<listitem>
+<para>
+Divides a glossary into several smaller sections. A good use of this in
+a very large glossary could be to break it up into separate sections for
+each letter in the alphabet.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="glossentry"><sgmltag class="starttag">glossentry
+id=""</sgmltag></term>
+<listitem>
+<para>
+Contains the actual entries in the glossary or glosslist, where you
+explain the terms you have marked up with glossterm in the text. You
+should give these an <sgmltag class="attribute">id</sgmltag>, so they
+can be linked to from the text, and crossreferenced between glossary
+entries.
+</para> 
+
+<para>
+A <sgmltag class="element">glossentry</sgmltag> always contains one
+<link linkend="glossterm"><sgmltag
+class="starttag">glossterm</sgmltag></link>. It also contains one <link
+linkend="glossdef"><sgmltag class="starttag">glossdef</sgmltag></link>,
+or one <link linkend="glosssee"><sgmltag
+class="starttag">glosssee</sgmltag></link>, or a <link
+linkend="glossdef"><sgmltag class="starttag">glossdef</sgmltag></link>
+and a <link linkend="glossseealso"><sgmltag
+class="starttag">glossseealso</sgmltag></link>.
+</para> 
+
+<tip>
+<para>
+I would suggest a consistent naming scheme, so glossary entries are easy
+to reference without having to go look them up all the time. For
+example, I use the form <sgmltag
+class="attribute">id="gloss-<replaceable>word</replaceable>"</sgmltag>,
+where <replaceable>word</replaceable> is the term that is being
+explained.
+</para>
+</tip>
+</listitem>
+</varlistentry>
+
+<varlistentry><term id="glossdef"><sgmltag
+class="starttag">glossdef</sgmltag></term>
+<listitem>
+<para>
+Contains the actual definitions of the terms
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="glosssee"><sgmltag class="starttag">glosssee
+otherterm=""</sgmltag></term>
+<listitem>
+<para>
+You can use this to save duplicating entries in the glossary. Instead
+of a <sgmltag class="starttag">glossdef</sgmltag> you can put <sgmltag
+class="starttag">glosssee</sgmltag> with the <acronym>id</acronym> of
+another <sgmltag class="starttag">glossentry</sgmltag>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="glossseealso"><sgmltag class="starttag">glossseealso
+otherterm=""</sgmltag></term>
+<listitem>
+<para>
+This is very similar to <sgmltag class="starttag">glosssee</sgmltag>,
+but instead of replacing the <sgmltag
+class="starttag">glossdef</sgmltag> it is in addition to
+it. 
+</para>
+</listitem> 
+</varlistentry>
+</variablelist>
+
+<para>
+If you compare a glossary entry to a variable list entry, you'll see the
+structure is quite similar, with a <sgmltag
+class="element">glossterm</sgmltag> taking the place of the <sgmltag
+class="element">term</sgmltag>, and a <sgmltag
+class="element">glossdef</sgmltag> taking the place of the <sgmltag
+class="element">listitem</sgmltag>. Since variable lists get heavy use
+in &tde; Documents, it shouldn't take you long to pick up how to do a
+glossary.
+</para>
+
+<example>
+<title>How to markup a glossary</title>
+
+<para>
+Say you have in the text of the document the following sentence:
+</para>
+
+<blockquote>
+<para>
+KWord is a graphical, wysiwyg word processor, and is part of KOffice. 
+</para>
+</blockquote>
+
+<para>
+You want to have the words KWord and koffice in the index, and KWord,
+wysiwyg, <quote>word processor</quote> and KOffice explained in a
+glossary.
+</para>
+
+<para>
+Many of these terms also need to be marked up with other tags, such as
+application, and acronym.
+</para>
+
+<para>The eventual markup would look like this:</para>
+
+<screen>
+<markup>
+&lt;para&gt;&lt;glossterm linkend="gloss-kword"&gt;KWord&lt;/glossterm&gt;
+&lt;indexterm&gt;&lt;primary&gt;KWord&lt;/primary&gt;&lt;/indexterm&gt; is a
+graphical &lt;glossterm linkend
+="gloss-wysiwyg"&gt;&lt;acronym&gt;WYSIWYG&lt;/acronym&gt;&lt;/glossterm&gt;
+&lt;glossterm linkend="gloss-word-processor"&gt;word
+processor&lt;/glossterm&gt;, and is part of &lt;glossterm
+linkend="gloss-koffice"&gt;KOffice&lt;/glossterm&gt;.
+&lt;indexterm&gt;&lt;primary&gt;KOffice&lt;/primary&gt;&lt;/indexterm&gt;&lt;/para&gt;
+</markup>
+</screen>
+
+<para>
+The next part is shown here as a <sgmltag
+class="starttag">glosslist</sgmltag>, and if there were really only this
+many entries in it, that could be entirely appropriate. In reality, if
+you are going to make a glossary, it would have many more entries and so
+would warrant it's own <sgmltag class="starttag">glossary</sgmltag>
+section. The syntax inside <sgmltag class="starttag">glossary</sgmltag>
+and <sgmltag class="starttag">glosslist</sgmltag> are otherwise the
+same.
+</para>
+
+<screen>
+<markup>
+&lt;glosslist&gt;
+&lt;glossentry id="gloss-kword"&gt;
+&lt;glossterm&gt;KWord&lt;/glossterm&gt;
+&lt;glossdef&gt;&lt;para&gt;The name of the TDE word
+processor&lt;/para&gt;&lt;/glossdef&gt;
+&lt;/glossentry&gt;
+
+&lt;glossentry id="gloss-koffice"&gt;
+&lt;glossterm&gt;KOffice&lt;/glossterm&gt;
+&lt;glossdef&gt;&lt;para&gt;A collection of office productivity tools, designed
+by and for &lt;acronym&gt;TDE&lt;/acronym&gt;, including presentation software,
+a word processor, a spreadsheet, a &lt;acronym&gt;PIM&lt;/acronym&gt;, and a
+vector illustration application.&lt;/para&gt;&lt;/glossdef&gt;
+&lt;/glossentry&gt;
+
+&lt;glossentry id="gloss-word-processor"&gt;
+&lt;glossterm&gt;word processor&lt;/glossterm&gt;
+&lt;glossdef&gt;&lt;para&gt;An application for handling text, typically more
+concerned with formatting visually than a plain text
+editor.&lt;/para&gt;&lt;/glossdef&gt;
+&lt;/glossentry&gt;
+
+&lt;glossentry id="gloss-wysiwyg"&gt;
+&lt;glossterm&gt;WYSIWYG&lt;/glossterm&gt;
+&lt;glossdef&gt;&lt;para&gt;Stands for &lt;quote&gt;What You See Is What You
+Get&lt;/quote&gt;, indicating that you can visually format the presentation of
+your data onscreen, and when you print the document, it will look exactly as you
+see on the screen.&lt;/para&gt;&lt;/glossdef&gt;
+&lt;/glossentry&gt;
+&lt;/glosslist&gt;
+</markup>
+</screen>
+
+<para>
+And the result of all this would be as follows:
+</para>
+
+<para>
+<glossterm linkend="gloss-kword">KWord</glossterm>
+<indexterm><primary>KWord</primary></indexterm> is a graphical
+<glossterm linkend
+="gloss-wysiwyg"><acronym>WYSIWYG</acronym></glossterm> <glossterm
+linkend="gloss-word-processor">word processor</glossterm>, and is part
+of <glossterm
+linkend="gloss-koffice">KOffice</glossterm>.<indexterm><primary>KOffice</primary></indexterm>.
+</para>
+
+<glosslist>
+<glossentry id="gloss-kword">
+<glossterm>KWord</glossterm>
+<glossdef><para>The name of the TDE word processor</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-koffice">
+<glossterm>KOffice</glossterm>
+<glossdef><para>A collection of office productivity tools, designed by and for
+<acronym>TDE</acronym>, including presentation software, a word processor, a
+spreadsheet, a <acronym>PIM</acronym>, and a vector illustration
+application.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-word-processor">
+<glossterm>word processor</glossterm>
+<glossdef><para>An application for handling text, typically more concerned with
+formatting visually than a plain text editor.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-wysiwyg">
+<glossterm>WYSIWYG</glossterm>
+<glossdef><para>Stands for <quote>What You See Is What You Get</quote>,
+indicating that you can visually format the presentation of your data onscreen,
+and when you print the document, it will look exactly as you see on the
+screen.</para></glossdef></glossentry>
+</glosslist>
+
+</example>
+
+</sect1>
+
+<sect1 id="indexes">
+<title>Making an Index</title>
+
+<para>
+For &tde; Documentation, indexes will in the future be generated
+automatically, so many of these elements are not to be used directly
+when authoring. At this stage, indexes are not generated, but if you
+want to you can mark up words that should be indexed with the <sgmltag
+class="starttag">indexterm</sgmltag> element, to save work for later.
+</para>
+
+<variablelist>
+<varlistentry>
+<term id="indexterm"><sgmltag
+class="starttag">indexterm</sgmltag></term>
+<listitem>
+<anchor id="primary"/>
+<para>
+Use this to note places in the main text of the document that should
+have an entry in the index. Don't over use it - not every single
+occurrence of a word needs to be noted in the index, but every
+occurrence where that term is significant should be.
+</para> 
+
+<para>
+<sgmltag class="element">indexterm</sgmltag> should contain a <sgmltag
+class="starttag">primary</sgmltag>, which contains the text that the
+entry will appear under in the index.
+</para>
+
+<para>
+Place the <sgmltag class="element">indexterm</sgmltag> directly before
+the word you want to index, and place the word itself inside the primary
+element. If the word should also be listed under a secondary heading,
+place that term inside a secondary element.
+</para> 
+
+<example>
+<title>Index</title>
+
+<para>Say the document contains the following sentence:</para>
+
+<blockquote><para>KWord is a graphical, wysiwyg word processor, and is part of
+KOffice. </para></blockquote>
+
+<para>You want KWord to have an index entry of it's own, and to also be noted
+under KOffice in the index.</para>
+
+<screen>
+<markup>
+&lt;para&gt;&lt;application&gt;KWord&lt;/application&gt;
+&lt;indexterm&gt;&lt;primary&gt;KWord&lt;/primary&gt;&lt;secondary&gt;KOffice&lt;/secondary&gt;&lt;/indexterm&gt;
+is a graphical, &lt;acronym&gt;WYSIWYG&lt;/acronym&gt; word processor, and is part of
+KOffice.&lt;/para&gt;
+</markup>
+</screen>
+
+<para>The fact that an index entry exists is not normally indicated by a change
+in appearance.</para>
+</example>
+
+<para>If you think it should also be added under a third heading in the index,
+you can use tertiary to indicate this. Most terms you would find in &tde;
+Documentation will only need a primary index heading, so use the others
+sparingly, if at all.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term id="tertiary"><sgmltag class="starttag">tertiary</sgmltag></term>
+<listitem><para>tertiary</para></listitem></varlistentry>
+
+<varlistentry><term id="seealso"><sgmltag class="starttag">seealso</sgmltag></term>
+<listitem><para>seealso</para></listitem></varlistentry>
+
+</variablelist>
+
+<para>
+The following elements are used to create the actual index, but they are
+automatically generated, if required. You should not use them when
+authoring documents.
+</para>
+
+<itemizedlist>
+<listitem id="index">
+<para>
+<sgmltag class="starttag">index</sgmltag>
+</para>
+</listitem>
+<listitem id="indexdiv">
+<para>
+<sgmltag class="starttag">indexdiv</sgmltag>
+</para>
+</listitem>
+<listitem id="indexentry">
+<para>
+<sgmltag class="starttag">indexentry</sgmltag>
+</para>
+</listitem>
+<listitem id="primaryie">
+<para>
+<sgmltag class="starttag">primaryie</sgmltag>
+</para>
+</listitem>
+<listitem id="secondaryie">
+<para>
+<sgmltag class="starttag">secondaryie</sgmltag>
+</para>
+</listitem>
+<listitem id="see">
+<para>
+<sgmltag class="starttag">see</sgmltag>
+</para>
+</listitem>
+<listitem id="seealsoie">
+<para>
+<sgmltag class="starttag">seealsoie</sgmltag>
+</para>
+</listitem>
+<listitem id="seeie">
+<para>
+<sgmltag class="starttag">seeie</sgmltag>
+</para>
+</listitem>
+<listitem id="tertiaryie">
+<para>
+<sgmltag class="starttag">tertiaryie</sgmltag>
+</para>
+</listitem>
+</itemizedlist>
+</sect1>
+
+<sect1 id="other-reference-sections">
+<title>Other Reference Sections</title>
+
+<variablelist>
+
+<varlistentry>
+<term id="firstterm"><sgmltag
+class="starttag">firstterm</sgmltag></term>
+<listitem>
+<para>
+Mark up the first occurence of a technically significant term with this
+element. If you are creating a glossary or an index, the first occurence
+of a term will probably also warrant being an entry in one or both.
+</para>
+</listitem> 
+</varlistentry>
+
+<varlistentry>
+<term id="refsynopsisdivinfo"><sgmltag
+class="starttag">refsynopsisdivinfo</sgmltag></term>
+<listitem>
+<para>
+refsynopsisdivinfo
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refnamediv"><sgmltag
+class="starttag">refnamediv</sgmltag></term>
+<listitem>
+<para>refnamediv
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refclass"><sgmltag 
+class="starttag">refclass</sgmltag></term>
+<listitem>
+<para>
+refclass
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refmeta"><sgmltag 
+class="starttag">refmeta</sgmltag></term>
+<listitem>
+<para>
+refmeta
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refsect1"><sgmltag 
+class="starttag">refsect1</sgmltag>,<sgmltag 
+class="starttag">refsect2</sgmltag>
+and <sgmltag class="starttag">refsect3</sgmltag></term>
+<listitem>
+<anchor id="refsect2"/><anchor id="refsect3"/>
+<para>
+refsect1, refsect2 and refsect3
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refmiscinfo"><sgmltag 
+class="starttag">refmiscinfo</sgmltag></term>
+<listitem>
+<para>
+refmiscinfo
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refsect1info"><sgmltag
+class="starttag">refsect1info</sgmltag>,<sgmltag
+class="starttag">refsect2info</sgmltag> and <sgmltag
+class="starttag">refsect3info</sgmltag></term>
+<listitem><anchor id="refsect2info"/><anchor id="refsect3info"/>
+<para>
+refsect1info, refsect2info and refsect3info
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refdescriptor"><sgmltag 
+class="starttag">refdescriptor</sgmltag></term>
+<listitem>
+<para>
+refdescriptor
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="setindex"><sgmltag class="starttag">setindex</sgmltag></term>
+<listitem>
+<para>
+Not Used in &tde; Documentation
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refpurpose"><sgmltag
+class="starttag">refpurpose</sgmltag></term>
+<listitem>
+<para>
+refpurpose
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="reference"><sgmltag class="starttag">reference</sgmltag></term>
+<listitem>
+<para>
+reference
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refentrytitle"><sgmltag
+class="starttag">refentrytitle</sgmltag></term>
+<listitem>
+<para>
+refentrytitle
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refname"><sgmltag class="starttag">refname</sgmltag></term>
+<listitem>
+<para>
+refname
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refentry"><sgmltag class="starttag">refentry</sgmltag></term>
+<listitem>
+<para>
+refentry
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term id="refsynopsisdiv"><sgmltag
+class="starttag">refsynopsisdiv</sgmltag></term>
+<listitem>
+<para>
+refsynpsisdiv
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+</chapter>
+
+<chapter id="tags-we-dont-use">
+<title>Tags we do not use</title>
+
+<para>
+These are tags that are available for DocBook &XML;, but we have decided
+they will not (at this time) be used for &tde; Documentation. They are
+included here for completeness, and so nobody can say <quote>I didn't
+know I wasn't supposed to use that!</quote>
+</para> 
+
+<para>
+They fall into two categories: Tags we have definitely decided to not
+use, in which case we have made a decision to use another tag instead,
+and tags that are just irrelevant to the documentation we are doing,
+which you hopefully will never want. Should we write new documentation
+that can sensibly be marked up with any of these elements, this list
+will be revised.
+</para>
+
+<para>
+If you think you have a use for one of these elements, please, check
+with the DocBook team first, and be prepared to justify your case. 
+</para>
+
+<itemizedlist>
+<listitem id="ackno"><para><sgmltag class="starttag">ackno</sgmltag></para></listitem>
+<listitem id="alt"><para><sgmltag class="starttag">alt</sgmltag></para></listitem>
+<listitem id="appendixinfo"><para><sgmltag class="starttag">appendixinfo</sgmltag></para></listitem>
+<listitem id="artheader"><para><sgmltag class="starttag">artheader</sgmltag></para></listitem>
+<listitem id="article"><para><sgmltag class="starttag">article</sgmltag></para></listitem>
+<listitem id="articleinfo"><para><sgmltag class="starttag">articleinfo</sgmltag></para></listitem>
+<listitem id="artpagenums"><para><sgmltag class="starttag">artpagenums</sgmltag></para></listitem>
+<listitem id="audiodata"><para><sgmltag class="starttag">audiodata</sgmltag></para></listitem>
+<listitem id="audioobject"><para><sgmltag class="starttag">audioobject</sgmltag></para></listitem>
+<listitem id="authorblurb"><para><sgmltag class="starttag">authorblurb</sgmltag></para></listitem>
+<listitem id="authorinitials"><para><sgmltag class="starttag">authorinitials</sgmltag></para></listitem>
+<listitem id="beginpage"><para><sgmltag class="starttag">beginpage</sgmltag></para></listitem>
+<listitem id="bibliodiv"><para><sgmltag class="starttag">bibliodiv</sgmltag></para></listitem>
+<listitem id="biblioentry"><para><sgmltag class="starttag">biblioentry</sgmltag></para></listitem>
+<listitem id="bibliography"><para><sgmltag class="starttag">bibliography</sgmltag></para></listitem>
+<listitem id="bibliographyinfo"><para><sgmltag class="starttag">bibliographyinfo</sgmltag></para></listitem>
+<listitem id="bibliomisc"><para><sgmltag class="starttag">bibliomisc</sgmltag></para></listitem>
+<listitem id="bibliomixed"><para><sgmltag class="starttag">bibliomixed</sgmltag></para></listitem>
+<listitem id="bibliomset"><para><sgmltag class="starttag">bibliomset</sgmltag></para></listitem>
+<listitem id="biblioset"><para><sgmltag class="starttag">biblioset</sgmltag></para></listitem>
+<listitem id="bookbiblio"><para><sgmltag class="starttag">bookbiblio</sgmltag></para></listitem>
+<listitem id="bridgehead"><para><sgmltag class="starttag">bridgehead</sgmltag></para></listitem>
+<listitem id="chapterinfo"><para><sgmltag class="starttag">chapterinfo</sgmltag></para></listitem>
+<listitem id="citation"><para><sgmltag class="starttag">citation</sgmltag></para></listitem>
+<listitem id="citerefentry"><para><sgmltag class="starttag">citerefentry</sgmltag></para></listitem>
+<listitem id="citetitle"><para><sgmltag class="starttag">citetitle</sgmltag></para></listitem>
+<listitem id="city"><para><sgmltag class="starttag">city</sgmltag></para></listitem>
+<listitem id="collab"><para><sgmltag class="starttag">collab</sgmltag></para></listitem>
+<listitem id="collabname"><para><sgmltag class="starttag">collabname</sgmltag></para></listitem>
+<listitem id="colophon"><para><sgmltag class="starttag">colophon</sgmltag></para></listitem>
+<listitem id="colspec"><para><sgmltag class="starttag">colspect</sgmltag></para></listitem>
+<listitem id="comment"><para><sgmltag class="starttag">comment</sgmltag></para></listitem>
+<listitem id="confdates"><para><sgmltag class="starttag">confdates</sgmltag></para></listitem>
+<listitem id="confgroup"><para><sgmltag class="starttag">confgroup</sgmltag></para></listitem>
+<listitem id="confnum"><para><sgmltag class="starttag">confnum</sgmltag></para></listitem>
+<listitem id="confsponsor"><para><sgmltag class="starttag">confsponsor</sgmltag></para></listitem>
+<listitem id="conftitle"><para><sgmltag class="starttag">conftitle</sgmltag></para></listitem>
+<listitem id="contractnum"><para><sgmltag class="starttag">contractnum</sgmltag></para></listitem>
+<listitem id="contractsponsor"><para><sgmltag class="starttag">contractsponsor</sgmltag></para></listitem>
+<listitem id="corpname"><para><sgmltag class="starttag">corpname</sgmltag></para></listitem>
+<listitem id="country"><para><sgmltag class="starttag">country</sgmltag></para></listitem>
+<listitem id="database"><para><sgmltag class="starttag">database</sgmltag></para></listitem>
+<listitem id="dedication"><para><sgmltag class="starttag">dedication</sgmltag></para></listitem>
+<listitem id="docinfo"><para><sgmltag class="starttag">docinfo</sgmltag></para></listitem>
+<listitem id="edition"><para><sgmltag class="starttag">edition</sgmltag></para></listitem>
+<listitem id="editor"><para><sgmltag class="starttag">editor</sgmltag></para></listitem>
+<listitem id="entrytbl"><para><sgmltag class="starttag">entrytbl</sgmltag></para></listitem>
+<listitem id="fax"><para><sgmltag class="starttag">fax</sgmltag></para></listitem>
+<listitem id="figure"><para><sgmltag class="starttag">figure</sgmltag></para></listitem>
+<listitem id="formalpara"><para><sgmltag class="starttag">formalpara</sgmltag></para></listitem>
+<listitem id="glossaryinfo"><para><sgmltag class="starttag">sgmltag</sgmltag></para></listitem>
+<listitem id="graphic"><para><sgmltag class="starttag">graphic</sgmltag></para></listitem>
+<listitem id="highlights"><para><sgmltag class="starttag">highlights</sgmltag></para></listitem>
+<listitem id="honorific"><para><sgmltag class="starttag">honorific</sgmltag></para></listitem>
+<listitem id="indexinfo"><para><sgmltag class="starttag">indexinfo</sgmltag></para></listitem>
+<listitem id="informalequation"><para><sgmltag class="starttag">informalequation</sgmltag></para></listitem>
+<listitem id="informalfigure"><para><sgmltag class="starttag">informalfigure</sgmltag></para></listitem>
+<listitem id="inlineequation"><para><sgmltag class="starttag">inlineequation</sgmltag></para></listitem>
+<listitem id="inlinegraphic"><para><sgmltag class="starttag">inlinegraphic</sgmltag></para></listitem>
+<listitem id="interfacedefinition"><para><sgmltag class="starttag">interfacedefinition</sgmltag></para></listitem>
+<listitem id="interfacename"><para><sgmltag class="starttag">interfacename</sgmltag></para></listitem>
+<listitem id="invpartnumber"><para><sgmltag class="starttag">invpartnumber</sgmltag></para></listitem>
+<listitem id="isbn"><para><sgmltag class="starttag">isbn</sgmltag></para></listitem>
+<listitem id="issn"><para><sgmltag class="starttag">issn</sgmltag></para></listitem>
+<listitem id="issuenum"><para><sgmltag class="starttag">issuenum</sgmltag></para></listitem>
+<listitem id="itermset"><para><sgmltag class="starttag">itermset</sgmltag></para></listitem>
+<listitem id="jobtitle"><para><sgmltag class="starttag">jobtitle</sgmltag></para></listitem>
+<listitem id="lineage"><para><sgmltag class="starttag">lineage</sgmltag></para></listitem>
+<listitem id="lot"><para><sgmltag class="starttag">lot</sgmltag></para></listitem>
+<listitem id="lotentry"><para><sgmltag class="starttag">lotentry</sgmltag></para></listitem>
+<listitem id="manvolnum"><para><sgmltag class="starttag">manvolnum</sgmltag></para></listitem>
+<listitem id="medialabel"><para><sgmltag class="starttag">medialabel</sgmltag></para></listitem>
+<listitem id="modespec"><para><sgmltag class="starttag">modespec</sgmltag></para></listitem>
+<listitem id="msg"><para><sgmltag class="starttag">msg</sgmltag></para></listitem>
+<listitem id="msgaud"><para><sgmltag class="starttag">msgaud</sgmltag></para></listitem>
+<listitem id="msgentry"><para><sgmltag class="starttag">msgentry</sgmltag></para></listitem>
+<listitem id="msgexplan"><para><sgmltag class="starttag">msgexplan</sgmltag></para></listitem>
+<listitem id="msginfo"><para><sgmltag class="starttag">msginfo</sgmltag></para></listitem>
+<listitem id="msglevel"><para><sgmltag class="starttag">msglevel</sgmltag></para></listitem>
+<listitem id="msgmain"><para><sgmltag class="starttag">msgmain</sgmltag></para></listitem>
+<listitem id="msgorig"><para><sgmltag class="starttag">msgorig</sgmltag></para></listitem>
+<listitem id="msgrel"><para><sgmltag class="starttag">msgrel</sgmltag></para></listitem>
+<listitem id="msgset"><para><sgmltag class="starttag">msgset</sgmltag></para></listitem>
+<listitem id="msgsub"><para><sgmltag class="starttag">msgsub</sgmltag></para></listitem>
+<listitem id="objectinfo"><para><sgmltag class="starttag">objectinfo</sgmltag></para></listitem>
+<listitem id="olink"><para><sgmltag class="starttag">olink</sgmltag></para></listitem>
+<listitem id="orgdiv"><para><sgmltag class="starttag">orgdiv</sgmltag></para></listitem>
+<listitem id="orgname"><para><sgmltag class="starttag">orgname</sgmltag></para></listitem>
+<listitem id="otheraddr"><para><sgmltag class="starttag">otheraddr</sgmltag></para></listitem>
+<listitem id="pagenums"><para><sgmltag class="starttag">pagenums</sgmltag></para></listitem>
+<listitem id="part"><para><sgmltag class="starttag">part</sgmltag></para></listitem>
+<listitem id="partintro"><para><sgmltag class="starttag">partintro</sgmltag></para></listitem>
+<listitem id="phone"><para><sgmltag class="starttag">phone</sgmltag></para></listitem>
+<listitem id="pob"><para><sgmltag class="starttag">pob</sgmltag></para></listitem>
+<listitem id="postcode"><para><sgmltag class="starttag">postcode</sgmltag></para></listitem>
+<listitem id="preface"><para><sgmltag class="starttag">preface</sgmltag></para></listitem>
+<listitem id="prefaceinfo"><para><sgmltag class="starttag">prefaceinfo</sgmltag></para></listitem>
+<listitem id="printhistory"><para><sgmltag class="starttag">printhistory</sgmltag></para></listitem>
+<listitem id="productname"><para><sgmltag class="starttag">productname</sgmltag></para></listitem>
+<listitem id="productnumber"><para><sgmltag class="starttag">productnumber</sgmltag></para></listitem>
+<listitem id="property"><para><sgmltag class="starttag">property</sgmltag></para></listitem>
+<listitem id="pubdate"><para><sgmltag class="starttag">pubdate</sgmltag></para></listitem>
+<listitem id="publisher"><para><sgmltag class="starttag">publisher</sgmltag></para></listitem>
+<listitem id="publishername"><para><sgmltag class="starttag">publishername</sgmltag></para></listitem>
+<listitem id="pubsnumber"><para><sgmltag class="starttag">pubsnumber</sgmltag></para></listitem>
+<listitem id="qandadiv"><para><sgmltag class="starttag">qandadiv</sgmltag></para></listitem>
+<listitem id="refentryinfo"><para><sgmltag class="starttag">refentryinfo</sgmltag></para></listitem>
+<listitem id="referenceinfo"><para><sgmltag class="starttag">referenceinfo</sgmltag></para></listitem>
+<listitem id="remark"><para><sgmltag class="starttag">remark</sgmltag></para></listitem>
+<listitem id="revdescription"><para><sgmltag class="starttag">revdescription</sgmltag></para></listitem>
+<listitem id="revhistory"><para><sgmltag class="starttag">revhistory</sgmltag></para></listitem>
+<listitem id="revision"><para><sgmltag class="starttag">revision</sgmltag></para></listitem>
+<listitem id="revnumber"><para><sgmltag class="starttag">revnumber</sgmltag></para></listitem>
+<listitem id="revremark"><para><sgmltag class="starttag">revremark</sgmltag></para></listitem>
+<listitem id="secondary"><para><sgmltag class="starttag">secondary</sgmltag></para></listitem>
+<listitem id="section"><para><sgmltag class="starttag">section</sgmltag></para></listitem>
+<listitem id="sectioninfo"><para><sgmltag class="starttag">sectioninfo</sgmltag></para></listitem>
+<listitem id="seriesinfo"><para><sgmltag class="starttag">seriesinfo</sgmltag></para></listitem>
+<listitem id="seriesvolnums"><para><sgmltag class="starttag">seriesvolnums</sgmltag></para></listitem>
+<listitem id="set"><para><sgmltag class="starttag">set</sgmltag></para></listitem>
+<listitem id="setindexinfo"><para><sgmltag class="starttag">setindexinfo</sgmltag></para></listitem>
+<listitem id="setinfo"><para><sgmltag class="starttag">setinfo</sgmltag></para></listitem>
+<listitem id="shortaffil"><para><sgmltag class="starttag">shortaffil</sgmltag></para></listitem>
+<listitem id="sidebar"><para><sgmltag class="starttag">sidebar</sgmltag></para></listitem>
+<listitem id="sidebarinfo"><para><sgmltag class="starttag">sidebarinfo</sgmltag></para></listitem>
+<listitem id="simpara"><para><sgmltag class="starttag">simpara</sgmltag></para></listitem>
+<listitem id="simplemsgentry"><para><sgmltag class="starttag">simplemsgentry</sgmltag></para></listitem>
+<listitem id="simplesect"><para><sgmltag class="starttag">simplesect</sgmltag></para></listitem>
+<listitem id="spanspec"><para><sgmltag class="starttag">spanspec</sgmltag></para></listitem>
+<listitem id="state"><para><sgmltag class="starttag">state</sgmltag></para></listitem>
+<listitem id="street"><para><sgmltag class="starttag">street</sgmltag></para></listitem>
+<listitem id="subject"><para><sgmltag class="starttag">subject</sgmltag></para></listitem>
+<listitem id="subjectset"><para><sgmltag class="starttag">subjectset</sgmltag></para></listitem>
+<listitem id="subjectterm"><para><sgmltag class="starttag">subjectterm</sgmltag></para></listitem>
+<listitem id="subtitle"><para><sgmltag class="starttag">subtitle</sgmltag></para></listitem>
+<listitem id="systemitem"><para><sgmltag class="starttag">systemitem</sgmltag></para></listitem>
+<listitem id="titleabbrev"><para><sgmltag class="starttag">titleabbrev</sgmltag></para></listitem>
+<listitem id="toc"><para><sgmltag class="starttag">toc</sgmltag></para></listitem>
+<listitem id="tocback"><para><sgmltag class="starttag">tocback</sgmltag></para></listitem>
+<listitem id="tocchap"><para><sgmltag class="starttag">tocchap</sgmltag></para></listitem>
+<listitem id="tocentry"><para><sgmltag class="starttag">tocentry</sgmltag></para></listitem>
+<listitem id="tocfront"><para><sgmltag class="starttag">tocfront</sgmltag></para></listitem>
+<listitem id="toclevel1"><para><sgmltag class="starttag">toclevel1</sgmltag></para></listitem>
+<listitem id="toclevel2"><para><sgmltag class="starttag">toclevel2</sgmltag></para></listitem>
+<listitem id="toclevel3"><para><sgmltag class="starttag">toclevel3</sgmltag></para></listitem>
+<listitem id="toclevel4"><para><sgmltag class="starttag">toclevel4</sgmltag></para></listitem>
+<listitem id="toclevel5"><para><sgmltag class="starttag">toclevel5</sgmltag></para></listitem>
+<listitem id="tocpart"><para><sgmltag class="starttag">tocpart</sgmltag></para></listitem>
+<listitem id="videodata"><para><sgmltag class="starttag">videodata</sgmltag></para></listitem>
+<listitem id="videoobject"><para><sgmltag class="starttag">videoobject</sgmltag></para></listitem>
+<listitem id="volumenum"><para><sgmltag class="starttag">volumenum</sgmltag></para></listitem>
+<listitem id="wordasword"><para><sgmltag class="starttag">wordasword</sgmltag></para></listitem>
+</itemizedlist>
+</chapter>
+
+<chapter id="alphabetical-list">
+<title>Alphabetical List of all elements</title>
+
+<para>
+This is a list of all the markup elements contained in DocBook XML
+4.1.2. Choose the element you are interested in to go directly to the
+section of this document which describes it.
+</para> 
+
+<note>
+<para>
+We don't use all these elements in &tde; Documentation - they are here
+for completeness. Elements we don't use are listed in <xref
+linkend="tags-we-dont-use"/>.
+</para>
+</note>
+
+<itemizedlist>
+<listitem><para><link linkend="authorinitials"><sgmltag
+class="starttag">authorinitials</sgmltag></link></para></listitem>
+
+<listitem><para><link linkend="beginpage"><sgmltag class="starttag">beginpage</sgmltag></link></para></listitem>
+<listitem><para><link linkend="bibliodiv"><sgmltag class="starttag">bibliodiv</sgmltag></link></para></listitem>
+<listitem><para><link linkend="biblioentry"><sgmltag class="starttag">biblioentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="bibliographyinfo"><sgmltag class="starttag">bibliographyinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="bibliomset"><sgmltag class="starttag">bibliomset</sgmltag></link></para></listitem>
+<listitem><para><link linkend="bibliomisc"><sgmltag class="starttag">bibliomisc</sgmltag></link></para></listitem>
+<listitem><para><link linkend="bibliomixed"><sgmltag class="starttag">bibliomixed</sgmltag></link></para></listitem>
+<listitem><para><link linkend="biblioset"><sgmltag class="starttag">biblioset</sgmltag></link></para></listitem>
+<listitem><para><link linkend="bibliography"><sgmltag class="starttag">bibliography</sgmltag></link></para></listitem>
+<listitem><para><link linkend="blockquote"><sgmltag class="starttag">blockquote</sgmltag></link></para></listitem>
+<listitem><para><link linkend="book"><sgmltag class="starttag">book</sgmltag></link></para></listitem>
+<listitem><para><link linkend="bookbiblio"><sgmltag class="starttag">bookbiblio</sgmltag></link></para></listitem>
+<listitem><para><link linkend="bookinfo"><sgmltag class="starttag">bookinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="bridgehead"><sgmltag class="starttag">bridgehead</sgmltag></link></para></listitem>
+<listitem><para><link linkend="co"><sgmltag class="starttag">co</sgmltag></link></para></listitem>
+<listitem><para><link linkend="callout"><sgmltag class="starttag">callout</sgmltag></link></para></listitem>
+<listitem><para><link linkend="calloutlist"><sgmltag class="starttag">calloutlist</sgmltag></link></para></listitem>
+<listitem><para><link linkend="caption"><sgmltag class="starttag">caption</sgmltag></link></para></listitem>
+<listitem><para><link linkend="caution"><sgmltag class="starttag">caution</sgmltag></link></para></listitem>
+<listitem><para><link linkend="chapter"><sgmltag class="starttag">chapter</sgmltag></link></para></listitem>
+<listitem><para><link linkend="chapterinfo"><sgmltag class="starttag">chapterinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="citation"><sgmltag class="starttag">citation</sgmltag></link></para></listitem>
+<listitem><para><link linkend="citerefentry"><sgmltag class="starttag">citerefentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="citetitle"><sgmltag class="starttag">citetitle</sgmltag></link></para></listitem>
+<listitem><para><link linkend="city"><sgmltag class="starttag">city</sgmltag></link></para></listitem>
+<listitem><para><link linkend="classname"><sgmltag class="starttag">classname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="classsynopsis"><sgmltag class="starttag">classsynopsis</sgmltag></link></para></listitem>
+<listitem><para><link linkend="classsynopsisinfo"><sgmltag class="starttag">classsynopsisinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="cmdsynopsis"><sgmltag class="starttag">cmdsynopsis</sgmltag></link></para></listitem>
+<listitem><para><link linkend="colspec"><sgmltag class="starttag">colspec</sgmltag></link></para></listitem>
+<listitem><para><link linkend="collab"><sgmltag class="starttag">collab</sgmltag></link></para></listitem>
+<listitem><para><link linkend="collabname"><sgmltag class="starttag">collabname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="colophon"><sgmltag class="starttag">colophon</sgmltag></link></para></listitem>
+<listitem><para><link linkend="command"><sgmltag class="starttag">command</sgmltag></link></para></listitem>
+<listitem><para><link linkend="comment"><sgmltag class="starttag">comment</sgmltag></link></para></listitem>
+<listitem><para><link linkend="computeroutput"><sgmltag class="starttag">computeroutput</sgmltag></link></para></listitem>
+<listitem><para><link linkend="confdates"><sgmltag class="starttag">confdates</sgmltag></link></para></listitem>
+<listitem><para><link linkend="confgroup"><sgmltag class="starttag">confgroup</sgmltag></link></para></listitem>
+<listitem><para><link linkend="confnum"><sgmltag class="starttag">confnum</sgmltag></link></para></listitem>
+<listitem><para><link linkend="confsponsor"><sgmltag class="starttag">confsponsor</sgmltag></link></para></listitem>
+<listitem><para><link linkend="conftitle"><sgmltag class="starttag">conftitle</sgmltag></link></para></listitem>
+<listitem><para><link linkend="constant"><sgmltag class="starttag">constant</sgmltag></link></para></listitem>
+<listitem><para><link linkend="constructorsynopsis"><sgmltag class="starttag">constructorsynopsis</sgmltag></link></para></listitem>
+<listitem><para><link linkend="contractnum"><sgmltag class="starttag">contractnum</sgmltag></link></para></listitem>
+<listitem><para><link linkend="contractsponsor"><sgmltag class="starttag">contractspnosor</sgmltag></link></para></listitem>
+<listitem><para><link linkend="contrib"><sgmltag class="starttag">contrib</sgmltag></link></para></listitem>
+<listitem><para><link linkend="copyright"><sgmltag class="starttag">copyright</sgmltag></link></para></listitem>
+<listitem><para><link linkend="corpauthor"><sgmltag class="starttag">corpauthor</sgmltag></link></para></listitem>
+<listitem><para><link linkend="corpname"><sgmltag class="starttag">corpname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="country"><sgmltag class="starttag">country</sgmltag></link></para></listitem>
+<listitem><para><link linkend="database"><sgmltag class="starttag">database</sgmltag></link></para></listitem>
+<listitem><para><link linkend="date"><sgmltag class="starttag">date</sgmltag></link></para></listitem>
+<listitem><para><link linkend="dedication"><sgmltag class="starttag">dedication</sgmltag></link></para></listitem>
+<listitem><para><link linkend="destructorsynopsis"><sgmltag class="starttag">destructorsynopsis</sgmltag></link></para></listitem>
+<listitem><para><link linkend="docinfo"><sgmltag class="starttag">docinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="edition"><sgmltag class="starttag">edition</sgmltag></link></para></listitem>
+<listitem><para><link linkend="editor"><sgmltag class="starttag">editor</sgmltag></link></para></listitem>
+<listitem><para><link linkend="email"><sgmltag class="starttag">email</sgmltag></link></para></listitem>
+<listitem><para><link linkend="emphasis"><sgmltag class="starttag">emphasis</sgmltag></link></para></listitem>
+<listitem><para><link linkend="envar"><sgmltag class="starttag">envar</sgmltag></link></para></listitem>
+<listitem><para><link linkend="entry"><sgmltag class="starttag">entry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="entrytbl"><sgmltag class="starttag">entrytbl</sgmltag></link></para></listitem>
+<listitem><para><link linkend="epigraph"><sgmltag class="starttag">epigraph</sgmltag></link></para></listitem>
+<listitem><para><link linkend="equation"><sgmltag class="starttag">equation</sgmltag></link></para></listitem>
+<listitem><para><link linkend="errorcode"><sgmltag class="starttag">errorcode</sgmltag></link></para></listitem>
+<listitem><para><link linkend="errorname"><sgmltag class="starttag">errorname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="errortype"><sgmltag class="starttag">errortype</sgmltag></link></para></listitem>
+<listitem><para><link linkend="example"><sgmltag class="starttag">example</sgmltag></link></para></listitem>
+<listitem><para><link linkend="exceptionname"><sgmltag class="starttag">exceptionname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="fax"><sgmltag class="starttag">fax</sgmltag></link></para></listitem>
+<listitem><para><link linkend="figure"><sgmltag class="starttag">figure</sgmltag></link></para></listitem>
+<listitem><para><link linkend="fieldsynopsis"><sgmltag class="starttag">fieldsynopsis</sgmltag></link></para></listitem>
+<listitem><para><link linkend="filename"><sgmltag class="starttag">filename</sgmltag></link></para></listitem>
+<listitem><para><link linkend="firstterm"><sgmltag class="starttag">firstterm</sgmltag></link></para></listitem>
+<listitem><para><link linkend="footnote"><sgmltag class="starttag">footnote</sgmltag></link></para></listitem>
+<listitem><para><link linkend="footnoteref"><sgmltag class="starttag">footnoteref</sgmltag></link></para></listitem>
+<listitem><para><link linkend="foreignphrase"><sgmltag class="starttag">foreignphrase</sgmltag></link></para></listitem>
+<listitem><para><link linkend="formalpara"><sgmltag class="starttag">formalpara</sgmltag></link></para></listitem>
+<listitem><para><link linkend="funcdef"><sgmltag class="starttag">funcdef</sgmltag></link></para></listitem>
+<listitem><para><link linkend="funcparams"><sgmltag class="starttag">funcparams</sgmltag></link></para></listitem>
+<listitem><para><link linkend="funcprototype"><sgmltag class="starttag">funcprototype</sgmltag></link></para></listitem>
+<listitem><para><link linkend="funcsynopsis"><sgmltag class="starttag">funcsynopsis</sgmltag></link></para></listitem>
+<listitem><para><link linkend="funcsynopsisinfo"><sgmltag class="starttag">funcsynopsisinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="function"><sgmltag class="starttag">function</sgmltag></link></para></listitem>
+<listitem><para><link linkend="guibutton"><sgmltag class="starttag">guibutton</sgmltag></link></para></listitem>
+<listitem><para><link linkend="guiicon"><sgmltag class="starttag">guiicon</sgmltag></link></para></listitem>
+<listitem><para><link linkend="guilabel"><sgmltag class="starttag">guilabel</sgmltag></link></para></listitem>
+<listitem><para><link linkend="guimenu"><sgmltag class="starttag">guimenu</sgmltag></link></para></listitem>
+<listitem><para><link linkend="guimenuitem"><sgmltag class="starttag">guimenuitem</sgmltag></link></para></listitem>
+<listitem><para><link linkend="guisubmenu"><sgmltag class="starttag">guisubmenu</sgmltag></link></para></listitem>
+<listitem><para><link linkend="glossdef"><sgmltag class="starttag">glossdef</sgmltag></link></para></listitem>
+<listitem><para><link linkend="glossdiv"><sgmltag class="starttag">glossdiv</sgmltag></link></para></listitem>
+<listitem><para><link linkend="glossentry"><sgmltag class="starttag">glossentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="glosslist"><sgmltag class="starttag">glosslist</sgmltag></link></para></listitem>
+<listitem><para><link linkend="glosssee"><sgmltag class="starttag">glosssee</sgmltag></link></para></listitem>
+<listitem><para><link linkend="glossseealso"><sgmltag class="starttag">glossseealso</sgmltag></link></para></listitem>
+<listitem><para><link linkend="glossterm"><sgmltag class="starttag">glossterm</sgmltag></link></para></listitem>
+<listitem><para><link linkend="glossary"><sgmltag class="starttag">glossary</sgmltag></link></para></listitem>
+<listitem><para><link linkend="glossaryinfo"><sgmltag class="starttag">glossaryinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="graphic"><sgmltag class="starttag">graphic</sgmltag></link></para></listitem>
+<listitem><para><link linkend="graphicco"><sgmltag class="starttag">graphicco</sgmltag></link></para></listitem>
+<listitem><para><link linkend="group"><sgmltag class="starttag">group</sgmltag></link></para></listitem>
+<listitem><para><link linkend="hardware"><sgmltag class="starttag">hardware</sgmltag></link></para></listitem>
+<listitem><para><link linkend="highlights"><sgmltag class="starttag">highlights</sgmltag></link></para></listitem>
+<listitem><para><link linkend="holder"><sgmltag class="starttag">holder</sgmltag></link></para></listitem>
+<listitem><para><link linkend="honorific"><sgmltag class="starttag">honorific</sgmltag></link></para></listitem>
+<listitem><para><link linkend="isbn"><sgmltag class="starttag">isbn</sgmltag></link></para></listitem>
+<listitem><para><link linkend="issn"><sgmltag class="starttag">issn</sgmltag></link></para></listitem>
+<listitem><para><link linkend="itermset"><sgmltag class="starttag">itermset</sgmltag></link></para></listitem>
+<listitem><para><link linkend="imagedata"><sgmltag class="starttag">imagedata</sgmltag></link></para></listitem>
+<listitem><para><link linkend="imageobject"><sgmltag class="starttag">imageobject</sgmltag></link></para></listitem>
+<listitem><para><link linkend="imageobjectco"><sgmltag class="starttag">imabeobjectco</sgmltag></link></para></listitem>
+<listitem><para><link linkend="important"><sgmltag class="starttag">important</sgmltag></link></para></listitem>
+<listitem><para><link linkend="index"><sgmltag class="starttag">index</sgmltag></link></para></listitem>
+<listitem><para><link linkend="indexdiv"><sgmltag class="starttag">indexdiv</sgmltag></link></para></listitem>
+<listitem><para><link linkend="indexentry"><sgmltag class="starttag">indexentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="indexinfo"><sgmltag class="starttag">indexinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="indexterm"><sgmltag class="starttag">indexterm</sgmltag></link></para></listitem>
+<listitem><para><link linkend="informalequation"><sgmltag class="starttag">informalequation</sgmltag></link></para></listitem>
+<listitem><para><link linkend="informalexample"><sgmltag class="starttag">informalexample</sgmltag></link></para></listitem>
+<listitem><para><link linkend="informalfigure"><sgmltag class="starttag">informalfigure</sgmltag></link></para></listitem>
+<listitem><para><link linkend="informaltable"><sgmltag class="starttag">informaltable</sgmltag></link></para></listitem>
+<listitem><para><link linkend="initializer"><sgmltag class="starttag">initializer</sgmltag></link></para></listitem>
+<listitem><para><link linkend="inlineequation"><sgmltag class="starttag">inlineequation</sgmltag></link></para></listitem>
+<listitem><para><link linkend="inlinegraphic"><sgmltag class="starttag">inlinegraphic</sgmltag></link></para></listitem>
+<listitem><para><link linkend="inlinemediaobject"><sgmltag class="starttag">inlinemediaobject</sgmltag></link></para></listitem>
+<listitem><para><link linkend="interface"><sgmltag class="starttag">interface</sgmltag></link></para></listitem>
+<listitem><para><link linkend="interfacedefinition"><sgmltag class="starttag">interfacedefinition</sgmltag></link></para></listitem>
+<listitem><para><link linkend="interfacename"><sgmltag class="starttag">interfacename</sgmltag></link></para></listitem>
+<listitem><para><link linkend="invpartnumber"><sgmltag class="starttag">invpartnumber</sgmltag></link></para></listitem>
+<listitem><para><link linkend="issuenum"><sgmltag class="starttag">issuenum</sgmltag></link></para></listitem>
+<listitem><para><link linkend="itemizedlist"><sgmltag class="starttag">itemizedlist</sgmltag></link></para></listitem>
+<listitem><para><link linkend="jobtitle"><sgmltag class="starttag">jobtitle</sgmltag></link></para></listitem>
+<listitem><para><link linkend="keycap"><sgmltag class="starttag">keycap</sgmltag></link></para></listitem>
+<listitem><para><link linkend="keycode"><sgmltag class="starttag">keycode</sgmltag></link></para></listitem>
+<listitem><para><link linkend="keycombo"><sgmltag class="starttag">keycombo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="keysym"><sgmltag class="starttag">keysym</sgmltag></link></para></listitem>
+<listitem><para><link linkend="keyword"><sgmltag class="starttag">keyword</sgmltag></link></para></listitem>
+<listitem><para><link linkend="keywordset"><sgmltag class="starttag">keywordset</sgmltag></link></para></listitem>
+<listitem><para><link linkend="legalnotice"><sgmltag class="starttag">legalnotice</sgmltag></link></para></listitem>
+<listitem><para><link linkend="lineannotation"><sgmltag class="starttag">lineannotation</sgmltag></link></para></listitem>
+<listitem><para><link linkend="lineage"><sgmltag class="starttag">lineage</sgmltag></link></para></listitem>
+<listitem><para><link linkend="link"><sgmltag class="starttag">link</sgmltag></link></para></listitem>
+<listitem><para><link linkend="listitem"><sgmltag class="starttag">listitem</sgmltag></link></para></listitem>
+<listitem><para><link linkend="literal"><sgmltag class="starttag">literal</sgmltag></link></para></listitem>
+<listitem><para><link linkend="literallayout"><sgmltag class="starttag">literallayout</sgmltag></link></para></listitem>
+<listitem><para><link linkend="lot"><sgmltag class="starttag">lot</sgmltag></link></para></listitem>
+<listitem><para><link linkend="lotentry"><sgmltag class="starttag">lotentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="manvolnum"><sgmltag class="starttag">manvolnum</sgmltag></link></para></listitem>
+<listitem><para><link linkend="markup"><sgmltag class="starttag">markup</sgmltag></link></para></listitem>
+<listitem><para><link linkend="medialabel"><sgmltag class="starttag">medialabel</sgmltag></link></para></listitem>
+<listitem><para><link linkend="mediaobject"><sgmltag class="starttag">mediaobject</sgmltag></link></para></listitem>
+<listitem><para><link linkend="mediaobjectco"><sgmltag class="starttag">mediaobjectco</sgmltag></link></para></listitem>
+<listitem><para><link linkend="member"><sgmltag class="starttag">member</sgmltag></link></para></listitem>
+<listitem><para><link linkend="menuchoice"><sgmltag class="starttag">menuchoice</sgmltag></link></para></listitem>
+<listitem><para><link linkend="methodname"><sgmltag class="starttag">methodname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="methodparam"><sgmltag class="starttag">methodparam</sgmltag></link></para></listitem>
+<listitem><para><link linkend="methodsynopsis"><sgmltag class="starttag">methodsynopsis</sgmltag></link></para></listitem>
+<listitem><para><link linkend="modespec"><sgmltag class="starttag">modespec</sgmltag></link></para></listitem>
+<listitem><para><link linkend="modifier"><sgmltag class="starttag">modifier</sgmltag></link></para></listitem>
+<listitem><para><link linkend="mousebutton"><sgmltag class="starttag">mousebutton</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msg"><sgmltag class="starttag">msg</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msgaud"><sgmltag class="starttag">nmsgaud</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msgentry"><sgmltag class="starttag">msgentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msgexplan"><sgmltag class="starttag">msgexplan</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msginfo"><sgmltag class="starttag">msginfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msglevel"><sgmltag class="starttag">msglevel</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msgmain"><sgmltag class="starttag">msgmain</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msgorig"><sgmltag class="starttag">msgorig</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msgrel"><sgmltag class="starttag">msgrel</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msgset"><sgmltag class="starttag">msgset</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msgsub"><sgmltag class="starttag">msgsub</sgmltag></link></para></listitem>
+<listitem><para><link linkend="msgtext"><sgmltag class="starttag">msgtext</sgmltag></link></para></listitem>
+<listitem><para><link linkend="note"><sgmltag class="starttag">note</sgmltag></link></para></listitem>
+<listitem><para><link linkend="olink"><sgmltag class="starttag">olink</sgmltag></link></para></listitem>
+<listitem><para><link linkend="objectinfo"><sgmltag class="starttag">objectinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="option"><sgmltag class="starttag">option</sgmltag></link></para></listitem>
+<listitem><para><link linkend="optional"><sgmltag class="starttag">optional</sgmltag></link></para></listitem>
+<listitem><para><link linkend="orderedlist"><sgmltag class="starttag">orderedlist</sgmltag></link></para></listitem>
+<listitem><para><link linkend="orgdiv"><sgmltag class="starttag">orgdiv</sgmltag></link></para></listitem>
+<listitem><para><link linkend="orgname"><sgmltag class="starttag">orgname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="otheraddr"><sgmltag class="starttag">otheraddr</sgmltag></link></para></listitem>
+<listitem><para><link linkend="othercredit"><sgmltag class="starttag">othercredit</sgmltag></link></para></listitem>
+<listitem><para><link linkend="othername"><sgmltag class="starttag">othername</sgmltag></link></para></listitem>
+<listitem><para><link linkend="pob"><sgmltag class="starttag">pob</sgmltag></link></para></listitem>
+<listitem><para><link linkend="pagenums"><sgmltag class="starttag">pagenums</sgmltag></link></para></listitem>
+<listitem><para><link linkend="para"><sgmltag class="starttag">para</sgmltag></link></para></listitem>
+<listitem><para><link linkend="paramdef"><sgmltag class="starttag">paramdef</sgmltag></link></para></listitem>
+<listitem><para><link linkend="parameter"><sgmltag class="starttag">parameter</sgmltag></link></para></listitem>
+<listitem><para><link linkend="part"><sgmltag class="starttag">part</sgmltag></link></para></listitem>
+<listitem><para><link linkend="partintro"><sgmltag class="starttag">partintro</sgmltag></link></para></listitem>
+<listitem><para><link linkend="phone"><sgmltag class="starttag">phone</sgmltag></link></para></listitem>
+<listitem><para><link linkend="phrase"><sgmltag class="starttag">phrase</sgmltag></link></para></listitem>
+<listitem><para><link linkend="postcode"><sgmltag class="starttag">postcode</sgmltag></link></para></listitem>
+<listitem><para><link linkend="preface"><sgmltag class="starttag">preface</sgmltag></link></para></listitem>
+<listitem><para><link linkend="prefaceinfo"><sgmltag class="starttag">prefaceinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="primary"><sgmltag class="starttag">primary</sgmltag></link></para></listitem>
+<listitem><para><link linkend="primaryie"><sgmltag class="starttag">primaryie</sgmltag></link></para></listitem>
+<listitem><para><link linkend="printhistory"><sgmltag class="starttag">printhistory</sgmltag></link></para></listitem>
+<listitem><para><link linkend="procedure"><sgmltag class="starttag">procedure</sgmltag></link></para></listitem>
+<listitem><para><link linkend="productname"><sgmltag class="starttag">productname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="productnumber"><sgmltag class="starttag">productnumber</sgmltag></link></para></listitem>
+<listitem><para><link linkend="programlisting"><sgmltag class="starttag">programlistingco</sgmltag></link></para></listitem>
+<listitem><para><link linkend="prompt"><sgmltag class="starttag">prompt</sgmltag></link></para></listitem>
+<listitem><para><link linkend="property"><sgmltag class="starttag">property</sgmltag></link></para></listitem>
+<listitem><para><link linkend="pubdate"><sgmltag class="starttag">pubdate</sgmltag></link></para></listitem>
+<listitem><para><link linkend="publisher"><sgmltag class="starttag">publisher</sgmltag></link></para></listitem>
+<listitem><para><link linkend="publishername"><sgmltag class="starttag">publishername</sgmltag></link></para></listitem>
+<listitem><para><link linkend="pubsnumber"><sgmltag class="starttag">pubsnumber</sgmltag></link></para></listitem>
+<listitem><para><link linkend="qandadiv"><sgmltag class="starttag">qandadiv</sgmltag></link></para></listitem>
+<listitem><para><link linkend="qandaentry"><sgmltag class="starttag">qandaentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="qandaset"><sgmltag class="starttag">qandaset</sgmltag></link></para></listitem>
+<listitem><para><link linkend="question"><sgmltag class="starttag">question</sgmltag></link></para></listitem>
+<listitem><para><link linkend="quote"><sgmltag class="starttag">quote</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refclass"><sgmltag class="starttag">refclass</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refdescriptor"><sgmltag class="starttag">refdescriptor</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refentry"><sgmltag class="starttag">refentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refentryinfo"><sgmltag class="starttag">refentryinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refentrytitle"><sgmltag class="starttag">refentrytitle</sgmltag></link></para></listitem>
+<listitem><para><link linkend="referenceinfo"><sgmltag class="starttag">referenceinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refmeta"><sgmltag class="starttag">refmeta</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refmiscinfo"><sgmltag class="starttag">refmiscinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refname"><sgmltag class="starttag">refname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refnamediv"><sgmltag class="starttag">refnamediv</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refpurpose"><sgmltag class="starttag">refpurpose</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refsect1"><sgmltag class="starttag">refsect1</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refsect1info"><sgmltag class="starttag">refsect1info</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refsect2"><sgmltag class="starttag">refsect2</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refsect2info"><sgmltag class="starttag">refsect2info</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refsect3"><sgmltag class="starttag">refsect3info</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refsect3info"><sgmltag class="starttag">refsect3info</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refsynopsisdiv"><sgmltag class="starttag">refsynopsisdiv</sgmltag></link></para></listitem>
+<listitem><para><link linkend="refsynopsisdivinfo"><sgmltag class="starttag">refsynopsisdivinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="reference"><sgmltag class="starttag">reference</sgmltag></link></para></listitem>
+<listitem><para><link linkend="releaseinfo"><sgmltag class="starttag">releaseinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="remark"><sgmltag class="starttag">remark</sgmltag></link></para></listitem>
+<listitem><para><link linkend="replaceable"><sgmltag class="starttag">replaceable</sgmltag></link></para></listitem>
+<listitem><para><link linkend="returnvalue"><sgmltag class="starttag">returnvalue</sgmltag></link></para></listitem>
+<listitem><para><link linkend="revdescription"><sgmltag class="starttag">revdescription</sgmltag></link></para></listitem>
+<listitem><para><link linkend="revhistory"><sgmltag class="starttag">revhistory</sgmltag></link></para></listitem>
+<listitem><para><link linkend="revnumber"><sgmltag class="starttag">revnumber</sgmltag></link></para></listitem>
+<listitem><para><link linkend="revremark"><sgmltag class="starttag">revremark</sgmltag></link></para></listitem>
+<listitem><para><link linkend="revision"><sgmltag class="starttag">revision</sgmltag></link></para></listitem>
+<listitem><para><link linkend="row"><sgmltag class="starttag">row</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sbr"><sgmltag class="starttag">sbr</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sgmltag"><sgmltag class="starttag">sgmltag</sgmltag></link></para></listitem>
+<listitem><para><link linkend="screen"><sgmltag class="starttag">screen</sgmltag></link></para></listitem>
+<listitem><para><link linkend="screenco"><sgmltag class="starttag">screenco</sgmltag></link></para></listitem>
+<listitem><para><link linkend="screeninfo"><sgmltag class="starttag">screeninfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="screenshot"><sgmltag class="starttag">screenshot</sgmltag></link></para></listitem>
+<listitem><para><link linkend="secondary"><sgmltag class="starttag">secondary</sgmltag></link></para></listitem>
+<listitem><para><link linkend="secondaryie"><sgmltag class="starttag">secondaryie</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect1"><sgmltag class="starttag">sect1</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect1info"><sgmltag class="starttag">sect1info</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect2"><sgmltag class="starttag">sect2</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect2info"><sgmltag class="starttag">sect2info</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect3"><sgmltag class="starttag">sect3</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect3info"><sgmltag class="starttag">sect3info</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect4"><sgmltag class="starttag">sect4</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect4info"><sgmltag class="starttag">sect4info</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect5"><sgmltag class="starttag">sect5</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sect5info"><sgmltag class="starttag">sect5info</sgmltag></link></para></listitem>
+<listitem><para><link linkend="section"><sgmltag class="starttag">section</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sectioninfo"><sgmltag class="starttag">sectioninfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="see"><sgmltag class="starttag">see</sgmltag></link></para></listitem>
+<listitem><para><link linkend="seealso"><sgmltag class="starttag">seealso</sgmltag></link></para></listitem>
+<listitem><para><link linkend="seealsoie"><sgmltag class="starttag">seealsoie</sgmltag></link></para></listitem>
+<listitem><para><link linkend="seeie"><sgmltag class="starttag">seeie</sgmltag></link></para></listitem>
+<listitem><para><link linkend="seg"><sgmltag class="starttag">seg</sgmltag></link></para></listitem>
+<listitem><para><link linkend="seglistitem"><sgmltag class="starttag">seglistitem</sgmltag></link></para></listitem>
+<listitem><para><link linkend="segmentedlist"><sgmltag class="starttag">segmentedlist</sgmltag></link></para></listitem>
+<listitem><para><link linkend="seriesinfo"><sgmltag class="starttag">seriesinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="seriesvolnums"><sgmltag class="starttag">seriesvolnums</sgmltag></link></para></listitem>
+<listitem><para><link linkend="set"><sgmltag class="starttag">set</sgmltag></link></para></listitem>
+<listitem><para><link linkend="setindex"><sgmltag class="starttag">setindex</sgmltag></link></para></listitem>
+<listitem><para><link linkend="setindexinfo"><sgmltag class="starttag">setindexinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="setinfo"><sgmltag class="starttag">setinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="shortaffil"><sgmltag class="starttag">shortaffil</sgmltag></link></para></listitem>
+<listitem><para><link linkend="shortcut"><sgmltag class="starttag">shortcut</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sidebar"><sgmltag class="starttag">sidebar</sgmltag></link></para></listitem>
+<listitem><para><link linkend="sidebarinfo"><sgmltag class="starttag">sidebarinfo</sgmltag></link></para></listitem>
+<listitem><para><link linkend="simpara"><sgmltag class="starttag">simpara</sgmltag></link></para></listitem>
+<listitem><para><link linkend="simplelist"><sgmltag class="starttag">simplelist</sgmltag></link></para></listitem>
+<listitem><para><link linkend="simplemsgentry"><sgmltag class="starttag">simplemsgentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="simplesect"><sgmltag class="starttag">simplesect</sgmltag></link></para></listitem>
+<listitem><para><link linkend="spanspec"><sgmltag class="starttag">spanspec</sgmltag></link></para></listitem>
+<listitem><para><link linkend="state"><sgmltag class="starttag">state</sgmltag></link></para></listitem>
+<listitem><para><link linkend="step"><sgmltag class="starttag">step</sgmltag></link></para></listitem>
+<listitem><para><link linkend="street"><sgmltag class="starttag">street</sgmltag></link></para></listitem>
+<listitem><para><link linkend="structfield"><sgmltag class="starttag">structfield</sgmltag></link></para></listitem>
+<listitem><para><link linkend="structname"><sgmltag class="starttag">structname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="substeps"><sgmltag class="starttag">substeps</sgmltag></link></para></listitem>
+<listitem><para><link linkend="subject"><sgmltag class="starttag">subject</sgmltag></link></para></listitem>
+<listitem><para><link linkend="subjectset"><sgmltag class="starttag">subjectset</sgmltag></link></para></listitem>
+<listitem><para><link linkend="subjectterm"><sgmltag class="starttag">subjectterm</sgmltag></link></para></listitem>
+<listitem><para><link linkend="subscript"><sgmltag class="starttag">subscript</sgmltag></link></para></listitem>
+<listitem><para><link linkend="subtitle"><sgmltag class="starttag">subtitle</sgmltag></link></para></listitem>
+<listitem><para><link linkend="superscript"><sgmltag class="starttag">superscript</sgmltag></link></para></listitem>
+<listitem><para><link linkend="surname"><sgmltag class="starttag">surname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="symbol"><sgmltag class="starttag">symbol</sgmltag></link></para></listitem>
+<listitem><para><link linkend="synopfragment"><sgmltag class="starttag">synopfragment</sgmltag></link></para></listitem>
+<listitem><para><link linkend="synopsis"><sgmltag class="starttag">synopsis</sgmltag></link></para></listitem>
+<listitem><para><link linkend="systemitem"><sgmltag class="starttag">systemitem</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tbody"><sgmltag class="starttag">tbody</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tfoot"><sgmltag class="starttag">tfoot</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tgroup"><sgmltag class="starttag">tgroup</sgmltag></link></para></listitem>
+<listitem><para><link linkend="thead"><sgmltag class="starttag">thead</sgmltag></link></para></listitem>
+<listitem><para><link linkend="table"><sgmltag class="starttag">table</sgmltag></link></para></listitem>
+<listitem><para><link linkend="term"><sgmltag class="starttag">term</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tertiary"><sgmltag class="starttag">tertiary</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tertiaryie"><sgmltag class="starttag">tertiaryie</sgmltag></link></para></listitem>
+<listitem><para><link linkend="textobject"><sgmltag class="starttag">textobject</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tip"><sgmltag class="starttag">tip</sgmltag></link></para></listitem>
+<listitem><para><link linkend="title"><sgmltag class="starttag">title</sgmltag></link></para></listitem>
+<listitem><para><link linkend="titleabbrev"><sgmltag class="starttag">titleabbrev</sgmltag></link></para></listitem>
+<listitem><para><link linkend="toc"><sgmltag class="starttag">toc</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tocback"><sgmltag class="starttag">tocback</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tocchap"><sgmltag class="starttag">tocchap</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tocentry"><sgmltag class="starttag">tocentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tocfront"><sgmltag class="starttag">tocfront</sgmltag></link></para></listitem>
+<listitem><para><link linkend="toclevel1"><sgmltag class="starttag">toclevel1</sgmltag></link></para></listitem>
+<listitem><para><link linkend="toclevel2"><sgmltag class="starttag">toclevel2</sgmltag></link></para></listitem>
+<listitem><para><link linkend="toclevel3"><sgmltag class="starttag">toclevel3</sgmltag></link></para></listitem>
+<listitem><para><link linkend="toclevel4"><sgmltag class="starttag">toclevel4</sgmltag></link></para></listitem>
+<listitem><para><link linkend="toclevel5"><sgmltag class="starttag">toclevel5</sgmltag></link></para></listitem>
+<listitem><para><link linkend="tocpart"><sgmltag class="starttag">tocpart</sgmltag></link></para></listitem>
+<listitem><para><link linkend="token"><sgmltag class="starttag">token</sgmltag></link></para></listitem>
+<listitem><para><link linkend="trademark"><sgmltag class="starttag">trademark</sgmltag></link></para></listitem>
+<listitem><para><link linkend="type"><sgmltag class="starttag">type</sgmltag></link></para></listitem>
+<listitem><para><link linkend="ulink"><sgmltag class="starttag">ulink</sgmltag></link></para></listitem>
+<listitem><para><link linkend="userinput"><sgmltag class="starttag">userinput</sgmltag></link></para></listitem>
+<listitem><para><link linkend="varargs"><sgmltag class="starttag">varargs</sgmltag></link></para></listitem>
+<listitem><para><link linkend="varlistentry"><sgmltag class="starttag">varlistentry</sgmltag></link></para></listitem>
+<listitem><para><link linkend="varname"><sgmltag class="starttag">varname</sgmltag></link></para></listitem>
+<listitem><para><link linkend="variablelist"><sgmltag class="starttag">variablelist</sgmltag></link></para></listitem>
+<listitem><para><link linkend="videodata"><sgmltag class="starttag">videodata</sgmltag></link></para></listitem>
+<listitem><para><link linkend="videoobject"><sgmltag class="starttag">videoobject</sgmltag></link></para></listitem>
+<listitem><para><link linkend="void"><sgmltag class="starttag">void</sgmltag></link></para></listitem>
+<listitem><para><link linkend="volumenum"><sgmltag class="starttag">volumenum</sgmltag></link></para></listitem>
+<listitem><para><link linkend="warning"><sgmltag class="starttag">warning</sgmltag></link></para></listitem>
+<listitem><para><link linkend="wordasword"><sgmltag class="starttag">wordasword</sgmltag></link></para></listitem>
+<listitem><para><link linkend="xref"><sgmltag class="starttag">xref</sgmltag></link></para></listitem>
+<listitem><para><link linkend="year"><sgmltag class="starttag">year</sgmltag></link></para></listitem>
+</itemizedlist>
+
+</chapter>
+
+<chapter id="credits-and-license">
+<title>Credits and License</title>
+<para>Document copyright 2000, 2001 Lauri Watts
+<email>lauri@kde.org</email></para>
+
+<para>
+This reference was written with substantial help and input from the
+following people who definitely deserve credit:
+</para>
+
+<itemizedlist>
+<listitem><para>Frederik Fouvry</para></listitem>
+<listitem><para>Eric Bischoff</para></listitem>
+<listitem><para>Michael McBride</para></listitem>
+<listitem><para>Lee Wee Tiong</para></listitem>
+<listitem><para>Philip Rodrigues</para></listitem>
+<listitem><para>Eyal Lotem
+<email>GNUPeaker@yahoo.com</email></para></listitem>
+<listitem><para>Malte Starostik
+<email>malte.starostik@t-online.de</email></para></listitem>
+<listitem><para>Antonio Larossa Jiminez</para></listitem>
+</itemizedlist>
+
+&underFDL;
+</chapter>
+
+<appendix id="appendix-entities">
+<title>Entities</title>
+
+<para>TODO</para>
+</appendix>
+
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+-->
diff --git a/doc/tutorials/styleguide/CMakeLists.txt b/doc/tutorials/styleguide/CMakeLists.txt
new file mode 100644
index 0000000..396682f
--- /dev/null
+++ b/doc/tutorials/styleguide/CMakeLists.txt
@@ -0,0 +1,9 @@
+#################################################
+#
+#  Improvements and feedback are welcome
+#
+#  This file is released under GPL >= 2
+#
+#################################################
+
+tde_create_handbook( DESTINATION khelpcenter/styleguide )
diff --git a/doc/tutorials/styleguide/Makefile.am b/doc/tutorials/styleguide/Makefile.am
new file mode 100644
index 0000000..4169155
--- /dev/null
+++ b/doc/tutorials/styleguide/Makefile.am
@@ -0,0 +1,3 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/tutorials/styleguide/index.docbook b/doc/tutorials/styleguide/index.docbook
new file mode 100644
index 0000000..8c94356
--- /dev/null
+++ b/doc/tutorials/styleguide/index.docbook
@@ -0,0 +1,466 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kde-authors '<personname><surname>The &kde; Documentation Team</surname></personname>'>
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"><!-- change language only here -->
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &tde; Style Guide</title>
+
+<authorgroup>
+<author>&kde-authors;</author>
+<author>&tde-authors;</author>
+</authorgroup>
+
+<copyright>
+<year>2002</year>
+<holder>The KDE e.V.</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; style standards for writing documentation.
+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="introduction">
+<title>Introduction</title>
+
+<para>The purpose of writing documentation for the &tde; Project, is
+to create for all the users, a complete, well organized set of
+documentation for each and every component of the &tde; project. In
+order to achieve this goal, we have drafted the following guide to
+help.</para>
+
+<para>This document is very new, and at the moment, very
+sparse.</para>	
+
+<para>If you have comments or additions, please do not hesitate to
+suggest them on the kde-doc-english@kde.org mailing list.</para>
+
+<para>In the meantime, here are some short notes based on content that
+was previously on the <ulink url="http://i18n.kde.org/">&tde;
+i18n</ulink> website.</para>
+
+</chapter>
+
+<chapter id="consistency">
+<title>Consistency</title>
+
+<sect1 id="dates-and-revisions">
+<title>Dates and Revision Numbers</title>
+
+<para>While it may seem like a minor issue, and a minor part of your
+document, it is very important that the following guidelines are
+adhered to:</para>
+
+<itemizedlist>
+<listitem>
+<para>All dates which are part of the text of your document
+should be spelled out &ie; <quote>March 2, 2000</quote></para>
+<para>This is the only way to be sure that <quote>03/02/2000</quote>
+is interpreted correctly in all languages, and by all readers.</para>
+<important><para>Exception: in the <sgmltag>date</sgmltag> tag, dates
+should be in the <quote>YYYY-MM-DD</quote> format.</para>
+</important>
+</listitem>
+<listitem>
+<para>All information included between the <sgmltag
+class="starttag">releaseinfo</sgmltag> and <sgmltag
+class="endtag">releaseinfo</sgmltag> should match the release number
+of the application.</para>
+</listitem>
+</itemizedlist>
+</sect1>
+
+<sect1 id="screenshots">
+<title>Screenshot Consistency</title>
+
+<para>To create consistent screenshots, use an environment where all requirements can
+be configured without interfering with your normal production environment. One option
+is a virtual machine. Another option is creating at least two themes. One theme is the
+normal everyday theme for production. The other theme is for handbook screenshots.
+Toggle between the two themes as necessary. A third option is a separate user
+account configured as required.</para>
+
+<para>To strive for a look of consistency with screenshots, please abide by the
+following requirements.</para>
+
+<itemizedlist>
+
+<listitem>
+<para>No personal information. That includes login names. Be careful when including
+window decorations because the title bar could include such information. Use a testing
+account or a virtual machine when such information cannot be avoided.</para>
+</listitem>
+<listitem>
+<para>Use &ksnapshot;. Normally use the <guilabel>Window Under Cursor</guilabel> option. Use the
+<ulink url="help:/ksnapshot"> &ksnapshot; Handbook</ulink> to learn more.</para>
+</listitem>
+<listitem>
+<para>Using the &ksnapshot; <guilabel>Include window decorations</guilabel> option is not
+required and not forbidden. Just ensure the decorations to do not interfere with the
+purpose of the screenshot.</para>
+</listitem>
+<listitem>
+<para>PNG images only.</para>
+</listitem>
+<listitem>
+<para>Window decorations: KDE2, Keramik, or Plastik.</para>
+</listitem>
+<listitem>
+<para>Widget style: KDE Classic, Keramik, or Plastik.</para>
+</listitem>
+<listitem>
+<para>In &kcontrol;->Style, enable <guilabel>Show icons on buttons</guilabel>.</para>
+</listitem>
+<listitem>
+<para>Colors: TDE defaults.</para>
+</listitem>
+<listitem>
+<para>Background: No wallpaper, no gradients.</para>
+</listitem>
+
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="other-consistency-issues">
+<title>Other Consistency Issues</title>
+
+<itemizedlist>
+<listitem>
+<para>Please submit only plain <acronym>ASCII</acronym> text, or
+Docbook &XML;. Anything else will be returned to you. (Docbook &XML; is
+preferred.)</para>
+</listitem> 
+<listitem>
+<para>Make sure you first read, and follow, the documentation template
+provided. You can find this in the source folder for &tde;. Simply
+point a browser to <filename
+class="directory">tdelibs/doc/kdoctools/template.docbook</filename></para>
+<note><para>If there is existing documentation (from the developer, or
+from &tde; 1.x or 2.x), then use that as a base to work from, but it
+needs to conform to the layout from the documentation
+template.</para></note>
+</listitem>
+<listitem>
+<para>Spell things according to Standard American spelling, except for
+proper names, places, &etc;</para>
+</listitem>
+<listitem>
+<para>Make sure to set your spell checker to US English. Make sure you
+<emphasis>use</emphasis> your spell checker.</para>
+</listitem>
+<listitem>
+<para>If there is a non-English word, which is used in an English
+sentence, be sure to spell this correctly, using appropriate accent
+marks, and any special characters. Use the &kcharselect; application
+if you don't have the correct keys on your keyboard.</para>
+</listitem>
+<listitem>
+<para>Abbreviations should be capitalized, unless they are
+specifically intended      to not be capitalized. (&ie; is a good
+example).</para>
+</listitem>
+<listitem>
+<para>Punctuation within numbers should be Americanized:
+10,000.00</para>
+</listitem>
+<listitem>
+<para>It is more legible to use written numbers where the number has
+no technical value, &eg; <quote>There are three buttons on the
+dialog</quote>. In this context <quote>3</quote> is not technically
+significant. Numbers with technical significance should be written as
+figures. (&ie; <quote>a 10 MB file</quote>, not <quote>a ten MB
+file</quote>.)</para>
+</listitem>
+<listitem>
+<para>Spell check and proofread your work before you send it in. Or
+even better, have someone else read it over. Spell checking programs
+won't catch incorrect words such as using <quote>their</quote> for
+<quote>there</quote>.</para>
+</listitem>
+</itemizedlist>
+</sect1>
+
+</chapter>
+
+<chapter id="writing-well">
+<title>Writing Well</title>
+
+<para>Some things to think about when writing documentation</para>
+
+<para>How many times have you attempted to read a man page, and given
+up in frustration &mdash; all the facts are there, but the writing is
+too dry and technical for you to make sense of them? We want to avoid
+this with the documentation you're writing. </para>
+
+<para>It's difficult to avoid the very dry, choppy style we're all too
+familiar with, but do try to make the writing flow and keep it
+<emphasis>user-friendly</emphasis>. Try to be as friendly as you can
+manage without being patronizing, and without sacrificing clarity or
+detail.</para>
+
+<para> Things you should consider: </para>
+
+<itemizedlist>
+
+<listitem>
+<para>Make sure you explain all aspects of the interface, and that you
+don't leave out any command line options available. </para>
+</listitem>
+
+<listitem>
+<para>It's important to keep a logical progression of difficulty. Keep
+the first few pages of the document simple, and accessible to users
+who have never seen the application before. More technical information
+should appear towards the end of the document. </para>
+</listitem>
+
+<listitem>
+<para>Be sure to write to the level of the intended reader. By this we
+mean, a Samba control module has a very different user base than a
+user of a game, and the manuals should reflect this. Don't insult the
+Samba networker's intelligence, and don't assume knowledge for the
+gamer that might not be there.</para> 
+</listitem>
+
+<listitem>
+<para>It is highly encouraged to use screenshots, pictures of action
+buttons, &etc; These are &GUI; applications, and a picture can be worth a
+thousand words. </para>
+</listitem> 
+
+<listitem>
+<para>Please define computer abbreviations, unless they are well
+understood by all computer users (There's no need to define
+<acronym>RAM</acronym>, <acronym>PC</acronym>, &etc;).</para>
+
+<para>For example, <quote>If you are going to use
+<acronym>PPP</acronym> (Point to Point Protocol),
+then.....</quote>. Define it only once though, in this example you
+could now use <acronym>PPP</acronym> without explanation for the rest
+of the document.</para>
+
+<para>The first time you introduce the word you should use <sgmltag
+class="starttag">firstterm</sgmltag> or consider setting up a glossary
+and using <sgmltag class="starttag">glossentry</sgmltag>.</para>
+</listitem>
+
+<listitem>
+<para>Remember the small things: If it's dockable, explain how to do
+that. Don't forget to mention where it installs itself in the K
+menu. If there are any environment settings required, and if they must
+be set manually, explain how to do that - if they're set
+automatically, they still need to be documented.</para>
+</listitem>
+
+<listitem>
+<para>Write something you would be happy to read as a user who doesn't
+know how the application works. Perhaps if you have a friend or family
+member who isn't familiar with the application you're writing about,
+have them work through using it, with your documentation as a
+guide. </para>
+</listitem>
+</itemizedlist>
+
+</chapter>
+
+<chapter id="more-hints">
+<title>Other general tips and hints for good writing</title>
+
+<para>A good way to catch simple errors is to read the text out loud,
+or have someone else read it to you. Passages that don't
+<quote>flow</quote> or have obviously awkward construction of the type
+you may miss on the screen, will usually become blindingly obvious
+when you hear them. This is especially the case with detecting really
+long sentences, as you will run out of breath and turn blue.</para>
+
+<para>Be concise, be specific, and be direct. Choose your words
+carefully, and  be certain you know the exact meaning of every word
+you use. Is it the right word? Use a dictionary, and find out.</para>
+
+<para>Use complete sentences. Not fragments. Like these ones.</para>
+
+<para>While talking about sentences:</para>
+<itemizedlist>
+<listitem>
+<para>Avoid run on sentences, sentences that cover several different
+subjects, or sentences that could be broken up into several sentences;
+avoid sentences that can fill a whole paragraph all by themselves and
+that are really long, like this one, which is all of the above.</para>
+</listitem>
+<listitem>
+<para>
+Use a comma before <quote>and</quote> in compound sentences, &eg;
+<quote>Use the left mouse button to select and copy text, and the
+middle mouse button to paste it.</quote></para>
+</listitem>
+<listitem>
+<para>Keep to logical sentence order.</para>
+<para>For example, <quote>&konqueror; is a web browser with the
+ability to browse file systems and it includes a javascript
+interpreter.</quote> (Do you see why this is awkward?)</para>
+</listitem>
+<listitem>
+<para>Try not to use the same word several times in the same sentence.
+An exception to this, is an application command or technical word,
+where this repetition is necessary, and improves clarity.</para>
+</listitem>
+<listitem>
+<para>Do not start sentences with any of <quote>and,</quote>
+<quote>so,</quote> <quote>but,</quote> <quote>because,</quote> or
+<quote>however.</quote></para>
+</listitem>
+<listitem>
+<para>Try to avoid contractions, rather spell out both words; &eg;,
+<quote>it is</quote> rather than <quote>it's</quote>; <quote>can
+not</quote> rather than <quote>can't</quote></para>
+</listitem>
+<listitem>
+<para>There is no need to worry about simple text formatting such as
+leaving two spaces after punctuation or indenting paragraphs. This is
+all handled by Docbook &XML; and the <acronym>XSLT</acronym>
+stylesheets in use.</para>
+</listitem>
+</itemizedlist>
+
+<para>Remember, we have also an active proofreading team, and there is
+always someone to help you with grammar, so just
+write and have fun!</para>
+
+</chapter>
+
+<chapter id="resources">
+<title>Resources</title>
+
+<sect1 id="general-purpose-sites">
+<title>General Purpose Websites</title>
+
+<para>A few sites you may find worth bookmarking, or at least
+visiting.</para>
+
+<sect2 id="dictionary-sites">
+<title>Dictionary Sites</title>
+
+<itemizedlist>
+<listitem>
+<para><ulink url="http://www.m-w.com/">Merriam Webster
+Online</ulink></para>
+</listitem>
+<listitem>
+<para><ulink
+url="http://www.dictionary.com/">Dictionary.com</ulink></para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="thesaurus-sites">
+<title>Thesaurus Sites</title>
+
+<itemizedlist>
+<listitem>
+<para><ulink url="http://www.m-w.com/">Merriam-Webster</ulink> have a
+thesaurus as well as a dictionary</para>
+</listitem>
+<listitem>
+<para><ulink url="http://www.thesaurus.com/">Roget's
+Thesaurus</ulink></para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="other-style-guides">
+<title>Style Guides and Other Resources</title>
+
+<itemizedlist>
+<listitem>
+<para><ulink
+url="http://www.cc.columbia.edu/acis/bartleby/strunk/">Strunk &amp;
+White</ulink> is the base style guide for many newspapers and press
+galleries. If you want to look up a grammar or usage question, this is
+the place to go.</para> </listitem>
+
+<listitem>
+<para>The <ulink
+url="news://alt.usage.english">alt.usage.english</ulink> newsgroup.
+If you'd like every sentence chewed over, dissected, and then
+rewritten several conflicting ways, or some great advice about bacon,
+you'll find both here. Many real live editors and authors hang out
+here, and they do know their stuff. Just make sure you read all ten
+or so <acronym>FAQ</acronym>'s before asking a question.</para>
+</listitem>
+</itemizedlist>
+<para>Other possibly useful sites</para>
+
+<itemizedlist>
+<listitem><para><ulink
+url="http://hotwired.lycos.com/hardwired/wiredstyle/biblio/">The Wired 
+      Style Guide Bookmarks section</ulink></para>
+</listitem>
+
+<listitem>
+<para><ulink
+url="http://www2.rscc.cc.tn.us/%7Ejordan_jj/OWL/Clutter.html">http://www2.rscc.cc.tn.us/~jordan_jj/OWL/Clutter.html</ulink>
+If you tend to write very wordy sentences, here's a page with some
+help for you. Includes a useful table of ways to rewrite common
+mistakes.</para>
+</listitem>
+<listitem>
+<para><ulink
+url="http://owl.english.purdue.edu/Files/116.html">http://owl.english.purdue.edu/Files/116.html
+</ulink> is a page about how to make sentences <quote>flow</quote>
+better</para>
+</listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+
+</chapter>
+
+<!-- &trademarks; -->
+
+
+<chapter id="credits-and-license">
+<title>Credits and Licenses</title>
+
+<para>The &tde; Documentation Style Guide</para>
+
+<!-- FIXME proper credits section -->
+<para>Copyright 2002, Lauri Watts, Mike McBride, Eric Bischoff,
+Frederik Fouvry.</para>
+<para>Copyright &tde-copyright-date;, &tde-authors;.</para>
+
+&underFDL;
+
+</chapter>
+
+<!-- &wordlist; -->
+
+</book>
diff --git a/tutorials/.directory b/tutorials/.directory
new file mode 100644
index 0000000..9efae07
--- /dev/null
+++ b/tutorials/.directory
@@ -0,0 +1,105 @@
+[Desktop Entry]
+Name=Tutorials
+Name[bg]=Ръководства
+Name[ca]=Programes d'aprenentatge
+Name[cs]=Návody
+Name[csb]=Tutoriale
+Name[cy]=Hyfforddiadau
+Name[da]=Øvelser
+Name[de]=Anleitungen
+Name[el]=Οδηγός χρήσης
+Name[eo]=Eklerniloj
+Name[es]=Tutoriales
+Name[et]=Õppematerjalid
+Name[fo]=Skeið
+Name[fr]=Didactitiels
+Name[hr]=Praktični vodič
+Name[hu]=Bevezetők
+Name[id]=Tutorial
+Name[is]=Kennsluefni
+Name[it]=Esercitazioni
+Name[ja]=チュートリアル
+Name[km]=បង្រៀន
+Name[ko]=따라하기
+Name[lo]=ການສອນ
+Name[lt]=Vadovai
+Name[mn]=Давтлага
+Name[nb]=Veivisere
+Name[nds]=Inföhren
+Name[nl]=Handleidingen
+Name[nn]=Innføringar
+Name[nso]=Dithutokopana
+Name[oc]=Introduccions
+Name[pl]=Podręczniki
+Name[pt]=Tutoriais
+Name[pt_BR]=Tutoriais
+Name[ro]=Tutoriale
+Name[ru]=Обучение
+Name[sk]=Návody
+Name[sl]=Učbeniki
+Name[sr]=Туторијали
+Name[sr@Latn]=Tutorijali
+Name[sv]=Handledningar
+Name[tg]=Дастурҳо
+Name[th]=ฝึกสอน
+Name[tr]=Kılavuzlar
+Name[uk]=Посібники
+Name[ven]=Dzikilasi dzau haseledza
+Name[wa]=Tutoriås
+Name[xh]=Izifundo zokuzikhumbuza
+Name[zh_TW]=教學
+Name[zu]=izifundo zokubuyekeza
+Comment=Tutorial and introduction documents.
+Comment[az]=Leksika və giriş sənədləri
+Comment[bg]=Ръководства и документи.
+Comment[br]=Kelennant ha teulioù deraouiñ.
+Comment[ca]=Curs d'aprenentatge i documents d'introducció.
+Comment[cs]=Návody a základní dokumenty.
+Comment[csb]=Tutorial ë wprowadzającé dokùmentë.
+Comment[cy]=Dogfenni cyflwyniad a hyfforddiadol
+Comment[da]=Øvelses- og introduktionsdokumenter.
+Comment[de]=Anleitungen und Einführungen
+Comment[el]=Οδηγός χρήσης και έγγραφα παρουσίασης.
+Comment[eo]=Eklernilaj kaj enkondukaj dokumentoj
+Comment[es]=Tutorial y documentos de introducción.
+Comment[et]=Õppematerjalid ja sissejuhatused.
+Comment[fr]=Didactitiels et documents de présentation
+Comment[hi]=शिक्षण पाठ तथा परिचय दस्तावेज़
+Comment[hr]=Praktični vodič i uvodni dokumenti.
+Comment[hu]=Bevezető jellegű dokumentumok.
+Comment[id]=Tutorial dan dokumen Pengenalan
+Comment[is]=Kennslu- og kynningarefni.
+Comment[it]=Esercitazione e documenti introduttivi.
+Comment[ja]=チュートリアルと導入用ドキュメント
+Comment[km]=ឯកសារ​បង្រៀន និង​ណែនាំ ។
+Comment[ko]=소개와 따라하기 글입니다.
+Comment[lo]=ການສອນແລະເອກະສານແນະນຳ
+Comment[lt]=Vadovai ir įvadiniai dokumentai
+Comment[lv]=Ievada un konsultāciju dokumenti.
+Comment[mn]=Давтлага ба удиртгал баримтууд
+Comment[mt]=Spjega u dokumenti ta' introduzzjoni.
+Comment[nb]=Veivisere og introduksjonsdokumenter
+Comment[nds]=Anleed- un Inföhrdokmenten
+Comment[nl]=Handleiding en inleidende documenten.
+Comment[nn]=Innføringar og introduksjonsdokument.
+Comment[nso]=Thutokopana le ditokomane tsa matseno.
+Comment[oc]=Documents e curs d'introduccion.
+Comment[pl]=Podręczniki i dokumenty dla początkujących.
+Comment[pt]=Tutoriais e documentos introdutórios.
+Comment[pt_BR]=Tutoriais e documentos introdutórios.
+Comment[ro]=Documente introductive și tutoriale.
+Comment[ru]=Документы по обучению.
+Comment[sk]=Dokumenty s úvodom a návodmi.
+Comment[sl]=Učbenik in uvodni dokumenti
+Comment[sr]=Туторијали и уводни документи.
+Comment[sr@Latn]=Tutorijali i uvodni dokumenti.
+Comment[sv]=Handlednings- och introduktionsdokument.
+Comment[tg]=Дастурҳо ва ҳуҷҷатҳои пешниҳод
+Comment[th]=เอกสารแนะนำและฝึกสอน
+Comment[tr]=Kılavuzlar ve belgeler
+Comment[uk]=Інструктаж і вступні документи.
+Comment[ven]=Kilasi yau haseledza na mathomo a manwalwa
+Comment[wa]=Tutoriå eyet documints di prezintaedje
+Comment[xh]=Isifundo sokuzikhumbuza kunye nesiqalo samaxwebhu.
+Comment[zh_TW]=教學與介紹文件。
+Comment[zu]=Ushicilelo lweziqalo kanye nezifundo zokubuyekeza
diff --git a/tutorials/CMakeLists.txt b/tutorials/CMakeLists.txt
new file mode 100644
index 0000000..c6732ad
--- /dev/null
+++ b/tutorials/CMakeLists.txt
@@ -0,0 +1,11 @@
+#################################################
+#
+#  Improvements and feedback are welcome
+#
+#  This file is released under GPL >= 2
+#
+#################################################
+
+install( FILES
+    .directory docprimer.desktop markup.desktop styleguide.desktop
+  DESTINATION ${DATA_INSTALL_DIR}/khelpcenter/plugins/Tutorials )
diff --git a/tutorials/Makefile.am b/tutorials/Makefile.am
new file mode 100644
index 0000000..44bd9d9
--- /dev/null
+++ b/tutorials/Makefile.am
@@ -0,0 +1,4 @@
+tut_DATA = .directory docprimer.desktop markup.desktop styleguide.desktop
+tutdir = $(kde_datadir)/khelpcenter/plugins/Tutorials
+
+
diff --git a/tutorials/docprimer.desktop b/tutorials/docprimer.desktop
new file mode 100644
index 0000000..b2d2a21
--- /dev/null
+++ b/tutorials/docprimer.desktop
@@ -0,0 +1,4 @@
+[Desktop Entry]
+Name=The TDE Documentation Primer
+DocPath=help:/khelpcenter/docprimer/index.html
+Icon=khelpcenter
diff --git a/tutorials/markup.desktop b/tutorials/markup.desktop
new file mode 100644
index 0000000..3ac4ebb
--- /dev/null
+++ b/tutorials/markup.desktop
@@ -0,0 +1,4 @@
+[Desktop Entry]
+Name=The TDE DocBook Markup Guide
+DocPath=help:/khelpcenter/markup/index.html
+Icon=khelpcenter
diff --git a/tutorials/styleguide.desktop b/tutorials/styleguide.desktop
new file mode 100644
index 0000000..17235ba
--- /dev/null
+++ b/tutorials/styleguide.desktop
@@ -0,0 +1,4 @@
+[Desktop Entry]
+Name=The TDE Help Handbook Style Guide
+DocPath=help:/khelpcenter/styleguide/index.html
+Icon=khelpcenter