4.6 documentation: xml2po

Nick Schermer nickschermer at gmail.com
Sat Feb 14 13:27:24 CET 2009


The wiki approach is one way of maintaining the manuals, we can also
use xml2po to make translating the docbooks easier. It's already used
by thunar, but we haven't really discussed this. So let's do that.

First some wiki facts:

Advantages:
  - Devs: wiki docs are probably easier to maintain, more people can
work on the documentation.
  - Users: up2date docs online.

Disadvantages:
  - Devs: wiki's don't provide the full power of docbook (no
cross-references, no semantic meaning).
  - Translators: not easy to track changes in the C version of the docbook.
  - Devs: another wiki, moinmoin can generate docbooks, but only ugly
format, if we write our own parser we have the maintain it.

Xml2po:

The idea: 1 english version of the manual. Somewhere in docs/manual/C/
and we make pot and update po files in po/manual/ or po-doc/ (keep the
application and manual po files separate). Then we make a cronjob on
the server to generate html versions of the pages for online usage.

Advantages:
  - Translators: easy to maintain translated version of the docs. You
just update the po file and/or fix the fuzzy strings. For them there
is no docbook magic needed.
  - Devs: Can use the full power of docbook.
  - Users: Up2date docs (generated each day), probably resulting in
more translations too. Also additional formats possible like pdf,
single page html etc.

Disadvantages:
  - Devs: Meh, still docsbook...
  - Devs: Needs some automake magic, but not a lot.
  - Xml2po is shipped with gnome-doc-utils. Not a big dep tho.

So, any thoughts?

Nick



More information about the Xfce4-dev mailing list