diff options
Diffstat (limited to 'doc/tutorials/docprimer')
| -rw-r--r-- | doc/tutorials/docprimer/CMakeLists.txt | 9 | ||||
| -rw-r--r-- | doc/tutorials/docprimer/Makefile.am | 3 | ||||
| -rw-r--r-- | doc/tutorials/docprimer/index.docbook | 2160 | ||||
| -rw-r--r-- | doc/tutorials/docprimer/kate-plugin.png | bin | 0 -> 81275 bytes | |||
| -rw-r--r-- | doc/tutorials/docprimer/kate-validate-xml.png | bin | 0 -> 70600 bytes | |||
| -rw-r--r-- | doc/tutorials/docprimer/quanta-doc-primer.png | bin | 0 -> 27366 bytes | |||
| -rw-r--r-- | doc/tutorials/docprimer/quanta-doc-structure.png | bin | 0 -> 12574 bytes | |||
| -rw-r--r-- | doc/tutorials/docprimer/quanta-entities.png | bin | 0 -> 6899 bytes | |||
| -rw-r--r-- | doc/tutorials/docprimer/quanta-tag.png | bin | 0 -> 60347 bytes | |||
| -rw-r--r-- | doc/tutorials/docprimer/quanta-toolbars.png | bin | 0 -> 28434 bytes | |||
| -rw-r--r-- | doc/tutorials/docprimer/quanta.png | bin | 0 -> 54149 bytes | |||
| -rw-r--r-- | doc/tutorials/docprimer/xmlval.png | bin | 0 -> 455 bytes | |||
| -rw-r--r-- | doc/tutorials/docprimer/xsltproc.png | bin | 0 -> 257 bytes |
13 files changed, 2172 insertions, 0 deletions
diff --git a/doc/tutorials/docprimer/CMakeLists.txt b/doc/tutorials/docprimer/CMakeLists.txt new file mode 100644 index 0000000..a4e5cd9 --- /dev/null +++ b/doc/tutorials/docprimer/CMakeLists.txt @@ -0,0 +1,9 @@ +################################################# +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION khelpcenter/docprimer ) diff --git a/doc/tutorials/docprimer/Makefile.am b/doc/tutorials/docprimer/Makefile.am new file mode 100644 index 0000000..4169155 --- /dev/null +++ b/doc/tutorials/docprimer/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/tutorials/docprimer/index.docbook b/doc/tutorials/docprimer/index.docbook new file mode 100644 index 0000000..28792b1 --- /dev/null +++ b/doc/tutorials/docprimer/index.docbook @@ -0,0 +1,2160 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kde-authors '<personname><surname>The &kde; Documentation Team</surname></personname>'> + <!ENTITY meinproc "<command>meinproc</command>"> + <!ENTITY checkxml "<command>checkXML</command>"> + <!ENTITY svn "<application>Subversion</application>"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &tde; Documentation Primer</title> + +<authorgroup> +<author>&kde-authors;</author> +<author> +<firstname>Carlos</firstname><surname>Woelz</surname> +</author> +<author>&tde-authors;</author> +</authorgroup> + +<copyright> +<year>2004</year> +<holder>The KDE Documentation Team</holder> +</copyright> +<copyright> +<year>2004</year> +<holder>Carlos Woelz</holder> +</copyright> +<copyright> +<year>&tde-copyright-date;</year> +<holder>&tde-team;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>&tde-release-date;</date> +<releaseinfo>&tde-release-version;</releaseinfo> + +<abstract> +<para> +This document provides information to start writing documentation for &tde;. +Please report any errors or omissions to +<email>trinity-devel@lists.pearsoncomputing.net</email>. +</para> +</abstract> + +<keywordset> +<keyword>TDE</keyword> +<keyword>Writing</keyword> +<keyword>Documentation</keyword> +</keywordset> + +</bookinfo> + +<chapter id="intro"> +<title>Introduction</title> + +<para> +The objective of this guide is to present all information required to make the +experience of writing &tde; documentation as easy as possible. +The next chapter gives some information about what skills you'll need for the task. +It is important to note that this guide is a joint effort of the &tde; +English Documentation Team and the &tde; Quality Team. You can ask for support +from both teams at any time.</para> + +<para>The <emphasis>&tde; English Documentation Team</emphasis> exists to +provide end-user documentation for the whole of &tde;. It's a big task, but an +important one. Although &tde; aims to be easy to use, not everything is obvious +without some help, and, in a project this big, even an experienced user +can't know every corner of &tde;.</para> +<para>The team is made up of people doing several different tasks: +<itemizedlist> +<listitem><para>Writing documentation for individual applications</para> +</listitem> +<listitem><para>Writing wider documentation for the whole of &tde; (like +the User Guide, or this document).</para> +</listitem> +<listitem><para>Proofreading and/or updating documentation to ensure +that it is correct and up-to-date.</para> +</listitem> +</itemizedlist> +Contributors to all of these areas are always welcome. You can +choose the area you would like to contribute to, based on your skills +and what you enjoy doing. If you need any help with documentation issues, +do not hesitate to ask at the &tde; Documentation mailing list, +<email>kde-doc-english@kde.org</email>, or on <acronym>IRC</acronym> in the channel #kde-docs on +<systemitem class="domainname">irc.freenode.net</systemitem>.</para> + + +<para> +The <emphasis>&tde; Quality Team</emphasis> provides support for +new contributors, and to coordinates the efforts of the volunteers. +The <ulink url="http://quality.kde.org">&tde; Quality Team Website</ulink> +provides guides to help you with some general development tasks, +such as getting the sources, +<ulink url="http://quality.kde.org/develop/cvsguide/">Building +&tde; From Source Step By Step</ulink>, and +<ulink url="http://quality.kde.org/develop/cvsguide/managestep.php"> +Working with Subversion</ulink>, &etc;. If these guides are not sufficient, and you +are having problems with &tde; development, we provide support for new contributors +at the &tde; Quality mailing list, <email>kde-quality@kde.org</email>, or on IRC +in the channel #kde-quality on +<filename class="directory">irc.freenode.net</filename>. +</para> + +</chapter> + + +<chapter id="getting-started"> +<title>Getting Started</title> + +<para>If you got this far reading this document, you're probably interested in +helping with &tde; documentation. If so, welcome aboard! We're always +happy to have new contributors, and whatever your skills, you can help +make &tde; even better. +<!-- Where to find us - mailing list, IRC, i18n.kde.org/doc --></para> + + +<sect1 id="requirements"> +<title>Things You'll Need</title> + +<para>To write documentation, there are only three things that are absolutely +necessary: some English knowledge, knowing what you want to document, and +access to a relatively recent version of the application you want to +document.</para> + +<note><para>Notice that the list of requirements does +<emphasis>not</emphasis> contain a requirement that you learn DocBook, +or any of the other tools we use. We're very happy to receive +documentation written in plain text. We would much rather have the +content and have to add formatting than have no content at all.</para> +</note> + +<sect2 id="requirements-english"> +<title>English Knowledge</title> + +<para>All &tde; documentation is originally written in English, so you +have to be able to write English to a reasonable level. That said, you +<emphasis>don't</emphasis> need to be a native speaker, and you don't +need to write word-perfect English. There are native English-speaking +proofreaders on the documentation team, and we would much rather have +<emphasis>some</emphasis> documentation that needs a little tweaking, +than no documentation at all. If you don't feel comfortable writing in +English, you might like to contribute to one of the &tde; translation +teams. You can find more information about translation on <ulink +url="http://i18n.kde.org">http://i18n.kde.org</ulink>.</para> + +<para>If you're a fluent English speaker with an eye for detail, you +might be interested in joining the proofreading +team. Just drop an email to <email>kde-doc-english@kde.org</email> if +you'd like to help the proofreaders.</para> +<!-- What about moving this to the other task section in the end? --> + + +</sect2> +<sect2 id="requirements-what-to-write"> +<title>Deciding What to Write About</title> +<para>&tde; is a very large project, with many different parts and +programs. Because of this, it can be hard to know where to start if you +want to contribute. There are a few rules of thumb that can help you +decide what to write about: +<itemizedlist> +<listitem><para>Find a topic that you'll enjoy writing about; It will +increase your motivation and help you to produce better documentation.</para> +</listitem> +<listitem><para>Write about an application you know well. You'll be able +to spend more time on writing and less time trying to work out how the +application works. On the other hand, documenting an application can be +a good way to learn about how it works, especially if you like a challenge!</para> +</listitem> +</itemizedlist> +</para> + +<para> +If you are looking for an application to document, or just checking the status +of the application you want to work with, the +<ulink url="http://wiki.kde.org/tiki-index.php?page=KDE+Quality+Team"> +&tde; Quality Team Wiki</ulink> contains lists of applications, organized +by modules, and their general status, including documentation status, and who +is working on it. Not all modules and applications are included or up to date, +but it is certainly worth checking.</para> + +<para>If you start documenting one of the listed applications, please add your +name to the wiki pages as well. But If you just can't find an application to +work with, write to <email>kde-doc-english@kde.org</email> and ask for +suggestions. There's always something available to do, but there's no obligation +to work on a particular application. Also, contributing to a document doesn't +force you into keeping that document up-to-date (although if you can do that, +it's very welcome!). +</para> + +<para>Another place to check is the &tde; bug list at <ulink +url="http://bugs.kde.org">http://bugs.kde.org</ulink>. This is usually +more detailed than the wiki, and provides a place to list specific small +changes that are needed to documents. These are often nice small jobs +to get you started contributing. A set of quick links to ready made +queries are available from the Documentation Project's <ulink +url="http://i18n.kde.org/doc/current.php"> +http://i18n.kde.org/doc/current.php</ulink> page.</para> + +<para>It is also helpful to the team to file more bugs like these +above. You will need a bugzilla account, and a recent copy of &tde;. +Simply open an application, choose +<menuchoice><guimenu>Help</guimenu><guimenuitem><replaceable>appname</replaceable> +Handbook</guimenuitem></menuchoice>. Then just read through the document, +following along in the application. &tde; applications are a moving +target to document, and sometimes the documentation has not yet caught +up with a change to the interface or behavior of an application. Feel +free to file bugs for any of these issues you find, in order of urgency:</para> + +<itemizedlist> +<listitem><para>Inaccurate information about how an application +works</para><para>For instance, if you previously needed to save +changes to a file before they take effect in the &GUI;, and this now +happens automatically, text referring to manual saving should be +removed, or it will confuse readers.</para> +<!-- This example is terrible, can someone find a better one? --> +</listitem> +<listitem><para>GUI options or menu items (or sometimes, entire +dialogs)</para><para>This often happens in configuration dialogs, when +new items are added, a new grouping of existing options may be +created.</para> +</listitem> +<listitem><para>New Features that are available and are not yet +documented.</para></listitem> +</itemizedlist> + +</sect2> + +<sect2 id="requirements-access"> +<title>Access to a Recent Version</title> + +<para>To make sure that the documentation you write is up-to-date, +you'll need to run a recent version of the application you are working with. +This normally means a recent beta version, a version of your application +compiled from sources or a version of &tde; compiled from sources in the &svn; +repository. If you think that compiling from sources is too burdensome, and you +cannot get some recent beta packages, there are still some interesting +possibilities to work around this requirement:</para> + +<itemizedlist> +<listitem><para> +Write about a stable application: there are many apps with a stable interface +which are still lacking good documentation. In this case, the last stable version +provided by your distribution will be sufficient to write about it, no +compiling required. +</para></listitem> + +<listitem><para> +Using a remote desktop connection to preview the development version is +an ideal solution to this problem. The FreeNX terminal server technology +enables decent desktop performance even with dial up Internet +connections. We are planning to offer this service to &tde; documenters, but +the infrastructure is not yet in place (as of May +2005). You may ask the <email>kde-quality@kde.org</email> mailing list +about it, if you think this is the way to go. +<!-- Also, Kurt's NX stuff will hopefully make this unnecessary Real --> +<!-- Soon Now. Once that happens, write about it here --> +</para></listitem> + +</itemizedlist> + +<para>If you want to try out building &tde; from sources, the &tde; Quality +website provides +<ulink url="http://quality.kde.org/develop/cvsguide/buildstep.php">a detailed, +step by step building guide</ulink>. You can find even more information at the +<ulink url="http://developer.kde.org/build">&tde; Developers Website</ulink>. +If you face any problems in the +compiling process you can't solve by reading the building guide, don't hesitate +to as for help on <email>kde-quality@kde.org</email>.</para> +</sect2> + +</sect1> + +</chapter> + +<chapter id="guidelines"> +<title>&tde; Writing Recommendations and Guidelines</title> + +<para>To maintain a uniform documentation set, there are some consistency rules +to be followed, that you should know before starting. In this chapter you will +find guidelines about targeting your audience, English usage, and what to cover +when you are documenting an application.</para> + +<para>We also offer some general writing tips to help you to +get started, provided by experienced &tde; documenters.</para> + +<sect1 id="guidelines-audience"> +<title>Writing for your Audience</title> + +<para>Since &tde; is used by people with a wide range of abilities, from +completely new users to long-time gurus, the documentation should be +appropriate to this audience. Therefore, in general, documentation +shouldn't assume too much about the knowledge of the reader, without +being patronizing. There are no hard-and-fast rules, but here are some +tips that should help:</para> +<itemizedlist> +<listitem><para>Remember that the audience varies with the application: for +example, a server control module has a very different user base than a user of a +game, and the manuals should reflect this. Don't insult the administrator +intelligence, and don't assume knowledge for the gamer that might not be +there.</para> +</listitem> +<listitem> +<para>Keep a logical progression of difficulty: Keep the first few pages +of the document simple, and accessible to users who have never seen the +application before. More technical information should appear towards the +end of the document.</para> +</listitem> +</itemizedlist> + +<para>Remember also that different types of documentation have different +purposes:</para> + +<variablelist> +<varlistentry> +<term>Application Handbooks</term> +<listitem> +<para>These may go into great depths on the configuration, behavior and +sometimes the philosophy of an application. There is scope to cover +corner cases of configuration, commonly asked questions, and advanced +troubleshooting techniques.</para> <para>They should also always contain +a complete reference to all the available menu functions and +configuration options for the application (but while these are required, +they should be certainly be considered a minimum of information to +provide.)</para> +<para>The Application Handbook should be answering the question: +<quote>What are all the things I can do with this application?</quote></para> +</listitem> +</varlistentry> +<varlistentry> +<term>User Guide</term> +<listitem> +<para>A much higher level overview of &tde; and its applications. This +aims to be the first stop for users to look for information, and should +be task based.</para> +<para>When writing for the User Guide, you should assume a working +default installation of &tde;, and you do not need to cover all cases of +unusual configurations, only the very common variations, nor should you +cover in-depth troubleshooting. You might provide answers to some very +common configuration errors (or not, as appropriate) and refer to the +Application Manual, the Application's Website, mailing list, and any +appropriate man pages for more detailed information.</para> +<para>Most people reading this guide do not have an actual problem, they +simply want to achieve a goal, and don't yet know how, or where to find +that information.</para> +<para>The User Guide should be answering the question: <quote>How do I +do <replaceable>this common task, ⪚ 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.kde.org</title> +<para>Note how we use b.k.o (general to-do items). Also point to Carlos' +guide on quality.k.o</para> + +<para>The &tde; bug tracking system, located at <ulink +url="http://bugs.kde.org">http://bugs.kde.org</ulink>, is now part of +the documentation team's toolkit. Issues with the &tde; documentation +can be filed in the <quote>docs</quote> +product of the bug tracker. Incorrect or outdated content, missing +content, outdated screenshots and typos are all appropriate reasons to +file bugs.</para> + +<para>When filing bugs, especially for incorrect or outdated content, be +specific about what's wrong. For example, if a certain page of a +configuration dialog is incorrectly documented, say which page it is in +the bug report. That way, someone fixing the bug can quickly find the +appropriate part of the application and the documentation, and make the +necessary changes with a minimum of effort.</para> + +<para>For more information on using the &tde; bug tracking system, see +<ulink +url="http://quality.kde.org/develop/howto/howtobugs.php">http://quality.kde.org/develop/howto/howtobugs.php</ulink>.</para> + +</sect1> + +</chapter> + +<chapter id="other-tasks"> +<title>Leveraging your Newly Acquired Knowledge</title> + +<para> After finishing documenting an application, +you can leverage the knowledge you gained in the process and improve +the application's level of quality in other areas. The Quality Team provide +guides on how to perform many of these tasks.</para> + +<para><itemizedlist> +<listitem><para><ulink url="http://quality.kde.org/develop/howto/howtodocs.php"> +Writing context help and configuration descriptions</ulink>: the handbook +is not the only source of help available for &tde; applications. Context help, +or <emphasis>whatsthis</emphasis> provides invaluable support for users, and +you will find it easy to write, especially after writing the handbook. +Documenting configuration options available through the KConfig framework may +require additional research, but configuration descriptions are often the only +documentation available for configuration options. +<!-- FIXME: Improve wording --> +</para> +</listitem> +<listitem><para><ulink url="http://quality.kde.org/develop/howto/howtoui.php"> +Performing usability analysis and tests</ulink>: to document your applications, +you probably tested most of the application functionality in a systematic way. +Please take the time read the guide and report the usability issues and +suggestions that appeared in the process.</para> +</listitem> +<listitem><para><ulink url="http://quality.kde.org/develop/howto/howtopromo.php"> +Writing guides and articles about the application</ulink>: promotion is the key +for a successful open source project, as widespread use means +usually more probability of attracting prospect contributors, developers, +documenters, translators, &etc;. +</para></listitem> +</itemizedlist> +</para> + +</chapter> + +<chapter id="credits"> +<title>Credits and License</title> +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +</chapter> + +<appendix id="widget-names"> +<title>Widget Names</title> +<para>Steal from (and extend) the <quote>Visual Guide to +&tde;</quote>.</para> + +</appendix> + + + + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: xml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +fill-column:72 +End: + +vim:tabstop=2:shiftwidth=2:expandtab +--> diff --git a/doc/tutorials/docprimer/kate-plugin.png b/doc/tutorials/docprimer/kate-plugin.png Binary files differnew file mode 100644 index 0000000..8633ffe --- /dev/null +++ b/doc/tutorials/docprimer/kate-plugin.png diff --git a/doc/tutorials/docprimer/kate-validate-xml.png b/doc/tutorials/docprimer/kate-validate-xml.png Binary files differnew file mode 100644 index 0000000..5d4e17b --- /dev/null +++ b/doc/tutorials/docprimer/kate-validate-xml.png diff --git a/doc/tutorials/docprimer/quanta-doc-primer.png b/doc/tutorials/docprimer/quanta-doc-primer.png Binary files differnew file mode 100644 index 0000000..b30f874 --- /dev/null +++ b/doc/tutorials/docprimer/quanta-doc-primer.png diff --git a/doc/tutorials/docprimer/quanta-doc-structure.png b/doc/tutorials/docprimer/quanta-doc-structure.png Binary files differnew file mode 100644 index 0000000..c8bd3bb --- /dev/null +++ b/doc/tutorials/docprimer/quanta-doc-structure.png diff --git a/doc/tutorials/docprimer/quanta-entities.png b/doc/tutorials/docprimer/quanta-entities.png Binary files differnew file mode 100644 index 0000000..dc2a4a9 --- /dev/null +++ b/doc/tutorials/docprimer/quanta-entities.png diff --git a/doc/tutorials/docprimer/quanta-tag.png b/doc/tutorials/docprimer/quanta-tag.png Binary files differnew file mode 100644 index 0000000..436692e --- /dev/null +++ b/doc/tutorials/docprimer/quanta-tag.png diff --git a/doc/tutorials/docprimer/quanta-toolbars.png b/doc/tutorials/docprimer/quanta-toolbars.png Binary files differnew file mode 100644 index 0000000..d34a759 --- /dev/null +++ b/doc/tutorials/docprimer/quanta-toolbars.png diff --git a/doc/tutorials/docprimer/quanta.png b/doc/tutorials/docprimer/quanta.png Binary files differnew file mode 100644 index 0000000..6dfb9aa --- /dev/null +++ b/doc/tutorials/docprimer/quanta.png diff --git a/doc/tutorials/docprimer/xmlval.png b/doc/tutorials/docprimer/xmlval.png Binary files differnew file mode 100644 index 0000000..180729f --- /dev/null +++ b/doc/tutorials/docprimer/xmlval.png diff --git a/doc/tutorials/docprimer/xsltproc.png b/doc/tutorials/docprimer/xsltproc.png Binary files differnew file mode 100644 index 0000000..54de744 --- /dev/null +++ b/doc/tutorials/docprimer/xsltproc.png |
