Documentation proposal

[Nick Schermer]

2009/5/4 Jannis Pohlmann <jannis at xfce.org>:
> On Mon, 4 May 2009 10:49:07 +0200
> Nick Schermer <nickschermer at gmail.com> wrote:
>
>> 2009/5/4 Jannis Pohlmann <jannis at xfce.org>:
>> > I'm against too complex hooks. I also have the feeling that the good
>> > old gettext translation method is not really suited for continuous
>> > text. IMHO the little syntax overhead you have with reST makes .po
>> > files almost pointless.
>>
>> The point is tracking changes. The advantage of po files it will
>> result in fuzzy or untranslated strings, for separate files you have
>> to compare it with the original version. The syntax overhead is not
>> the point, keeping in sync is.
>
> I've just read Mike's mail on xfce-i18n. If translators feel that
> they are more comfortable with rst2xml + xml2po + xml2rst rather than
> translating the docs by creating a copy of the original english docs,
> that's fine with me. I'm not (really) a translator so I'm not in the
> position to make this decision - translators should decide here.

>From this point I think we make it too complicated. Why not put all
the docs in 1 git module, use docbook + xml2po for translations
(translations also in the docs module) and hooks or submodules to link
the docs to the core modules.
We could provide some extra scripts in the docs module to make this
easier and automate some stuff.

reST simply does not quite suit our needs IMHO, we could use it and
work around all the problems, but that will result in more
maintenance. Docbook is a bit rough on the edges, but it works fine
(proven concept) and there are a lot of (good) tools for translators
and developers.

Nick