Comment by chrismorgan

6 years ago

reStructuredText on these, for anyone that’s curious or thinking about it:

1. If you use “5.”, it’ll give you a five. If you want auto-numbering, use “#.” as your prefix. (While I’m thinking of it: I hate that using actual Unicode bullets like “•” doesn’t work in Markdown, and that in https://talk.commonmark.org/t/unicode-character-bullet-u-202... it’s been actively rejected for CommonMark.)

2. Code blocks are by indentation only, no fencing, but avoids confusion about indentation levels by defining all of that stuff properly and having it match visual usage, rather than Markdown’s crazy “four spaces, but in certain situations we’ll let you get by with 3, 2, 1 or even 0—but if you then seek to nest, remember to bump it up to eight rather than just N+4”. Code blocks are indicated by `::` at the end of or as the entire previous paragraph, which is esoteric, but also fits in very well with its directive syntax, which is how you can attach extra metadata to code blocks. It’s definitely not as simple as the newer Markdown fencing approach, though it fits into the rest of reStructuredText in a sane and principled way so that it’s not at all hard. Still, I think that a new version of reStructuredText would quite possibly include fencing in some form—or maybe directives would be resyntaxed to be able to be fenced rather than indented, though achieving that while still allowing nesting would take care.

3. Markdown in HTML in Markdown? That Markdown extends HTML is the real problem here, and is both its greatest strength and help in adoption, and its catastrophic weakness. reStructuredText is a language of its own that doesn’t extend anything, so that style of HTML output is typically done by defining new directives, which can then contain reStructuredText. It’s strictly less powerful, but it composes way better. As a workaround, the `raw` directive lets you put in arbitrary HTML (or LaTeX, &c.).

4. By deliberately not being HTML, reStructuredText handles this sort of thing much better. Each node in the document can have classes (which will end up as class="…" in HTML, something else in LaTeX, &c.). You can do things like `.. class:: …` to apply a class to the next block (heading, paragraph, list, &c.). Most directives support a :class: option. You can define new roles so that :classname:`…` will do what you desire. And none of this is then tied to HTML.

5. reStructuredText lets you define anchors at any place in the document (which can also be used for index entries when writing books or things like that). `.. _anchor-name:` above the heading will do it thus. This protects you against the anchor changing (and thus breaking links) if you change the text of the heading. Any form of automatic heading ID generation is left to the software to decide, e.g. Sphinx generates IDs by default.

6. Field lists. A field list at the start of the document is treated as document bibliographic data, and you can put anything in there you like.

I myself prefer reStructuredText in almost all regards, but I scarcely use it any more other than for a couple of types of personal documents, because of the ubiquity of Markdown. It was similar with Mercurial and Git.

4 comments

chrismorgan

Reply
1wd  6 years ago

Agree. reStructuredText has much stronger concepts. Composable. A standard way to extend semantics without requiring new syntax. Not tied to HTML. It has some slightly more superficial weaknesses that made it the loser I guess: ugly / awkward / inconvenient syntax; no atx headers; not every document is "valid"; HTML is less integrated... worse-is-better strikes again.

jurip  6 years ago

It's weird how both ReST and Markdown stumbled on that indentation thing. And ReST has the awkward header underlines, too. Both of those are annoying at the best of times and basically unusable with proportional fonts (and we're dealing with prose here, where there should be no reason to force people to use monospaced fonts if they don't want to.)

If I'm ever involved in designing a syntax like that, the first hard and fast rule will be that the user should never have to count anything, especially in relation to anything else.

  • chrismorgan  6 years ago

    reStructuredText is very committed to the plain text visually matching the formatted. For headings, visual underlining makes sense in that context. And code is conventionally indented, so it also makes a lot of sense. (Blockquotes are indented as well, differing from code blocks by the absence of `::` at the end of the preceding paragraph; indentation again matches conventional appearance. But that’s a place where I get where Markdown’s coming from, using > indentation like in emails.)

    In more recent times, convenience of writing has become a more important concern to people, because these formats have shifted from niche use by dedicated people in real text editors that would like what they see to match the end result fairly well, to mainstream use in textareas and similar, and sometimes even WYSIWYG editors. That’s what’s driven people to prefer the convenience of code fencing, because indenting each line in a textarea is a pain. Ditto on headings. If reStructuredText were being redone now, I think it’s fair to say that prefix rather than underlined headers would be at least an option. It would just remain to be seen whether they went with `###` meaning level 3 even if there was no `##` or `#`, or whether they’d boost it up to level 1 or title, as appropriate.