[Qgis-community-team] Fix for wrong PDF bookmarks and hyperlinks in QGIS User Guide manual

[Alessandro Fanna]

Hello to everybody, this is my first message to the list so please be 
patient if I'll be a little tedious...

My name is Alessandro Fanna and I'm helping (lately...) Alessandro 
Sarretta with italian translations.
During last week I spend my efforts closing v1.0.0_ita (just minor 
things) and giving an overview to the whole User Guide in order to make 
it's contents more uniform and to correct small errors spread a little 
bit everywhere. Although it wasn't as deep as I wished, it was a quite 
tough job anyway. Now we have better grounds for v.1.3.0_ita.

Coming to the point, I found quite annoying how the following PDF 
bookmarks weren't pointing to the right page, but always to the one 
bookmarked before (i.e. by clicking on the bookmark 'Preamble' you get 
the 'Title' page, same thing for hyperlinks in the 'Contents' page):

   Preamble
   Table of Contents
   List of Figures
   List of tables
   List of QGIS Tips
   Cited literature

This concerns all User Guides that I downloaded (also 
1.3.0_user_guide_en.pdf), so I started to search for the reason of this 
behaviour. I have to say that I'm new to Latex (started using it just a 
couple of weeks ago...) so I lost some time before understanding a 
little bit how things work...
Anyway, it seems it's related to the Hyperref package and this command 
that adds an entry to a specified list or table: \addcontentsline.

The fix is to add the following code just before each \addcontentsline:

   \clearpage
   \phantomsection

'\phantomsection' has to be used to get the hyperlinks (and bookmarks in 
PDF) right for index, list of files, etc, but I found that it won't work 
without adding '\clearpage' just before. So i.e. for preamble.tex the 
code should look this way:

...
\clearpage
\phantomsection
\addcontentsline{toc}{section}{Preamble}
...

These are the .tex files where the code fix is needed:

toc.tex (for 'Table of Contents', 'List of Figures', 'List of Tables' 
and 'List of QGIS Tips')
title.tex
literature.tex
preamble.tex
index.tex

About 'index.tex': when compiling the .dvi I was getting some warnings 
due to the fact that the '\index' command does't like more than three 
sublevels. I changed the four commands that were giving an error in the 
italian version of the User Guide by erasing the fourth sublevel.

Hope I was helpful...

Alessandro (rospus)

PS. In the next days Alessandro Sarretta will commit all the changes for 
1.0.0_ita, I hope to get an account too in the next future.