Documentation proposal

[Jannis Pohlmann]

On Tue, 05 May 2009 08:40:59 +0200
Yves-Alexis Perez <corsac at debian.org> 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:
> > http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt.
> 
> Here's the one for asciidoc:
> 
> http://powerman.name/doc/asciidoc (seems to lag at the moment)
> 
> > 
> > That leaves us with less typing and better-to-read sources of reST. 
> 
> Hmhm, http://www.methods.co.nz/asciidoc/userguide.txt is pretty
> readable to me.

So is http://sphinx.pocoo.org/_sources/markup/inline.txt. 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.

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables

  - 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/20090505/24898dc5/attachment.pgp>