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

[Otto Dassau]

Hi,

Am Wed, 6 Jun 2012 16:33:24 +0200
schrieb Paolo Corti <pcorti at gmail.com>:

> 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?

no, looking at the wiki page, there is maybe 50 % done or in work. It would
be nice, if more people would contribute and convert from latex to rst.

> * 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

It would be important to have all these notes and howtos somewhere in the
wiki, so people understand how to work with the new documentation. Could
someone do that and update the relevant wiki pages? And Paolo could you
assist, if there are questions?

> [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/

Regards
Otto