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
_______________________________________________
Xfce-i18n mailing list
[email protected]
http://foo-projects.org/mailman/listinfo/xfce-i18n
