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

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

1 files changed, 2160 insertions, 0 deletions

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 
+-->