3 ms·
Neither is any good for technical docs, Asciidoc/Asciidoctor is by far the best. You get automatic numbering, conditional includes i.e you can pull in specific
by type0 10y ago
Neither is any good for technical docs, Asciidoc/Asciidoctor is by far the best. You get automatic numbering, conditional includes i.e you can pull in specific pieces of code into your docs when you tag them. Look it up, it's extremely powerful and as easy to write as reST if not easier because it's more consistent.
- david38 10y agoI just read some articles on why Linux went from asciidoc to RST. Interesting read.
- detaro 10y agoLinks?
- type0 10y agoI guess you meant this - https://lwn.net/Articles/692704/ https://lwn.net/Articles/692704/ "When comparing the markup formats for the purposes of kernel documentation, only the table support, which is much needed for the media subsystem documentation in particular, was clearly identified as being superior in AsciiDoc. Otherwise, the markup comparison was rather dispassionate; it really boiled down to the tools themselves... ... In the kernel tree, there are no tools written in Ruby, but there are plenty of tools written in Python. It was fairly easy to lean towards Sphinx in this regard." As I read it, Asciidoctor is still superior, but their decision was to go with something written in Python that they could adapt for these specific needs.