Documentation proposal

[Nick Schermer]

2009/5/3 Jannis Pohlmann <jannis at xfce.org>:
> 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.

Previously I was thinking a separate package for docs was a good idea,
but noadays I'm more or less against this (because of the modularity
it should be possible for people to use a single component without
being bothered with the rest of the documentation).

On the other hand I can understand all the docs in a single repo are
easier to maintain, which is at this point the biggest issue. So maybe
we can put all the docs in 1 git module and we use a hook inside a
module (thunar, panel, xfwm4) to include the (translated) html when
running make dist.

> 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 breefly looked at the docs and didn't find any syntax for gui docs.
With is one of the reasons docbook is used.

Nick