Documentation proposal

[Jannis Pohlmann]

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. 

  - Jannis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://mail.xfce.org/pipermail/xfce4-dev/attachments/20090504/3dc4670e/attachment.pgp>