3 ms·
I'd also recommend people to make use of reStructuredText for documentation. Also it is actually possible to write something like a thesis or scientific researc
by zelphirkalt 7y ago
I'd also recommend people to make use of reStructuredText for documentation. Also it is actually possible to write something like a thesis or scientific research in it, where you might need arbitrary linking powers, which you simply don't have in Markdown. This can also be important for technical documentation. Furthermore you can add custom roles, like I did for my personal wiki implementation, to link to other pages, which are actually other reStructuredText files.
The downside of reStructuredText is, that there are almost no libraries in other languages than Python, which can transform it into HTML for the web. The canonical parser is a custom parser, without grammar and lots of states, which is unfortunate, because if there was a grammar, it could easily be implemented in other languages and the format might be much more used. But perhaps it would not be as extensible then?
Another, but quite minor, downside is, that it is a little bit harder to learn than Markdown.
Perhaps I can suggest Emacs Org-mode? The downside is, that it's only available to the extend in Emacs and other implementations are lacking many things.
Anyway, I wrote a thesis in reStructuredText and used Pandoc + custom preprocessing for document internal linking to generate the final PDF version and once I had it set up, it worked great.