Documentation proposal

[Nick Schermer]

2009/5/4 Jannis Pohlmann <jannis at xfce.org>:
> On Mon, 4 May 2009 08:39:56 +0200
> Nick Schermer <nickschermer at gmail.com> wrote:
>
>> 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.
>
> GUI docs? I don't think we need anything GUI-specific here. And if we
> ever should, we can still write our own little Sphinx extension for
> special GUI-related markup.

Well we use stuff like this:
<menuchoice><guimenu>View</guimenu><guimenuitem>View as Detailed
List</guimenuitem></menuchoice>

and <guilabel>Open With</guilabel>

Which results in special markup when generating html.

Nick