Documentation proposal

[Jannis Pohlmann]

On Mon, 4 May 2009 21:30:47 +0200
Nick Schermer <nickschermer at gmail.com> wrote:

> 2009/5/4 Yves-Alexis Perez <corsac at debian.org>:
> > On dim, 2009-05-03 at 21:31 +0200, Jannis Pohlmann wrote:
> >> 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.
> >
> > Another stuff you might want to look at (sorry I'm a bit late) is
> > asciidoc.
> 
> Looks easy, quite powerful and well maintained. I never heard of it
> before, but if we go for easy docs this is a good candidate.

Looks interesting. However, I think I'd still vote for Sphinx/reST.
It looks like AsciiDoc uses a more explicit markup language, e.g.

  link:<target>[caption>]

where reST follows a more implicit approach, e.g.

  `caption <target>`_

There are pros and cons for both. Explicit markup (Docbook is another
example of this, because tags have names and describe what they do)
helps understanding the markup itself but are not as easy to read.
Implicit markup often involves less typing, is easier to read but
sometimes requires you look up the markup definition.

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.

That leaves us with less typing and better-to-read sources of reST. 

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.

  - 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/c7a5c963/attachment.pgp>