Documentation proposal

[Yves-Alexis Perez]

(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.
> 
> 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.

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.

Cheers,
-- 
Yves-Alexis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
URL: <http://mail.xfce.org/pipermail/xfce4-dev/attachments/20090505/ebe2b86f/attachment.pgp>