If you’re not accustomed to reStructuredText, it looks dreadful. If you saw it in the context of a larger document that used directives for more things, it’d make more sense.

Also the author has very bad taste in having used two spaces of indentation. It should have been three, which makes it significantly less ugly:

  .. image:: example.jpg
     :alt: alttext

“.. ”: this block is magic.

“image::”: directive, type image.

“example.jpg”: directive argument, file name.

“:alt: alttext” directive option, named alt, value alttext.

Rewritten with a completely different sort of syntax, for fun:

  ┌ IMAGE ─ example.jpg ──┐
  │ alt = alttext         │
  └───────────────────────┘

▲ dangus 3 days ago | parent [-]

Yikes, this explanation does not make it better. You’re telling me the indentation convention is three spaces?

And “..” is just your “something cool is about to happen” symbol?

I’ve been reading through the documentation more and this thing seems insane.

That .. symbol is also used for comments!? “Oh if it’s invalid it’s a comment!” No way to make multi-line comments without another ridiculous indentation.

The tables are insane, somehow they implemented something worse than markdown.

To make a header you need to make a long line of characters as long as your text for some reason.

For being a language that’s supposed to be more powerful than markdown and not so HTML-adjacent it sure depends on whitespace a lot. Like, why do literal blocks need be indented? Why do doctest blocks need to end with a blank line?

> The handling of the :: marker is smart:

> If it occurs as a paragraph of its own, that paragraph is completely left out of the document.

> If it is preceded by whitespace, the marker is removed.

> If it is preceded by non-whitespace, the marker is replaced by a single colon.

lol, a directive that does 3 entirely unrelated things depending on white space. Genius.

▲

chrismorgan 3 days ago | parent [-]

Three space indentation is indeed the convention, mostly because of `.. `, but honestly `1. ` is nicer with three spaces too… unless you want to go to ` 1. `. Frankly, other than when inlining code that uses a different number of spaces, I think I visually prefer three spaces for something like reStructuredText, even apart from directives.

`.. ` is a bit overloaded and I think better was possible.

> The tables are insane, somehow they implemented something worse than markdown.

To write without tools, I’ll accept it’s not good. But to read, it’s good. Also be aware you can get a table from nested lists <https://docutils.sourceforge.io/docs/ref/rst/directives.html...> or CSV <https://docutils.sourceforge.io/docs/ref/rst/directives.html...>. That demonstrates a nice bit of the power of the reStructuredText approach, I’d say.

On the literal blocks `::` thing, it’s a little too magic for my taste, but in practice works pretty well. Based on your quote, you weren’t going through <https://docutils.sourceforge.io/docs/ref/rst/restructuredtex...>; I think that’s a better presentation of it, showing how it’s not three entirely unrelated things, but rather just two minimised forms of the complete thing. I’d say it does two largely-unrelated things only! (Aside: “a directive” in reStructuredText is the `.. foo::` construct. The `::` is not a directive.)

> Like, why do literal blocks need be indented?

I think you may be biased against significant indentation. It has advantages and disadvantages over fencing—and the most important disadvantages are really about <textarea>. I think things have swung way too far in the direction of fencing. I’ve been making and using my own prettiness-focused lightweight markup language for the last five or so years, and where I started out with only a little significant indentation (list markers), I’ve leaned ever more in the direction of significant indentation, because most of the time I find it to be better, and I reckon the results are very pretty.

Remember also the Python background to reStructuredText in things like indentation and more specifically doctests.

	▲	dangus 3 days ago \| parent [-]
		I can concede that it seems to make sense for Python, of course I can also imagine why it wouldn’t be a popular choice for general purpose use cases.