History

Latex structure and style

The structure of the latex sources of the english master document and therefore also in the translation branches is quite simple. The file user_guide.tex includes a list of *.tex files that will be included when you build the manual. All these *.tex files, mostly referring to different sections of the manual, are stored on that same level (except the appendicies). Then there are subfolders, usually named after sections as well, with images. They are organized as described below:

# GUI icons for the core of QGIS appear in the folder "images" 
/images

# GUI icons for every plugin have its own folder
/plugins_decorations_images
/plugins_geoprocessing_images
...

# Every latex file (.tex) has its own folder for screenshots
/working_with_raster_screenies
/working_with_projections_screenies
...

Important note, if you intend to update or add image: All screenshots should go in one of these screenies folders and not be mixed with the images folders with the icons! This is very important, because otherwise it will be difficult to update the GUI icons for future releases automatically.

Other files you usually (at least in the beginning) don't have to care about a lot is the latex style file (qgis_style.sty) and the two files for literature and weblink citations (cited_lit.bib and cited_weblinks.bib). All other files are necessary but have to be there, but usually you don't have to care about it :-).

# Example
# Latex structure in trunk/english_us/user_guide/
- user_guide.tex||
- cited_lit.bib||
- cited_weblinks.bib||
- qgis_style.sty||
- working_with_ogc.tex||
- grass_integration_screenies||
|   |-- add_grass_raster.png|
- appendices||
|   |-- gpl.tex|
|   |-- qgis_qt_gpl_exception.tex|
...

If you are not yet familiar with Latex and/or SVN, you can write to the qgis-community-team mailing list to get help. The main task for the manual team lead is to manage the manual efforts. This means, you try to recruit volunteers to split the work and overview what has to be done for upcoming releases.

How to download a local copy of the manual

This wiki page gives hints for working with subversion and latex under MS Windows, GNU/Linux and Mac, to be able to edit and translate QGIS documentation.

For Windows User

Working with Subversion (SVN)

Tortoise SVN is a SVN-client for Windows. The installation is simple, but you probably need to reboot. Then with a right-mouse click on the desktop you can select SVN checkout and enter the repository URL and checkout dir where to put the sources on your PC.

 checkout URL for whole doc repository:
 svn co https://svn.osgeo.org/qgis/docs/

With 'right mouse click -> TortoiseSVN' inside the user_guide folder (e.g. \xxx\User\Desktop\qgis-docs\user_guide\) you have all subversion tools available such as commit, check for modifications etc.

For Linux User

Working with Subversion (SVN)

All common linux distributions provide subversion. So all you need to start with is install the software and then check out the latex sources:

  • checkout the documentation you want to work with as a named user with write access or 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:
  • change into the downloaded folder in your current directory and start working with your favorite text editor:
  • 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:
 # Example:
 # 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/

 # If you already have a local copy of the trunk on your PC, just update the content
 svn up

 # Commit your changes to the repository with some comments what you did 
 svn commit -m 'a short summary of your changes'

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

For Mac OS User

Working with Subversion (SVN)

Working with Latex

Installing TexLive 2009

Since 1.5, the QGIS manual use PDFLaTeX to produce the PDF. It is advised to now use the TeXLive 2009 or later distribution as it is multiplateform and well-maintained.

If you already have another latex environment, please make a full uninstall (textex is deprecated) and download these installers :
  • Linux & Windows Go to the Texlive website and download the file corresponding to your OS then read the installation guide (Windows Linux).
  • MacOS X Go on MacTeX and download the *.mpkg file, double-click to install.

For all, the best choice is to select the full scheme to be sure to have all the packages needed (it will takes 2Go). If you have chosen a more restrictive set of packages, you can always install those needed using the TexLive Manager.

Note for Windows users:

Avoid MikeTex, the current distribution doesn't contains some packages and ships some deprecated ones.

Note for Linux users:

Only Debian and Fedora packages have been tested so far, most distributions are still shipping TexLive 2007. If so, please install TexLive 2009.

There is a plenty of LaTeX's editors (kile, texmaker, vim, etc.), this distribution comes with TeXworks which will be enough for most of your editing needs.

Note for Debian users:
On Debian testing (and possibly other platforms), if you get this error while compiling:

\usepackage[style=authoryear]{biblatex} (line 99, qgis_style.tex) 
! LaTeX Error: File `biblatex.sty' not found.

means that package biblatex is not installed. Upgrading texlive from 2007 to 2009 missed that dependency on my machine and required a manual install.

It is also recommended to remove tetex installs as they can conflict with texlive.

Building the PDF

  • using TeXworks :
    :#once you've launch this software, open the user_guide.tex, then select pdflatex in the drop-down list placed in in the top-left corner and click on the green arrow.
    :#on the first try, it will be asked to build the bibtex's file. To do so, open user_guide.aux, select BibTex in the dropdown list and click on the green button
    :#now redo the first step to get the final PDF with the correct bibliography
  • using the command line :
    cd ~/user_guide
pdflatex user_guide.tex
bibtex user_guide.aux
pdflatex user_guide.tex

If you open a .tex file and the user_guide.pdf exists, TeXwork will open them side by side so a click on one will move the other at the same position (great to correct typos).

How to organize your chapter hierarchically

  • chapter - Features at a Glance
    • section - Rendering
      • subsection - Controlling Map Rendering
        • minisec - a) Suspending Rendering

How to add a figure

\begin{figure}[ht]
<pre>
   \centering
   \includegraphics[clip=true, width=10cm]{proxy-settings}
   \caption{Proxy-settings in \qg \nixcaption}
   \label{fig:proxy-settings}
 \end{figure}
</pre>
  • just put the name and not the filetype extension
  • always put the caption after the \includegraphics
  • change \unixcaption to \wincaption or \osxcaption according to the OS pictured in the capture

To use subfigures (1.a/1.b) please use the subfloat command as below :

\begin{figure}[ht]
\centering
<pre>
   \subfloat[Measure lines] 
       {\label{subfig:measure_line}\includegraphics[clip=true, width=0.3\textwidth]{measure_line}}
     \hspace{1cm} % change this space if needed
   \subfloat[Measure areas]
       {\label{subfig:measure_area}\includegraphics[clip=true, width=0.3\textwidth]{measure_area}}
   \caption{Measure tools in action \nixcaption} \label{fig:measure} 
</pre>
\end{figure}

How to add a tip

\begin{Tip}\caption{\textsc{here be tip's title, matey !}}
Your Text
\end{Tip}

How to write

QGIS is using the UTF8 encoding table so you can use many of the complex or foreign symbols without typing things like \~a (ã). Most of the files are using a indentation of 72 character, if you're making a new file you don't have to do the same. Most of the editor are able to handle automatic line return (even Notepad).

How to add a new chapter

The manual keeps growing and then necessitate new chapters so if you need to create a new one :
:#create the new_chapter.tex with % !TeX root = user_guide.tex at the first line
:#add it at the releving position in the list in user_guide.tex by adding a new line called \input{new_chapter}
:#add the screenshots' folder in qgis_style.sty below \graphicspath

How to add a new icon

Copy the PNG file into the "images" folder.