[Qgis-community-team] User guide patch

[Richard Duivenvoorde]

Anne Ghisla wrote:
> some time ago we thought of creating a HTML version of the manual with
> user comments to each section, like PostgreSQL's manual:
> 
> http://www.postgresql.org/docs/9.0/interactive/index.html
> 
> we are still looking on how to implement it, ideas welcome!

Hi Anne et al.

(I hope this is not all old news....)

I really do like the kind of documentation in which users can comment
(though I'm afraid for spammers too :-( )

Beside this I like the idea of an easy writable/translatable docs.

Myself I downloaded a one file python script
(http://asynchronous.org/rstiki/ NOT for production) which makes it
possible to write docs in Restructured Text
(http://docutils.sourceforge.net/rst.html)

Using this very simple 'markup' there are in linux several tools to
translate this to html (for a site), and odt (for a paper manual). Both
versions are stylable (html via css, odt via a template doc). see
http://docutils.sourceforge.net/ or look for rst2* commands:
rst2html            rst2newlatex        rst2odt_prepstyles  rst2s5

rst2latex           rst2odt             rst2pseudoxml       rst2xml

I'm aware of the fact that it is (again) a new format, but it is so
simple that it would also make docs easier translatable (just an svn
diff on the old english version will show all changes).

It is the markup for Python docs and eg OpenLayers, but there they use
Sphinx (http://sphinx.pocoo.org/) an even more advanced use of rst.
Trac has a plugin for it: http://trac.edgewall.org/wiki/WikiRestructuredText

It does not have all the possibilities of latex of other high end
doc-writers, but because the source is so easy we could have a look at
it if it is usable.

My ideal:
- writing the docs on your local filesystem
- commiting would trigger some process which would putthe docs online
- those doc would then be incorporated in some kind of cms (so users can
make comments on it).


Regards,

Richard Duivenvoorde