|
|
|
|
<?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.trinitydesktop.org">http://bugs.trinitydesktop.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, ⪚ 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, ⪚
|
|
|
|
|
<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; ⪚,
|
|
|
|
|
<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 && 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 "committing")
|
|
|
|
|
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 "doc", 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 "trunk" link to get the main branch listing. Click on "TDE"
|
|
|
|
|
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 & 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 (⪚ &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
|
|
|
|
|
</sect2>
|
|
|
|
|
^
|
|
|
|
|
</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)
|
|
|
|
|
</para></answer></qandaentry>
|
|
|
|
|
^
|
|
|
|
|
</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 & 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> à 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> (<book> <chapter> <sectn>
|
|
|
|
|
<para>)</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>⪚</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, ⪚, <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>
|
|
|
|
|
<!ENTITY package "tde-module">
|
|
|
|
|
<!ENTITY % addindex "IGNORE">
|
|
|
|
|
<!ENTITY % English "INCLUDE">
|
|
|
|
|
</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><!-- TRANS:ROLES_OF_TRANSLATORS --></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 – 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
|
|
|
|
|
– 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.trinitydesktop.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.trinitydesktop.org">http://bugs.trinitydesktop.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
|
|
|
|
|
-->
|
