[Xenomai] Using asciidoc for README.INSTALL

[Xenomai] Using asciidoc for README.INSTALL

[Gilles Chanteperdrix]

Hi,

currently, the installation instructions are available on xenomai
website as a plain text file. It makes sense, as we want them as a plain
text file in the release tarball, and we do not want to maintain two
separate sets of installation instructions. However, a plain text file
is not so nice to read in a web browser.

So, maybe we could use an asciidoc version. I tried to do a quick
conversion to asciidoc, and I find it looks fine:
http://xenomai.org/~gch/README.INSTALL.html
The sources however, maybe a bit less readable:
http://xenomai.org/~gch/README.INSTALL.txt
But maybe we can ask asciidoc to generate a really plain text version.

Anyone opposed to the change?

pros:
- nice online html version
- online one source file to maintain
cons:
- need to learn asciidoc syntax to maintain the doc
- a slightly less readable plain text version

Regards.

-- 
                                                                Gilles.

Re: [Xenomai] Using asciidoc for README.INSTALL

[Philippe Gerum]

On 08/11/2012 09:46 AM, Gilles Chanteperdrix wrote:
>
> Hi,
>
> currently, the installation instructions are available on xenomai
> website as a plain text file. It makes sense, as we want them as a plain
> text file in the release tarball, and we do not want to maintain two
> separate sets of installation instructions. However, a plain text file
> is not so nice to read in a web browser.
>
> So, maybe we could use an asciidoc version. I tried to do a quick
> conversion to asciidoc, and I find it looks fine:
> http://xenomai.org/~gch/README.INSTALL.html
> The sources however, maybe a bit less readable:
> http://xenomai.org/~gch/README.INSTALL.txt
> But maybe we can ask asciidoc to generate a really plain text version.
>
> Anyone opposed to the change?
>
> pros:
> - nice online html version
> - online one source file to maintain
> cons:
> - need to learn asciidoc syntax to maintain the doc
> - a slightly less readable plain text version

That's fine, let's move to asciidoc. Those who should read the doc but 
don't, won't notice any difference. Others are likely to know how to 
start a browser. I'll use the couple of brain cells I have left to learn 
a few asciidoc tags.

-- 
Philippe.

Re: [Xenomai] Using asciidoc for README.INSTALL

[Gilles Chanteperdrix]

On 08/11/2012 10:07 AM, Philippe Gerum wrote:

> On 08/11/2012 09:46 AM, Gilles Chanteperdrix wrote:
>>
>> Hi,
>>
>> currently, the installation instructions are available on xenomai
>> website as a plain text file. It makes sense, as we want them as a plain
>> text file in the release tarball, and we do not want to maintain two
>> separate sets of installation instructions. However, a plain text file
>> is not so nice to read in a web browser.
>>
>> So, maybe we could use an asciidoc version. I tried to do a quick
>> conversion to asciidoc, and I find it looks fine:
>> http://xenomai.org/~gch/README.INSTALL.html
>> The sources however, maybe a bit less readable:
>> http://xenomai.org/~gch/README.INSTALL.txt
>> But maybe we can ask asciidoc to generate a really plain text version.
>>
>> Anyone opposed to the change?
>>
>> pros:
>> - nice online html version
>> - online one source file to maintain
>> cons:
>> - need to learn asciidoc syntax to maintain the doc
>> - a slightly less readable plain text version
> 
> That's fine, let's move to asciidoc. Those who should read the doc but 
> don't, won't notice any difference. Others are likely to know how to 
> start a browser.


README.INSTALL is the 6th most downloaded file on the web site. So,
it seems people do want to read the installation instructions in their
browser.

> I'll use the couple of brain cells I have left to learn
> a few asciidoc tags.



It is really easy, much more "plain text like" than the mediawiki markup.
Asciidoc is also able to generate man pages, so, I am going to move the
manpages we have to asciidoc, taking the opportunity to update them.
Some of our manpages are outdated, and the fact that they use the nroff
format does not make them easy to update.

-- 
                                                                Gilles.

Re: [Xenomai] Using asciidoc for README.INSTALL

[Daniele Nicolodi]

On 11/08/2012 09:46, Gilles Chanteperdrix wrote:
> So, maybe we could use an asciidoc version.

> pros:
> - nice online html version
> - online one source file to maintain
> cons:
> - need to learn asciidoc syntax to maintain the doc
> - a slightly less readable plain text version

For what it is worth, I find reStructuredText [1] much more readable in
its "raw" format that asciidoc. reStructuredText is the nowadays
standard for Python documentation.

[1] http://docutils.sourceforge.net/rst.html

Cheers,
Daniele

Re: [Xenomai] Using asciidoc for README.INSTALL

[Gilles Chanteperdrix]

On 08/13/2012 12:09 AM, Daniele Nicolodi wrote:

> On 11/08/2012 09:46, Gilles Chanteperdrix wrote:
>> So, maybe we could use an asciidoc version.
> 
>> pros:
>> - nice online html version
>> - online one source file to maintain
>> cons:
>> - need to learn asciidoc syntax to maintain the doc
>> - a slightly less readable plain text version
> 
> For what it is worth, I find reStructuredText [1] much more readable in
> its "raw" format that asciidoc. reStructuredText is the nowadays
> standard for Python documentation.
> 
> [1] http://docutils.sourceforge.net/rst.html


And asciidoc is the standard for git documentation.

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"). From what I have tried, there is nothing special to
be done with asciidoc to have a nice output, the "out-of-the-box"
experience is very good.

And there is a docbook to asciidoc translator:
https://github.com/oreillymedia/docbook2asciidoc

Which may interest us as we also have some docbook code, which may be
interesting to convert to asciidoc.


-- 
                                                                Gilles.

Re: [Xenomai] Using asciidoc for README.INSTALL

[Daniele Nicolodi]

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

Re: [Xenomai] Using asciidoc for README.INSTALL

[Gilles Chanteperdrix]

On 08/13/2012 01:08 AM, Daniele Nicolodi wrote:

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


Yes, that is what I meant by "out-of-the-box" experience. I already do
not have a lot of time to spend on documentation, but when I spend time
on documentation, I want to write documentation, not fight with markup
syntax and toolchain, and even less with CSS customization (which I am
unable to do anyway). asciidoc provides a good looking CSS, apparently,
reST does not.

 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


Yes, but the primer in its "What's Next" section says: "This primer
introduces the most common features of reStructuredText, but there are a
lot more to explore. The Quick reStructuredText user reference is a good
place to go next. For complete details, the reStructuredText Markup
Specification is the place to go". So, neither the primer nor the
quickref are complete documentations, and ultimately, the only complete
documentation is a specification, not a user guide.

So, on one side, we have one project with one clearly users-oriented
documentation, and on the other side, we have another project with three
documentations, two incomplete user documentations, and a complete
documentation, but which name seems to indicate that it is not user
oriented.

Maybe I react strangely, but I prefer the first solution.


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


I did not take it as a criticism, and I had a look at ReST, but it does
not really look convincing. As for the readability, the syntax
comparison on wikipedia:
http://en.wikipedia.org/wiki/Lightweight_markup_language#Comparison_of_lightweight_markup_language_syntax

does not look to the advantage of ReST either.

*bold text*
_italic text_
Introduction
============
http://www.example.com[Link text]

vs

**bold text**
*italic text*
Section 1 Introduction
======================
`Link text <http://www.example.com/>`_
or
Linkname_
.. _Linkname: http://www.example.com

-- 
                                                                Gilles.

Re: [Xenomai] Using asciidoc for README.INSTALL

[Gilles Chanteperdrix]

On 08/11/2012 09:46 AM, Gilles Chanteperdrix wrote:

> 
> Hi,
> 
> currently, the installation instructions are available on xenomai
> website as a plain text file. It makes sense, as we want them as a plain
> text file in the release tarball, and we do not want to maintain two
> separate sets of installation instructions. However, a plain text file
> is not so nice to read in a web browser.
> 
> So, maybe we could use an asciidoc version. I tried to do a quick
> conversion to asciidoc, and I find it looks fine:
> http://xenomai.org/~gch/README.INSTALL.html
> The sources however, maybe a bit less readable:
> http://xenomai.org/~gch/README.INSTALL.txt
> But maybe we can ask asciidoc to generate a really plain text version.


Yes, we can, with some trickery to get the URLs verbatim in the plain
text output, we get
- for these sources:
http://xenomai.org/~gch/README.INSTALL.adoc
- the html version:
http://xenomai.org/~gch/README.INSTALL.html
- the plain text version:
http://xenomai.org/~gch/README.INSTALL

-- 
                                                                Gilles.

Re: [Xenomai] Using asciidoc for README.INSTALL

[Gilles Chanteperdrix]

On 08/11/2012 09:46 AM, Gilles Chanteperdrix wrote:

> 
> Hi,
> 
> currently, the installation instructions are available on xenomai
> website as a plain text file. It makes sense, as we want them as a plain
> text file in the release tarball, and we do not want to maintain two
> separate sets of installation instructions. However, a plain text file
> is not so nice to read in a web browser.
> 
> So, maybe we could use an asciidoc version. I tried to do a quick
> conversion to asciidoc, and I find it looks fine:
> http://xenomai.org/~gch/README.INSTALL.html
> The sources however, maybe a bit less readable:
> http://xenomai.org/~gch/README.INSTALL.txt
> But maybe we can ask asciidoc to generate a really plain text version.


Even before converting the man pages, I tried converting the
TROUBLESHOOTING guide, so that it is a bit more cross-linked with
README.INSTALL.

Sources here:
http://xenomai.org/~gch/TROUBLESHOOTING.adoc
Generated html:
http://xenomai.org/~gch/TROUBLESHOOTING.html
Generated plain text:
http://xenomai.org/~gch/TROUBLESHOOTING

I used the opportunity to add some content, so, feel free to proof-read
and send patches (the reference being the .adoc file).

-- 
                                                                Gilles.