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

[Tim Sutton]

Hi

On Wed, Jun 6, 2012 at 6:04 PM, Otto Dassau <dassau at gbd-consult.de> wrote:
> 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?
>

Paolo and documentation team it really is an awesome job you have done
getting all this set up!

@Otto maybe we should take Paolo's document and create a TRANSLATION
document to go in the root of the code base (as we have with CODING,
INSTALL) so that the instructions arrive with the source and we can
just point people to the github hosted version of the document. Just a
thought!

Regards

Tim


>> [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
> _______________________________________________
> Qgis-community-team mailing list
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team



-- 
Tim Sutton - QGIS Project Steering Committee Member (Release  Manager)
==============================================
Visit http://linfiniti.com to find out about:
 * QGIS programming services
 * Mapserver and PostGIS based hosting plans
 * FOSS Consulting Services
Skype: timlinux Irc: timlinux on #qgis at freenode.net
==============================================