Change README to AsciiDoc

[magicDGS]

Proposal to change the README to AsciiDoc, as it supports out-of-the-box "Table of Contents", apart of a really nice markup syntax (more consistent than Markdown).

Also, I included some changes in the content.

It also includes changes from #24:

• Badges
• Build status (including AppVeyor)

[lbergelson]

I don't have a strong feeling about this. The downside is that it seems a little more complicated then markdown, and people won't be familiar with it out of the box. It looks like it has some nice features like auto table of contents creation. I don't feel strongly either way.

[lbergelson]

I would probably put these as a single horizontal line or as part of the badge line. This table looks nice but takes up most of the vertical space.

[magicDGS]

Done

[lbergelson]

If we go with asciidoc we might want a footnote at the bottom with a link to an asciidoc quick reference guide.

[magicDGS]

We can add something like that in the contributors guidelines, that I am preparing in combination with #42 and this PR (preparing is too optimistic, I just have in mind what I will propose).

[lbergelson]

Can asciidoc generate support those interactive panes where you can have multiple tabs for different language examples? Something like the panes here

[magicDGS]

There is not built-in support for this, and I doubt that even if so the GitHub renders it properly (e.g., jekyll for gh-pages does not support very useful plugins...)

[magicDGS]

I did put them in a table form similar to the build.

[tfenne]

Sorry for the delay weighing in on this. I have to say, I'm sorry, but I'm against switching away from MarkDown. My brain is already annoyed at having to recall both MarkDown and RST syntax, and adding yet another "not-HTML" language just to get an automated TOC seems like a bad tradeoff. It also looks more complicated (to my eye) than MarkDown, but that might be lack of familiarity.

[magicDGS]

@tfenne - I understand you, as I was also against AsciiDoc now that I am using it but I found that not only the built-in TOC is a nice feature. I propose it for several reasons:

1. Have a consistent markup language. For writing technical documentation and other stuff that I am planning to add (see Add docs project for technical documentation #42 as an example), I think that Markdown is really limited: using AsciiDoc and some extensions (like the diagams) we can have even embeded UML diagrams to document how the architecture of the project looks like. Having the README in one format and the rest in other format is kind of inconsistent (similar to different formatting around the code).
2. The syntax is fixed but extensible, and there are not dialects like with Markdown. This means that in every computer, it will render (better or worse depending on the command that was used). That is not the case if you are editting Markdown without specifying that it is GitHub-flavored, for example.
3. Other features apart of the TOC might be useful in the future. By now, with this simple README, it does not look like an amazing thing to do. For example, the multi-line code for the build/test tables should be done with html in markdown (see below for more about this).
4. Using AsciiDoc avoids to use a lot of hardcoded HTML as Markdown sometimes force to do. For example, to do a subscript/superscript in Markdown you are forced to use HTML (e.g., x<sub>2</sub> to render to x₂), but in AsciiDoc it is as simple as x~2. For x², where x<sup>2</sup> is less readable for me than x^2

If you are still not convinced by this, I can give up the README. But I think that we should definetely write in AsciiDoc the technical documentation and user manual on how to use the library (and also in a way that the documentation is compiled and every test snippet is run - I have a very cool idea about this). And I would really like to have technical documentation to define a proper architecture to be able to fullfill all the requirements from other projects (e.g., see #34 and #42 for a concrete proposal designed before the implementation).

[tfenne]

Closing; in person conversation with @lbergelson - we agree to stay with MarkDown.