[Qgis-community-team] QGIS restructured text documentation: some notes on current situation

[Paolo Corti]

Hi all

Since the Lyon HF in my spare time I have been contributing to
implement the new documentation infrastructure based on rst.
Now I would like to give some quick considerations about the current situation:

* for migrating from TEX to rst someone (I think Yves) created a
script [1] that in same case, and together with the use of pandoc,
didn't correctly migrate all or part of the files. So it would have
been necessary a manual effort: Jean Roc created a wiki page [2] for
coordinating this manual effort, can we consider closed this effort?

* I have added in the project the gettext files for de, es, fr, it,
ru, js, pt languages. So from now it is possible to translate these
files in each language. As you commit the translation in gitthub it
will be possible to see the translated documentation in the qgis
documentation site (docs.qgis.org), following the links suggested in
the readme file [3]

* for offline translating the gettext files we strongly recommended to
use QtLinguist [4], but in principle you could use any gettext editor,
including text editors like vi, gedit and emacs

* if you are online you may opt to use the Pootle application,
deployed here [5]. As an anonymous user you may see the status of the
different QGIS translation efforts (for now just the QGIS user guide).
You may decide to register yourself if you are willing  to contribute.
Via the web application you will be able to submit your changes to
github clicking on the "Commit to VCS link."

* one important notice: with the gettext approach for translation, all
of the existing translations needs unluckily to be manually ported
from TEX, as there is not a possible automatic way to import them, at
least IMHO. I think we could discuss on a case by case basis if to go
with the gettext approach or with a rst translation process (like for
the CookBook). We need to consider, though, that the former can
initially take much more to be implemented, but in the future will
have definitely much better maintainability than the latter

thanks
p

[1] https://github.com/qgis/QGIS-Documentation/blob/master/latex2rst.py
[2] http://hub.qgis.org/wiki/quantum-gis/LaTeX_to_RST_migration
[3] https://github.com/qgis/QGIS-Documentation/blob/master/readme.rst
[4] http://qt-apps.org/content/show.php/Qt+Linguist+Download?content=89360
[5] http://translate.qgis.org/

-- 
Paolo Corti
Geospatial software developer
web: http://www.paolocorti.net
twitter: @capooti
skype: capooti