[Xfce-i18n] Documentation proposal

[Mike Massonnet]

Hi Jannis,

Jannis Pohlmann wrote:
> Hey,
> 
> Jim and I are currently investigating ways to improve the user
> documentation in future releases of Xfce.

Good.

> I think we all agree that the
> current situation is far from optimal and we really *need* improvements
> here. I think we also agree that user documentation is something our
> core developers don't want to maintain themselves (IMHO we're busy
> enough already).

For the most of them they are maintained, but the overall documentation 
is left away. One thing I noted, and that I think must be done the same 
way, was in Xfpm, the Help button doesn't point to the xfpm user manual, 
but instead to the index.html file from /usr/share/xfce4/doc/. Well this 
is one thing usually done on its own desire. But jumping to...

> Last year I promised to do something about this by forming a dedicated
> documentation team. Today, I'd like to make a proposal to get this
> "operation" started. Warning: this mail contains a lot of text.

(yeah yeah, we are a little crowd doing stuff on our own mostly by 
giving our free time on free software)

> We've briefly discussed the option of a wiki-based solution but I'm
> a bit worried that exporting could become a mess. Thus, the approach I'm
> suggesting here is based on a normal repository, and not a wiki.
> 
> Furthermore, I have the feeling that per-component docs, which is what
> we have right now, are confusing and too complicated for the people
> motivated to improve our documentation. This is why my proposal is
> about creating a separate documentation package.

...That is a good idea, this way we can provide an up-to-date index 
page. Even though this can be done directly under xfce-utils, it is 
better to keep this stuff inside its own. The only downside, is that 
having docs outside the build system of the component will disallow the 
use of automatic project name, version, author name, etc (the magic .in 
files).

The current situation is not only confusing, it's also a pain in tha a** 
for the i18n maintainer to update it. By the way, @Brian, 
xfdesktop/branches/xfce_4_6 is not building because the doc/ was never 
committed, I don't have the rights to commit there. For reference, the 
uncommitted part is in bug #5259, the two latest attachments.

Anyway, do like you want to, the main goal is to provide new and updated 
documentation. I had like to hack on the CSS, or at least get it done 
like in bug #5255.

> And just like our website, the docs are a pain to translate because
> they're written in Docbook or even HTML (correct me if I'm wrong ...
> I've lost the overview myself). That's why my suggestion involves a
> powerful markup language with less syntax overhead than Docbook or
> HTML.
> 
> Ok, let's get to the point. I'm proposing that we create a new
> component to include the user guide and other user documentation (like
> application manuals, glossary, tips & tricks, ...). The name? I'd
> suggest something like xfce4-docs or xfce4-documentation. xfhelp4 is
> part of xfce-utils so I suggest we make xfce-utils depend on this new
> package. That way we make sure it's always installed together with Xfce.
> 
> Jim pointed me to reStructuredText [1] yesterday. I tried it today.
> It's very easy to use, the reST sources are very easy to read and the
> best thing is: there's a tool called Sphinx [2] which generates HTML and
> PDF from it and links different reST source files together.

I'm looking at rst right now, for the translations. And good news, I 
already found an xml2rst, which comes in handy for translations! I will 
give that a test.

The thing is simple, you update the english text, then convert it to xml 
(rst2xml.py), then run it through xml2po (update the po files). At this 
point you let the translators update the po files, when updating one, 
you run the po files through xml2po again (output xml files on top of 
the rst2xml.py generated file), and then run the generated xml files 
through xml2rst to output the rst files in their translations.

Keeping the translations with po files is the best way IMHO. You always 
end with an up-to-date manual for any translation. The tools to 
translate po files are what numerous, and translators get used to the 
one they use. They don't need to learn about a third syntax.

I'll ping back when I get something done with rst+po files.

> So my suggestion is that we create xfce4-docs (or whatever name we
> decide on) and write the documentation using Sphinx/reST. For
> translations we can create copies of the original documentation
> inside the same package, just like we do right now.
> 
> For releases we could simply build the docs and upload the HTML to our
> website. We could also consider running a cronjob for generating and
> uploading in-development docs once a day or so.

(or a hook when pushing)

> An example of how the HTML docs generated by Sphinx look like
> can be seen on [3]. The generated HTML even provides a searching
> feature based on a searchindex.js. The HTML templates and CSS can be
> modified easily.
> 
> Sphinx would be a build-time dependency and most binary distributions
> would only package the generated HTML/PDF docs anyway. Nothing to worry
> about IMHO.
> 
> I'm volunteering to set up the repository, but first I need some input
> from Jim, our core developers and the interested translators. Thoughts?
> 
> Cheers,
> Jannis
> 
> [1] http://sphinx.pocoo.org/rest.html
> [2] http://sphinx.pocoo.org/
> [3] http://docs.python.org/dev/
> 

Cheers
Mike