Discussions about configuration, compilation or installation of Xenomai, as well as common usage of its features and interfaces. ()

Gilles Chanteperdrix | 11 Aug 2012 09:46

Using asciidoc for README.INSTALL


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.

(Continue reading)

Philippe Gerum | 11 Aug 2012 10:07

Re: Using asciidoc for README.INSTALL

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.

(Continue reading)

Gilles Chanteperdrix | 11 Aug 2012 10:54

Re: Using asciidoc for README.INSTALL

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

(Continue reading)

Gilles Chanteperdrix | 11 Aug 2012 10:54

Re: Using asciidoc for README.INSTALL

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

(Continue reading)

Philippe Gerum | 11 Aug 2012 10:07

Re: Using asciidoc for README.INSTALL

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.

(Continue reading)

Daniele Nicolodi | 13 Aug 2012 00:09

Re: Using asciidoc for README.INSTALL

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

Gilles Chanteperdrix | 13 Aug 2012 00:56

Re: Using asciidoc for README.INSTALL

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"

(Continue reading)

Daniele Nicolodi | 13 Aug 2012 01:08

Re: Using asciidoc for README.INSTALL

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

Gilles Chanteperdrix | 13 Aug 2012 01:51

Re: Using asciidoc for README.INSTALL

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

(Continue reading)

Gilles Chanteperdrix | 13 Aug 2012 01:51

Re: Using asciidoc for README.INSTALL

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

(Continue reading)

Daniele Nicolodi | 13 Aug 2012 01:08

Re: Using asciidoc for README.INSTALL

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

Gilles Chanteperdrix | 13 Aug 2012 00:56

Re: Using asciidoc for README.INSTALL

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"

(Continue reading)

Daniele Nicolodi | 13 Aug 2012 00:09

Re: Using asciidoc for README.INSTALL

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

Gilles Chanteperdrix | 16 Aug 2012 22:51

Re: Using asciidoc for README.INSTALL

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.

(Continue reading)

Gilles Chanteperdrix | 16 Aug 2012 22:51

Re: Using asciidoc for README.INSTALL

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.

(Continue reading)

Gilles Chanteperdrix | 20 Aug 2012 23:00

Re: Using asciidoc for README.INSTALL

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

(Continue reading)

Gilles Chanteperdrix | 20 Aug 2012 23:00

Re: Using asciidoc for README.INSTALL

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

(Continue reading)

Return

Return to gmane.linux.real-time.xenomai.users.

Advertisement

Project Web Page

Discussions about configuration, compilation or installation of Xenomai, as well as common usage of its features and interfaces. ()

Search Archive

Language

Change language

Options

Current view: Threads only / Showing only 20 lines / Not hiding cited text.
Change to All messages, whole messages, or hide cited text.

Post a message
NNTP Newsgroup
Classic Gmane web interface
XML

XML

RSS Feed
List Information

About Gmane