Chapter 4. Writing Documentation

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 do have some tools we use and procedures we follow, it's not vital that everyone knows them in detail, especially when starting out.

For example, all KDE 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.

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.

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 CVS, you will be able to integrate yourself to the regular KDE development process (upload your changes, work toogether with other developers, etc..

Getting the Documentation Sources

Note

If you are starting your document from scratch, you probably do not need to read this section, and may start working right now.

You are welcome to use plain text to contribute to KDE 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 KDE CVS, 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 CVS later in this document, so if you're interested, read on, but if you want to use plain text, you can go directly to the section called “Working with plain text sources”.

Documentation for KDE, like the rest of the source code, is kept in a CVS repository. CVS (Concurrent Versions System) 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.

The basic principle behind CVS is simple: one server stores a definitive copy of the files making up a project. This is known as the repository. Each developer can download the files to make their own private copy, named working copy or sandbox. Using CVS, 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.

There are two main ways edit the contents of a KDE document you want to improve: using plain text or DocBook.

Working with plain text sources

The docs.kde.org website displays most of the KDE documentation in HTML format, updated daily from CVS. There are two versions available in the website: the stable version and the KDE from CVS version. You will always use the latest version of the documentation, i.e. the KDE from CVS version.

The docs.kde.org website presents a quick and easy method of retrieving the latest version of the KDE 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 KDE Documentation mailing list, <kde-doc-english@kde.org>. Please note that not all KDE 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 KDE Documentation mailing list.

Now you know everything you need to start working. When you are finished writing, you may want to read Chapter 7. Have fun!

Retrieving the DocBook sources

The latest DocBook sources are located inside the KDE repository. Now you need to find and retrieve them.

The software inside the KDE repository is divided in modules, which are used to organize the different software projects inside the repository. Modules are the top folders in the CVS repository folder tree, and each one contain a group of related applications. These modules are sometimes released in binary form as packages. 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 kdepim module, Quanta in the kdewebdev module, Cervisia in the kdesdk 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.

To access the repository, you can use the CVS command line application, the Cervisia application, or browse the KDE WebCVS website (webcvs.kde.org).

The webcvs.kde.org is web based representation of the contents of the CVS repository. It is easy to download files using webcvs.kde.org, the operational system or desktop you use does not matter.

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 KDE CVS 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 CVS or Cervisia, the easiest way we can. You can get more information about these tools (they are really useful) reading the the section called “Managing CVS”.

Procedure 4.1. Retrieving documentation sources using WebCVS

  1. Go to http://webcvs.kde.org using your favorite web browser. Let's suppose you are looking for Cervisia's documentation sources.

  2. Cervisia is part of the kdesdk module (KDE software development kit module). Therefore, click the "kdesdk" item on the list. The contents of the kdesdk module will be displayed.

  3. Click the "doc" 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.

  4. Select the application you want to work with from the list (in our case, "cervisia"). All Cervisia's documentation source files will be displayed, being images or DocBook files.

  5. 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 *.docbook. In this case, there is only one file file in this format: index.docbook. Click this file on the list. A list of revisions (versions) of that file will be displayed.

  6. Click the "download" 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.

We use KMail's documentation sources as example in the following procedures.

Procedure 4.2. Retrieving documentation sources using CVS

  1. Check if you have CVS installed (hint: enter cvs -v in the terminal screen). If not, install the cvs package using the tools provided by your distribution.

  2. The .cvsrc file contains the default options for the various cvs commands. Start your favorite text editor, type the text below and save it as .cvsrc in your home folder.:

    cvs -z4 -q
    diff -u3 -p
    update -dP
    checkout -P
    

  3. CVS looks for the CVSROOT environment variable to locate the repository. To set up this variable to the KDE Anonymous CVS repository location, type on the terminal screen:

    export CVSROOT=:pserver:anonymous@anoncvs.kde.org:/home/kde
    Now, you have to log in. Type:
    cvs login
    When asked for a password, just press enter.

  4. Now it is time to download, or checkout the sources. Using CVS, type in the terminal:

    mkdir path/to/working/folder
    cd path/to/working/folder
    cvs checkout module/doc/application
    
    where path/to/working/folder is the folder you want to install the sources in your system, module is the application's module name and application is the application name. remember to use small caps to type the application and module names. In our example, KMail is in the kdepim module, so you would enter:
    cvs checkout kdepim/doc/kmail
    

Procedure 4.3. Retrieving documentation sources using Cervisia

  1. Check if you have the CVS and kdesdk Cervisia applications installed. If not, install the cvs and kdesdk packages using the tools provided by your distribution.

  2. 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 the section called “Managing CVS”.

  3. To store the repository location using Cervisia, choose the Repository->Repositories... menu item. Click the Add... button. Enter ":pserver:anonymous@anoncvs.kde.org:/home/kde" in the Repository: edit box. Press OK. You will see the repository you just entered on the repositories list.

    Figure 4.1. A screenshot of Cervisia's Configure Access to Repositories dialog


    A screenshot of Cervisia's Configure Access to
Repositories dialog

    Now you need to login. Select the repository on the list and press the Login... button. A pop-up dialog will appear. Just press enter.

    If the Status column entry shows Logged in instead of Not logged in, it means you successfully configured the KDE repository location in Cervisia.

  4. Now it is time to download, or checkout the sources. Choose the Repository->Checkout... menu item.

    Figure 4.2. A screenshot of Cervisia's Checkout dialog


    A screenshot of Cervisia's Checkout dialog

    Select the KDE repository location in the Repository: drop down box. Enter in the Module: edit box the location of the documentation sources, in the form "module/doc/application", where module is the application's module name and application is the application name. In our example, since KMail is in the kdepim module, you should enter "kdepim/doc/kmail". Enter in the Working folder: edit box the folder under which the sources should be downloaded. Press OK.