4.6 documentation: xml2po

[Mike Massonnet]

Hi,

I'll try to give my thoughts on this topic, as documentation is
something I am working on currently. In fact I'm integrating a docbook
+ po-doc just like thunar, terminal, xfce4-panel, xfdesktop, etc.

First off, it is more interesting to provide the workflow that exists
currently and that will going to happen with the wiki. There exists
little documentation about the current workflow that is summarized on
the i18n wiki[0].

[0] http://i18n.xfce.org/wiki/translation_guidance_in_xfce#13._documentation_translation

What is really important is to provide documentation with the
application, not to have online documentation. What I see that can be
useful, is to let the documentation getting completed online and
export it to docbook syntax to include it inside the software and run
the xml2po makefile rule so that translators have po files.

2009/2/14 Nick Schermer <nickschermer at gmail.com>:
> 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).

Bad. At least it is a start, and the things that don't work should be
ignored. Then fixed.

>  - Translators: not easy to track changes in the C version of the docbook.

Please no, don't let translations take place on the wiki. Po template
is the right thing to use for translators.

>  - Devs: another wiki, moinmoin can generate docbooks, but only ugly
> format, if we write our own parser we have the maintain it.

That's the hard part then.

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

Instead of the cronjob, use a hook. And it is a nice idea. Writing
docbooks is not hard once you know it... you don't have to start from
scratch, instead you use a good template. We should just make our own
manual template. There is a good GNOME template[1].

[1] http://developer.gnome.org/projects/gdp/templates/gnome-app-template.xml

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

The little part that is tricky is to take screenshots in the
translators locale which are usually available under the images
directory of the C docbook, and not with the po files. The
documentation maintainer (usually the dev or the i18n main committer
e.g. Maximilian) will then have to copy the images.
Other thing is, you can update the po files from the docbook files,
and also update the docbook files from the po files. When this is
written down inside a workflow, it is not complicated to understand
what the translator,  the developper, or the documentation maintainer
has to do.

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

Not meh... if only what you wish is to get lost from the docbook then
there is something wrong. We want to provide documentation with the
application, and I don't know anything better than docbook, which has
proven to be a really good option.

>  - Devs: Needs some automake magic, but not a lot.

GNOME has a common way of doing this, by including a makefile from the
gnome-doc-utils in the top source directory and writing a simple
Makefile.am script with what matters for the manual. Check out this
HowTo[2].
What we do is to write a Makefile.am script based on what currently
exists in the current documentations that use docbook + po-doc.
Usually all that is needed is to copy the Makefile.am file with the
xml2po rules written by Daichi to our application that can be found in
the Thunar manual for instance.

[2] http://people.igalia.com/mrego/mswl/ils/how_to_write_a_manual_for_a_gnome_application_with_docbook.html#preparing_the_source_code

>  - Xml2po is shipped with gnome-doc-utils. Not a big dep tho.

Absolutely not a problem.

> So, any thoughts?

Here is a useful link for documentation writers:
http://library.gnome.org/devel/gdp-style-guide/stable/ and I except
anyone who wants to write good documentation to read it.

Don't forget about the maintaince of the wiki + the plugins, and that
there will be a lot of things to test and fix.

It would be good to give the workflow.

It would be good to write down a "howto implement docbook inside your
application" in the wiki.

I think it is wrong to think "wiki only" or "docbooks only", instead
the wiki should aid to see the documentation getting updated more
often and import a docbook out of it inside the application.

Cheers
Mike