ReST

I’ve been trying to learn reST and finding it hard going.  reST just doesn’t seem to work the way I expect it to work.

I don’t know whether the problem lies in reST or in me. It could be me.  I carry a lot of conceptual baggage — it may just be that reST is different from structured-text dialects that I’ve worked with in the past.

Anyway, at this point I am a reST newbie.  As such, I want to find:

• A few very short, very accessible introductions or tutorials to reST
• an explanation of reST’s basic “world-view”
• an online sandbox where I can play with reST, similar to the markdown dingus

1. Introductions

I’ve found these to be pretty useful.

• The Sphinx reST introduction.
• a great introductory tutorial
• another very good short tutorial
• a short video at showmedo.com that gives a quick overview of the things you can do with reST
• and of course the official reST Web page has several good items in its documentation section

2. Fundamental concepts

I haven’t yet found a good explanation of reST’s world-view.  I suspect it is staring me in the face and I’m just not seeing it.  What I need is for it to be spelled out in big block letters.  And then to be hit over the head with it. Sort of like this:

reST is built on three fundamental concepts: paragraph, indentation, and whitespace.

paragraph

The paragraph is the basic building block of reST. A paragraph is a chunk of text separated from other chunks by one or more blank lines.

reST ignores single newlines, but two or more adjacent newlines (i.e. one or more blank lines) delimit a paragraph.

indentation

Paragraphs must have the same indentation — that is, line up at their left edge. Paragraphs that start indented will result in indented quote paragraphs. For example:

This is a paragraph. It’s quite short.

This paragraph will result in an indented block of text, typically used for quoting other text.

This is another one.

Results in:

This is a paragraph. It’s quite short.

This paragraph will result in an indented block of text, typically used for quoting other text.

This is another one.

whitespace

The importance of white space is touched on in a tip in the official reST introduction, which talks about inline markup – markup for things like italics, bold, monospaced text, etc.

Think of inline markup as a form of (parentheses) and use it the same way: immediately before and after the text being marked up. Inline markup by itself (surrounded by whitespace) or in the middle of a word won’t be recognized.

reST markup is context-sensitive, or maybe I should say whitespace sensitive. For example, an asterisk in one context creates a bullet for a bullet-list. An asterisk in another context creates inline markup for emphasis (italics). The difference in the context is whether or not the asterisk is or is not preceded or followed by whitespace.

• An asterisk that is preceded by, but not followed by, whitespace starts italics.

• An asterisk that is followed by, but not preceded by, whitespace ends italics.

• Otherwise, an asterisk at the beginning of a line creates a bullet.

This creates emphasis.

some text. *enclosed text* some text.

But this creates a bullet item.

some text. * enclosed text * some text.

3. A reST dingus

I have been able to find an online reST editor.  http://cometdemo.lshift.net:8080/greed/welcome_document/ I’m not quite sure what to call it, so I’ll call it “greed” — that’s a nice memorable name.  In my experience, greed’s page layout doesn’t work very well under Firefox, but works just fine with Internet Explorer.

There is also a pretty nice reST dingus at Siafoo, at www.siafoo.net/tools/reST.

4. Things that I find confusing

I get confused when I read this in the reST documentation:

A paragraph is a chunk of text separated from other chunks by one or more blank lines. … Paragraphs must have the same indentation — that is, line up at their left edge.

Is it saying that the definition of a paragraph is: a chunk of lines that is separated from other chunks of lines by two newlines and contains lines all of which have the same indentation?  What happens if you have a chunk of lines that is delimited by double newlines, but contains lines with _different_indentation levels?

Let’s see.  Let’s start with these lines.

line A line B line C

If we feed these lines to greed, we get:

line A line B line C

No surprises there.

Now let’s add some indentation to line B:

line A line B line C

When we feed this to greed, what we get is roughly (I say “roughly” because in WordPress it is difficult to reproduce the exact HTML that you get from greed) this:

line A line B System Message: WARNING/2 (, line 3) Definition list ends without a blank line; unexpected unindent. line C

So reST has rejected a paragraph with irregular indentation.

This is A Good Thing.  reST seems to be acting they way I would expect it to.

Now let’s try putting double newlines after line B, like this:

line A line B

line C

When we feed this to greed, it produces roughly this:

line A line B

line C

So now I’m confused. In theory, line A and line B form a single, double-newline-delimited paragraph, with irregular indentation.  reST rejected irregular indentation in a paragraph in the previous example, but now reST is accepting irregular indentation and acting as if line B was an indented paragraph. What is going on???!!! (See the answer, below.)

So what happens if we put a double newline after line A?  We get roughly this:

line A

line B

line C

This is the same result as before, but with more space between line A and line B.  This is what I would have expected.

So what was going on?

My hypothesis is that reST interpreted line A and line B as a definition list — line A being the term, line B being the definition.

The reST docs say that in a definition list, “Blank lines are not allowed between term and definition.”

So (to put it in the most obtuse way possible) a paragraph is a chunk of lines that is separated from other chunks of lines by two newlines. All of the lines in the paragraph must have the same indentation, except when the paragraph is a definition list, in which case the indentation of the definition_must be different_ (greater than) the indentation of the term.

The Bottom Line

I suspect that reST by its very nature has a lot of gotchas.

reST is trying to do so much (e.g. to support advanced markup structures such as definition lists) with so little (simple ASCII text) that it must read a lot into what (in other circumstances) would be meaningless differences.   You might say that reST by its very nature has a very high interpretation-to-signal ratio.

If you are feeling uncharitable, you could say that reST is fragile or flaky; if charitable, you might say that it is very sensitive.   What that adds up to — for at least some newbies — is that it has a lot of gotchas.

So (I’m embarrassed to admit it) I’m still struggling with reST.  Undoubtedly, it is just a matter of time and experience.  I’m pretty sure that if I work with reST long enough — and read all of the documentation — I will eventually grok it.

COMMENT - 1

Tarek Ziade’s book (Expert Python Programming: http://www.packtpub.com/expert-python-programming/book) has what I thought was a very nice, “do stuff with this now” intro to reST. The rest of the book is also very well done imo. Packt sells a PDF version of the book, which has been open on my personal laptop for probably a month straight. (I do not work for any publisher, btw)

COMMENT - 2

Sorry that you’re struggling. Please realize that reST is doing a lot with very little. It’s basically a formalization of lots of informal implicit formatting that people do in email and other plain text.

It may not break up the fundamental concepts the way you want, but “An Introduction to reStructuredText” is a good place to start:http://docutils.sourceforge.net/docs/ref/rst/introduction.html

For the specifics of paragraph syntax, “and” clearly applies. Definition lists are not some variant on paragraphs. Look up definition lists in the “reStructuredText Markup Specification” to see how they differ (http://docutils.sourceforge.net/docs/ref/rst/introduction.html). In fact, the first few sections of “Syntax Details” may be what you’re looking for (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#syntax-details).

As for a “dingus”, the rst2a (a=anything) site may be appropriate: http://rst2a.com/ (click on “Create” then “Type a Document”).

Overall, methinks the OP doth protest too much. You’re learning a new markup language, and you’re complaining about specifics before you’ve practised enough of the basics to get the concepts straight. Start with the primer: http://docutils.sourceforge.net/docs/user/rst/quickstart.html

In any case, markup is very individual, especially this kind of implicit markup — maybe you like it, maybe you don’t. There are lots of other formulations that you might like better.