A few things I don't like about AsciiDoc
Posted by matijs 11/12/2021 at 09h26
AsciiDoc is nice because a lot
is possible. However, there are a lot of surprising edge cases that make it
less great as an easy to read and write documentation format.
-
Some list markers support nesting, others do not
If you use a dash (
-) as a list marker, that works fine until you want to
create nested lists. Then, it turns out you should be using*. -
Outdenting lists has very weird syntax.
To outdent a list, you have to add a number of empty lines equal to the
number of outdents plus one, followed by an empty line with a+. This is
too specific for a human-readable format. -
Escaping only works where it is needed.
Wherever an asterisk leads to bolding, you can escape it using a
\to create a literal
asterisk. However, when the use of an asterisk does not lead to bolding, adding the\
will just lead to a literal\in the output. Predicting where this will
happen is tricky so you have to constantly look at the actual output.