101–110 of 124 posts
Asciidoc is a no-brainer. The TOC macro alone is a game changer. Just wish the documentation were so absolutely awful -- extremely bare and hard to find examples. Enumerated values poorly explained, if at all.
The AsciiDoc docs got an overhaul 2 years ago. I find them to be quite good.
What are enumerated values? Do you mean ordered lists?
Earlier quoted context omitted.
At least for video games, the lack of a GC dependency for the standard library made C++ more attractive than D.
I thought the GC was optional in D, was it not?
That's not an elegant solution, this is a stray markup disaster waiting to happen, and in both directions: re-wrap a paragraph (I'm doing it all the freaking time), edit some more so you can't just ctrl-z, and now you've got those plus signs sprinkled throughout your text mixed with non-special plus-signs. Manual line breaks are too infrequently used to warrant such an unconspicuous markup with such a frequently used character IMHO. It's also totally arbitrary and not backed by widespread precedent. Just use
for heavens' sake, you can at any time just copy-paste it to reduce the chore, its semantics are among the most published text markup conventions ever, and it's in most situations unique enough to be safely searched-replaced in a document without all the headscratching that /\+(?=\n)/ vs /\+(?!\n)/ entails. Plus,
is impervious to reflowing paragraphs. What's not to like?
. Foo
. Bar
. Baz
Markdown is more intuitive to understand, and the idea is that it's human readable even if not rendered.
1. Foo
2. Bar
3. Baz
I'm not a fan of using 1. for each bullet point, as that takes away from the "readable source code" paradigm. On the other hand, it avoids a change in indentation if you have ten or more items.
Earlier quoted context omitted.
In fact, both claims are misleading. There are two implementations, and they implement distinct flavors with syntactic differences: https://consolelog.gitee.io/docs-asciidoctor/asciidoc-asciid... Markdown has a smaller flavors/implementations ratio!
In fact, also this claim is wrong, because there are three :D 1. https://asciidoctor.org/ 2. https://github.com/asciidoc-py/asciidoc-py 3. https://asciidoc3.org/ 1 and 2 seem to hate 3 (see issue trackers / web sites of all three) and meanwhile probably also vice versa. The discussion was quickly dragged into the legal realm by 1 in particular, which very obviously dampened number 3's initial enthusiasm. Additionally…
Aside from the merits of Markdown and Asciidoc, Asciidoc has a name that doesn't help. Depending on the (natural) language, ASCII (the encoding, that is) annoys anything from a small percentage of users (e.g., English, Esperanto), to many people (e.g, Dutch, German, French), to almost everyone (anything that doesn't use Latin characters). In the context of a markup language intended for structuring normal text its na…
Absolutely, or at least I was also put off the name when I first heard of it. The name sounds like something that requires you to use (HTML) entities or some kind of Unicode code point syntax if you want to input non-ASCII. Blegh…
It might not occur to people in North America that even British English users are inconvenienced when restricted to ASCII only (GBP vs £) and therefore the name implies that this tool is not for us.
For the 'real' documentation, asciidoc (with include, I think not every implementation make the work) is generally the best. Because of includes especially, that the salient point makes asciidoc better than Latex (that I prefer generally for everything else).
Features like table is the ultimate conundrum - if you want beautiful text based tables like in reStructuredText it becomes very difficult to write and edit unless you use a specialized editor, while Asciidoc’s table syntax is very code-like and is completely unreadable as a tabular table (almost like a simplified HTML markup).
Markdown strikes a middle ground where it tries to be readable while being as easy to write by hand as possible. However in practice most people don’t bother to keep the columns aligned by hand so it still becomes quite unreadable, and you still need specialized editor to do align columns automatically if you want to retain readability.
You can consider it a good compromise or failing at both tasks (I view it as the latter).
Markdown is also wildly inconsistent - why have fenced codeblock feature with info string to set the language, when you can’t have fenced blockquote with info string to set the “cite” attribute?
I’m actually quite fond of reStructuredText but without widespread support it’s hard to justify investing into a much less portable format.