Re: [Xenomai] Using asciidoc for README.INSTALL

[Daniele Nicolodi <daniele@grinta.net>]

On 13/08/2012 00:56, Gilles Chanteperdrix wrote:
> Since my aim is to generate html, I am comparing the html versions of
> the user documentations of the two projects, each made with its own tool:
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
> http://www.methods.co.nz/asciidoc/userguide.html
> 
> Maybe reStructuredText is good for python documentation, but apparently
> not for generating good looking html (let alone the fact that the
> document describing reStructuredText syntax is called "specification",
> not "user guide").

I'm sure you know that how HTML looks like depends mostly on the applied
CSS rather than on the HTML code. The Python documentation
http://docs.python.org/ looks much better than the (oldish) docutils web
pages. The document is called "specification" because it is indeed the
specification. Other documents target the end user, the quickref for
example: http://docutils.sourceforge.net/docs/user/rst/quickref.html

However, this was not a criticism of the choice of using asciidoc, which
may be better suited to the use case. I just wonted to provide my
opinion on readability.

Cheers,
Daniele