• DocumentationWritersCorner

Note: This document is under construction.

Note: This wiki is read-only by default. This pretty much violates the intent of a wiki but was necessary to prevent further misuse of the site. If you want to contribute to the wiki, register and then send an email with your wiki name to gsherman at mrcc dot com or tim at linfiniti.com requesting write access.

Note: We prefer you to use NameSurname format for your wiki name.

Note: We suggest you subscribe (using the subscribe link near the top) to this page if you are interested in keeping up to date with changes in this document's

Introduction

These pages provide details of everything you need to know relating to the QGIS documentation effort including checking out, compiling, translating and procedural details. It is managed by the community assistant (Manual team lead) Tara Athan. If you plan to contribute to the manual or help to translate it into a foreign maybe not yet existing language and for any other related questions, please contact Tara Athan using the qgis-community-team mailing list.

Together with the stable release of QGIS Version 1.0 the english version of the Documentation for QGIS Version 1.0 was tagged on January, 3rd 2009. Latest documentation and translations are provided here QGIS Documentation. If you are intrested to translate the text you see in the QGIS user interface, please get latest information from the TranslatorsCorner.

Mailing List

A (currently low volume) mailing list is available for discussion of both, translation of the QGIS user interface and documentation (User and Installation Guide) issues. We strongly encourage anyone joining the documentation effort to join this list!

The Documentation Process

The documentation process works in the following way. In the build up to each release the master document (in english) is updated. When this document is complete and we are absolutely sure there will be no more changes to the application ('code freeze') the documentation in subversion will be tagged and branched for translation into several foreign languages. For example leading up to the release the documentation tree in SVN may look like this:

`-- trunk
    `-- english_us
        |-- install_guide
        `-- user_guide

When a code freeze is declared, we will tag the code freeze and create branches in SVN, one for each target language. e.g.

.
|-- branches
|   `-- 1.0.0
|       |-- italian
|       `-- german
|       `-- etc...
|-- tags
|   `-- 1.0.0_user_guide
|   `-- etc...

Document writers will be given write access to their branch and the translation process can commence. The table in the next section can be used to give a macro level view of how you are in the translation process. If you read on, we will explain how to get the docs from SVN in more detail.

Please note that we started this branched documentation management system as of the 0.8.0 release.

Maintainers

Document Maintainers

Note: The QGIS project is looking for people who are willing to invest some more time - even perhaps to coordinate the documentation effort. We are trying to improve our project management process and spread the load more evenly between people who each have a specific area of resposibility, so any contribution you have to make will be greately appreciated.

Please add your details to the list below. If you would like to nominate yourself as a coordinator for a language please go ahead. If more than one person nominates themselves as coordinator for the same language, please contact each other and resolve how you will manage your efforts.

Get the latest version of the QGIS Documentation

Translation Maintainers

Note: The QGIS project is looking for people who are willing to invest some more time - even perhaps to coordinate the documentation translation effort. We are trying to improve our project management process and spread the load more evenly between people who each have a specific area of resposibility, so any contribution you have to make will be greately appreciated.

Please add your details to the list below. If you would like to nominate yourself as a coordinator for a language please go ahead. If more than one person nominates themselves as coordinator for the same language, please contact each other and resolve how you will manage your efforts.

Get latest translations of the QGIS Documentation

How to become a maintainer

There are currently some restrictions to check out the QGIS documentations with write-support. If you like to add new content or for the translation of the current QGIS manual please contact Tara Athan or Otto Dassau using the qgis-community-team mailing list..

What you need to get started

Following steps are needed to get write-access to the documentation repository.

• LaTeX (tetex and tetex-extra on debian-based systems)
• convert from the image-magick-package
• subversion client

• Read more about subversion here: http://svnbook.red-bean.com/

• latest QGIS version
• program for making screenshots (xgrab | xv | ksnapshot | ...)

• some time to contribute to the manual

Further you need to decide on a username and password. You will be given access to write to the documentation trunk or translation branch for your chosen language.

Getting the latex sources

Structure of the documentation repository

The folder structure looks like this (3 levels deep):

.
|-- branches
|   `-- 0.8.0
|   `-- 0.9.1
|       |-- italian
|       `-- german
|       `-- spanish
|   `-- 1.0.0
|-- tags
    `-- 1.0.0_user_guide
    `-- 0.9.1_user_guide
    `-- 0.8.0_user_guide
    `-- ...
`-- trunk
    `-- english_us
        |-- user_guide

Checkout

Once your account has been set up you are able to check out the documentation project as a named user. For a clean checkout you need a svn-client. The following procedure is written for GNU/Linux to access to the documentation repository:

branches keeps the documentation for the releases in different languages. Currently english_uk and german are available.

# Checkout as a guest
svn co https://svn.osgeo.org/qgis/docs/branches/1.0.0/<language>
# Checkout as a named user
svn co --username <your username here> https://svn.osgeo.org/qgis/docs/branches/1.0.0/<language>

tags keeps snapshots of a given state. The english version of the user and installation guide 1.0.0 was tagged on January, 3rd 2009 and is available here:

svn co https://svn.osgeo.org/qgis/docs/tags/1.0.0_user_guide

trunk is the 'master'-document where new content goes to.

# Checkout as a guest
svn co https://svn.osgeo.org/qgis/docs/trunk/english_us/
# Checkout as a named user
svn co --username <your username here> https://svn.osgeo.org/qgis/docs/trunk/english_us/

Checking out the whole documentation repository as a guest

# Checkout out the whole documentation repository as a guest
svn co https://svn.osgeo.org/qgis/docs
# Checkout out the whole documentation repository as a named user
svn co --username <your username here> https://svn.osgeo.org/qgis/docs

Press 'p' if you are prompted to accept the ssl key from the server.

This will create the folder qgis_docs in your current working directory.

Building

To build the user_guide as a PDF-doc, change into the folder user_guide and do the following:

cd trunk/english_us/user_guide
make
make pdf

Contributing

Adding new content to the english trunk

New content should be created in the english (trunk) version first. The english version is the 'master' document. At the time of release, the english version will be frozen and used as the basis for all other languages. To add new content follow the procedure for Unix (Linux) and Windows described below. For any questions please write to the qgis-community-team mailing list.

Unix (Linux)

checkout the english documentation trunk as a named user with write access:

svn co --username <your username here> https://svn.osgeo.org/qgis/docs/trunk/english_us
change into the downloaded folder english_us in your current directory and start working with your favorite text editor:
{{{
cd /path/to/working-copy/english_us/

when finished you need to commit (upload) your changes as soon as possible to prevent that work is done twice by another person. Inside the folder english_us type:

svn commit

That's all! Before you start adding or changing further content you should update your local working copy with the latest copy of the SVN-server. This is necessary, because another person might have updated the SVN-server with his/her latest work:

cd /path/to/working-copy/english_us/
svn update

Windows

For Windows a nice SVN-client is Tortoise SVN which integrates smoothly into the windows explorer. All needed SVN-commands described above can be used inside the explorer using the context-menu. Find more information at the Support Page.

Translating the english documentation

Translating the latex sources inside the svn branches (translation areas) is pretty simple. To contribute directly you need a valid username with password and a subversion installation on your PC. You can write to the qgis-community-team mailing list. Tara Athan will help you and organize everything you need and create a translation branch for the language you want to translate the english latex files into.

Next step is to checkout (download) the latex files from the subversion repository translate the files and commit (upload) the translated files again. Follow the procedure for Unix (Linux) and Windows described below for the german translation branch of QGIS version 1.0.0:

Unix (Linux)

checkout the german translation branch as a named user with write access:

svn co --username <your username here> https://svn.osgeo.org/qgis/docs/branches/1.0.0/german/

change into the downloaded folder german in your current directory and start translating with your favorite text editor:

cd /path/to/working-copy/german/

when finished you need to commit (upload) your translations as soon as possible to prevent that translation is done twice by another person. Inside the folder german type:

svn commit

That's all! Before you start continuing your translation work you should update your local working copy with the latest copy of the SVN-server. This is necessary, because another translator might have updated the SVN-server with his/her latest work:

cd /path/to/working-copy/german/
svn update

Windows

For Windows a nice SVN-client is Tortoise SVN which integrates smoothly into the windows explorer. All needed SVN-commands described above can be used inside the explorer using the context-menu. Find more information at the Support Page.

For using LaTeX with windows it is recommended to use the MikTeX distribution located at MikTeX Page. There are also several LaTeX-Editors available for windows like Winshell TeXMaker TeXnicCenter if you like WYSIWYG editing (mostly you loose some advantages of LaTeX) you can use LaTeXEditor or for a 28day free period BaKoMa TeX

Some hints translating the latex files

• All you need to translate is the english text within the files ending with .tex (e.g. map_composer.tex).
• You don't need to adapt or change the images nor the names of the images.
• You can ignore all commands starting with \ (e.g. \section) and only translate the text inside the brackets (e.g. \section{Introduction} becomes in german \section{Einführung}).
• For figures you can also almost ignore most of the definition and only translate small parts (see the example below):

\begin{figure}[ht]
   \begin{center}
   \caption{Image of a blank Map Composer}\label{fig:map_composer_blank}\smallskip
   \includegraphics[clip=true, width=\textwidth]{map_composer_blank08}
\end{center}
\end{figure}
in german becomes:
\begin{figure}[ht]
   \begin{center}
   \caption{Bild eines leeren Map Composer}\label{fig:map_composer_blank}\smallskip
   \includegraphics[clip=true, width=\textwidth]{map_composer_blank08}
\end{center}
\end{figure}

• To check the translation you can build the latex sources simply with 'make':

For any questions you can get help from the qgis-community-team mailing list.

Procedure for new manual releases

Here you find a collection of tasks to implement before the next tagging of the documentation trunk.

User and Installation Guide (1.1):

• Update INSTALL.t2t and CODING.t2t from sources
• Changing current version to 1.1
• Adding information "whats new or enhanced in 1.1 compaired to 1.0
• Commit a pdf from the tagged user guide to qgis/doc
• Proof-reading by a native-english-speaker at the end