Documentation proposal

Jannis Pohlmann jannis at
Tue May 5 11:49:17 CEST 2009

On Tue, 05 May 2009 08:40:59 +0200
Yves-Alexis Perez <corsac at> wrote:

> (sorry for dual answer)
> On mar, 2009-05-05 at 00:37 +0200, Jannis Pohlmann wrote:
> > Both, AsciiDoc and reST are relatively simple and easy to learn.
> > That's why I think the "requires you too look up markup definition"
> > part is not really important here. If you need a reference card,
> > here's one for reST:
> >
> Here's the one for asciidoc:
> (seems to lag at the moment)
> > 
> > That leaves us with less typing and better-to-read sources of reST. 
> Hmhm, is pretty
> readable to me.

So is I guess it
boils down to personal taste in the end. 

> > Another important aspect is the generated HTML. Sphinx includes a
> > template system, and its output includes features such as search,
> > view reST sources etc. Especially the template and design stuff
> > doesn't have to be copied for each language, it could reside in a
> > global source directory. It's very flexible and powerful and I
> > really like it.
> Templates for the various backends are in /etc/asciidoc or .asciidoc
> or the current folder. I think you can choose the config file from
> command line. You have some common options for all backends and some
> specific configurations files. All in all I found it really easy to
> use and tune.

I still have the feeling that Sphinx/reST is a bit more powerful and
flexible, especially wrt to the generated HTML website. It creates
navigation elements, a search index.

But AsciiDoc also ships the features we need: cross-referencing,
including AsciiDoc files into other AsciiDoc files and so on. 

> In fact, the only real drawback I (in my day to day use) find in
> asciidoc is the tables. It changed recently so it's now really
> powerful, but it might be a little complicated. I don't really know
> about reST tables though.

  - Jannis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <>

More information about the Xfce4-dev mailing list