3 ms·

Good question! Keep in mind that I'm not a regular rST user, so I'm not the best person to make complaints about it. I dislike both the inline links and the fo

Good question! Keep in mind that I'm not a regular rST user, so I'm not the best person to make complaints about it. I dislike both the inline links and the footnotes. I agree with you about the underscore and that is the main aesthetic critique. I also rather dislike the use of backticks here, though. They have the smell of code especially with the nested <href>. If you have to have inline links I think Markdown's aren't that bad, especially because they lend themselves to easily adding inline images (exclamation point before the opening bracket). But both clearly function as markup, which is what would make them inappropriate for my envisioned format that is intended to be primarily rendered as plain text. Additional complaints about rST syntax are the mixture of semantic document elements with code. For example rST has a glossary directive (great!) but unfortunately it is (and reads as) a piece of code (just like literalinclude or highlight). In some ways what I'm looking for is even more constrained than Markdown. For example, # GLOSSARY: is valid markdown, but I'd like a standardized format that imputes semantic meaning to constructs like this and has rules for how the glossary section of the document must be formatted. The result would (hopefully) read without any hint that it is markup, but on the other hand make it possible to convert the document to PDF, HTML, EPUB, etc. A format intended to be read as text probably wouldn't have inline links at all. A cleanly readable syntax for footnotes would probably make more sense, and with the proper semantics, a viewer / converter for the format could convert the link to inline if desired.

chrismorgan 5y ago
Interesting. I’m curious in significant part because I’m in the process of designing a lightweight markup language of my own, in which I am caring a lot about the ergonomics of the source text for reading, writing and tooling (I’d say all existing LMLs fail significantly on at least one of those). Your remarks against inline links surprise me, because I am rather inclined to approve of inline links, because otherwise the href tends to get too far separated from the place it is, yet it is regularly important to the understanding of the text. Similarly endnotes as widely practised on the web (extremely commonly misnamed footnotes) are horrible for reading, as they’re in a completely different location, requiring jumping back and forth—whereas in the source, there’s a fair chance you wrote the footnote near the source. I’m rather partial to side notes, and have in the past set such a thing up in Sphinx so I could write the |main column content| like that, followed by `.. |main column content| sidenote:: the note text` below. Meanwhile on my website, currently Zola-powered, I write {{ sidenote(src="main column content", note="the note text") }} which invokes a shortcode that transforms it into the required HTML. Anyway, enough of that. I despise Markdown’s inline link syntax, because it has no rhyme or reason: square brackets around the text, then parentheses around the href and possibly toooltip. Not only are parentheses around the link terrible due to being URL characters (thereby complicating the parser in an attempt to mitigate the damage by allowing matching parentheses, yet still requiring something beyond a simple URL serialiser for unmatched parentheses), the entire […](…) syntax is quite unlike anything used by anything else, and devoid of any rationale (you could just about describe the URL as parenthetical to the prose, but the claim is weak at best and perhaps harmed by the lack of space before it, though that would be a problem of its own)—people that don’t work in Markdown extremely extensively get the order wrong ((text)[href], [href](text) or (href)[text]) fairly regularly. As for Markdown’s inline image syntax, it’s possibly even more atrocious by virtue of being utterly opaque—it’s something that has to be taught and can’t be guessed, and is surprising when encountered even when you see that it is an image. In my own markup language (code name T), I currently have [link text <href>] as the inline link syntax, quite similar to reStructuredText’s, but using matching outer delimiters. ([link text] <href> or word <href> are almost tempting, but definitely conflict with other parts of my goals.) With your glossary heading, you may be interested in AsciiDoc (which incidentally for this submission has DocBook semantics); it’s big on the sort of semantics it looks like you may be interested in. (I’m not so fond of quite a bit of its syntax, but its semantics are robust like reStructuredText’s.) https://docs.asciidoctor.org/asciidoc/latest/sections/glossary/ https://docs.asciidoctor.org/asciidoc/latest/sections/glossa... is its glossary stuff. Note that it requires more than just a heading with the text “glossary”, which would be problematic to operate on for linguistic reasons (though you could perhaps separate such style commands in a CSS-like way, `section:heading("GLOSSARY:") { role: glossary; }`).
- aurora72 5y ago
  There are dozens of Markdowns flavors: Github Flavored Markdown Stack Exchange Flavored Markdown Markdown Extra LiaScript MultiMarkdown LeanPub Flavored Markdown Markua Python-Markdown Kramdown Even that is enough to show that Markdown is bad by design. But when you actually use it for any serious document, you face the bad design and struggle with the "easy" tool :)

chrismorgan 5y ago

Interesting. I’m curious in significant part because I’m in the process of designing a lightweight markup language of my own, in which I am caring a lot about the ergonomics of the source text for reading, writing and tooling (I’d say all existing LMLs fail significantly on at least one of those). Your remarks against inline links surprise me, because I am rather inclined to approve of inline links, because otherwise the href tends to get too far separated from the place it is, yet it is regularly important to the understanding of the text. Similarly endnotes as widely practised on the web (extremely commonly misnamed footnotes) are horrible for reading, as they’re in a completely different location, requiring jumping back and forth—whereas in the source, there’s a fair chance you wrote the footnote near the source. I’m rather partial to side notes, and have in the past set such a thing up in Sphinx so I could write the |main column content| like that, followed by `.. |main column content| sidenote:: the note text` below. Meanwhile on my website, currently Zola-powered, I write {{ sidenote(src="main column content", note="the note text") }} which invokes a shortcode that transforms it into the required HTML. Anyway, enough of that. I despise Markdown’s inline link syntax, because it has no rhyme or reason: square brackets around the text, then parentheses around the href and possibly toooltip. Not only are parentheses around the link terrible due to being URL characters (thereby complicating the parser in an attempt to mitigate the damage by allowing matching parentheses, yet still requiring something beyond a simple URL serialiser for unmatched parentheses), the entire […](…) syntax is quite unlike anything used by anything else, and devoid of any rationale (you could just about describe the URL as parenthetical to the prose, but the claim is weak at best and perhaps harmed by the lack of space before it, though that would be a problem of its own)—people that don’t work in Markdown extremely extensively get the order wrong ((text)[href], [href](text) or (href)[text]) fairly regularly. As for Markdown’s inline image syntax, it’s possibly even more atrocious by virtue of being utterly opaque—it’s something that has to be taught and can’t be guessed, and is surprising when encountered even when you see that it is an image. In my own markup language (code name T), I currently have [link text <href>] as the inline link syntax, quite similar to reStructuredText’s, but using matching outer delimiters. ([link text] <href> or word <href> are almost tempting, but definitely conflict with other parts of my goals.) With your glossary heading, you may be interested in AsciiDoc (which incidentally for this submission has DocBook semantics); it’s big on the sort of semantics it looks like you may be interested in. (I’m not so fond of quite a bit of its syntax, but its semantics are robust like reStructuredText’s.) https://docs.asciidoctor.org/asciidoc/latest/sections/glossary/ https://docs.asciidoctor.org/asciidoc/latest/sections/glossa... is its glossary stuff. Note that it requires more than just a heading with the text “glossary”, which would be problematic to operate on for linguistic reasons (though you could perhaps separate such style commands in a CSS-like way, `section:heading("GLOSSARY:") { role: glossary; }`).

aurora72 5y ago
There are dozens of Markdowns flavors: Github Flavored Markdown Stack Exchange Flavored Markdown Markdown Extra LiaScript MultiMarkdown LeanPub Flavored Markdown Markua Python-Markdown Kramdown Even that is enough to show that Markdown is bad by design. But when you actually use it for any serious document, you face the bad design and struggle with the "easy" tool :)