I opted for Asciidoc 5 years ago and hadn’t touched ReST since. Yesterday I had a closer look into ReST and it has improved a lot! There is a proper specification now and at first glance it seems I can find everything I was missing 5 years ago. I especially like how it handles links and I decided to give ReST a second chance.
Results of my comparative tests:
In Docutils’ RestructuredText I mainly missed the same than in pure asciidoctor : good support for scientific references. The latter adds them with asciidoctor-bibtext and the first with a sphinx extension: sphinxcontrib-bibtex. Both provide live preview: Asciidoctor with browser-plugins and for reStructuredText there is restview available.
Now the differences:
As reStructuredText uses indentation as markup, the source text is much easier to read and the markup itself is less verbose! It is certainly a matter of taste, but for me just looks much better!
I will continue using reStructuredText in the future.
The best way I found so far to convert my existing Asciidoc documents to reStructuredText:
#!/bin/sh
BaseName=$(basename "$1" ".adoc")
DirName=$(dirname "$1")
XmlFileName="$DirName/$BaseName.xml"
RstFileName="$DirName/$BaseName.rst"
asciidoctor -b docbook5 "$1"
pandoc -f docbook -t rst "$XmlFileName" > "$RstFileName"
rm "$XmlFileName"
I’m very interested in markup languages (aka wiki-like syntaxes). Few years ago I’ve reviewed all of the existing syntaxes and found out AsciiDoc to be the best one for use cases more complex than simple comment on a blog. Sure, it’s not perfect, but I’m convinced that it’s better than all existing alternatives.
It’s widely used for writing technical documentation (e.g. Git, Spring projects, Fedora projects) and also books (e.g. O’Reilly Atlas publishing platform is based on AsciiDoc(tor)). The syntax is simple to understand and use (even for non-technical writers), comprehensive and extensible. Ecosystem around AsciiDoc is quite rich and mature. Asciidoctor runs on Ruby, JavaScript (very important for live preview on web) and JVM. There’s also a legacy AsciiDoc toolchain written in Python.
reStructuredText is very different… compared to anything. It’s really non-intuitive (e.g. links and references), hard to grasp and remember. In my opinion, it’s the worst wiki-like syntax ever made. Just look at some examples and compare with current version of AsciiDoc and also other syntaxes. It’s widely used more or less only in Python world.
Someone mentioned indentation, that RST is easier to read, because it’s indentation-based. It’s true that the delimited blocks in AsciiDoc currently cannot be indented. However, this might be changed (and I hope that it’ll be) and it’s only a trivial change in the syntax. Then you can (not must) indent markup as you wish, for a better readability.
It may be a problem for Rust that AsciiDoc (and even RST) toolchain needs some runtime (Ruby, JS or JVM), there’s no parser written in Rust or C. I’d like to say that I would love to write AsciiDoc parser in Rust (and I’m able to do it)!
3 Likes
A Rust asciidoc would be cool, but I think the original implementation of asciidoc (at http://www.methods.co.nz/asciidoc/) is written in C?
EDIT whoops nevermind, it's Python.
1 Like
A Rust asciidoc would be cool, but I think the original implementation of asciidoc (at http://www.methods.co.nz/asciidoc/2) is written in C?
No, it’s not, there’s currently no C implementation of AsciiDoc. Also this Python implementation is de facto deprecated and replaced by Asciidoctor.
1 Like
Having used Asciidoctor for 4 years I switched to ReStructuredText last year in October.
reStructuredText is very different… compared to anything. It’s really non-intuitive (e.g. links and references), hard to grasp and remember. In my opinion, it’s the worst wiki-like syntax ever made. Just look at some examples and compare with current version of AsciiDoc and also other syntaxes.
I mainly use Asciidoctor and ReStructuredText (with Sphinx) as a LaTex replacement to write academic articles and to take short notes.
Dealing with more complex Asciidoc documents you easily end up with a lot verbose markup whereas even complex ReSt documents remain really human readable and just elegant.
Like @jirutka it took me a moment to find out how ReSt handles references. Finally I found out this feature is the strongest upside of ReSt: it gets the URL out of the text flow and participates greatly to its readability.
What I did not like at the beginning with Sphinx was that you first have to create template directory structure using sphinx-quickstart. Then I realized that with most of my Asciidoc documents I ended up with some bash scripts describing the compilation parameters and directory structure used. Sphinx does this for you in standardized and clean way. Here again it took some time to discover how well ReSt is designed for practical use.
Since I write all my new notes in ReSt and even convert older ones I still edit from Asciidoc to ReSt.
Recently I hit on rust-rst a reStructuredText parser and renderer written in Rust. Has anybody tried it out?
2 Likes
Could you please show me few real-world examples?
It’s not that I couldn’t find out, but that I consider RST’s underscores mess insane. 
You’re comparing apples and oranges here. Asciidoctor is more or less just a converter, from AsciiDoc to other formats. It’s like docutils. Sphinx is a complex documentation generator.
Moreover, it’s quite irrelevant, because this is just about a tool. Tools can be simple improved or changed, but format cannot. The format is what really matters here.
1 Like
I have 2 files for you to compare. It is the documentation of 2 of my smaller projects: restructuredtext-notetaking and asciidoctor-notetakling.
Please compare this rst-file to this adoc-file. Their content is 99% the same, but the rst-file is much easier to read and looks more beautiful.
You accidentally used the privileged editing links for those two files. Here are the unprivileged raw links for rst-file and adoc-file.
1 Like
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.