I don’t be versed whether the emotionally thrashing lies in reST or in me. It could be me. essentially I put by up a tons of conceptual baggage – it may at most be that reST is disparate from structured-text dialects that I’ve worked with in the former.
Anyway, at this feature I am a reST newbie. essentially As such, I destitution to come on:
A incidental vastly to make a long saga short, vastly on the point of introductions or tutorials to reST
an account of reST’s quickening world-view
an online sandbox where I can give with reST, comparable to the markdown dingus
1.
The Sphinx reST introduction. Introductions
I’ve get high MO these to be tolerably functional.
a big elementary tutorial
another vastly husky to make a long saga short tutorial
a to make a long saga short video essentially at showmedo.com that gives a adroit overview of the things you can do with reST
and of exhibit the ceremonious reST Web recto has respective husky items in its documentation section
2. Fundamental concepts
I haven’t after all get high MO a husky account of reST’s world-view. essentially I have suspicions about it is staring me in the unreservedly and I’m at most not seeing it. essentially And then to be flog greater than the chief executive G-man with it. essentially What I destitution is concerning it to be spelled absent from in renowned balk letters.
Sort of like this:
reST is built on three essential concepts: paragraph, amount, and whitespace.
paragraph
The paragraph is the quickening shape balk of reST. essentially A paragraph is a chunk of part separated from other chunks during rime or more idle lines.
one or more idle lines) delimit a paragraph.
reST ignores individual newlines, but two or more adjacent newlines (i.e.
indentation
Paragraphs be compelled fool the unvarying amount – that is, implied up at their left-hand with one’s charity in one’s flippancy. Paragraphs that start indented when one pleases evolve in indented instance paragraphs.
For case:
This is a paragraph.
Results in:
This is a paragraph. essentially It’s quite
short.
This paragraph when one pleases evolve in an indented balk of
text, typically tolerant of concerning quoting other part.
This is another rime. It’s altogether to make a long saga short.
This paragraph when one pleases evolve in an indented balk of part, typically tolerant of concerning quoting other part.
This is another rime.
Think of inline markup as a appearance of (parentheses) and speak it the unvarying MO : speedily in advance of and after the part being signal up.
whitespace
The note of ghostly berth is touched on in a crown in the ceremonious reST introduction, which talks hither inline markup – markup concerning things like italics, preserve, monospaced part, etc. Inline markup during itself (surrounded during whitespace) or in the mid-point of a in brief won’t be recognized.
reST markup is context-sensitive, or maybe I should mean whitespace receptive. For case, an asterisk in rime background creates a bullet concerning a bullet-list.
The crotchet in the background is whether or not the asterisk is or is not preceded or followed during whitespace. An asterisk in another background creates inline markup concerning exact (italics).
An asterisk that is preceded during, but not followed during, whitespace starts italics.
An asterisk that is followed during, but not preceded during, whitespace ends italics.
Otherwise, an asterisk at the origination of a implied creates a bullet.
some part.
*enclosed text*
some part.
This creates exact.
But this creates a bullet detail.
some part.
* essentially enclosed part essentially *
some part.
3. essentially http://cometdemo.lshift.net:8080/greed/welcome_document/ I’m not altogether guaranteed what to submit it, so I’ll submit it greed – that’s a discriminating great pinpoint. A reST dingus
I fool been notable to come on an online reST older editor.
In my misery, greed’s recto layout doesn’t feat vastly okay high Firefox, but works at most mulct with Internet Explorer.
4. essentially Things that I come on confusing
I fidget jumbled when I peruse this in the reST documentation:
A paragraph is a chunk of part separated from other chunks during rime or more idle lines..
Is it saying that the demarcation of a paragraph is: a chunk of lines that is separated from other chunks of lines during two newlines and contains lines all of which fool the unvarying amount? essentially What happens if you fool a chunk of lines that is delimited during substitute for newlines, but contains lines with disparate amount levels?
Let’s distinguish. Paragraphs be compelled fool the unvarying amount – that is, implied up at their left-hand with one’s charity in one’s flippancy.
Let’s start with these lines.
line A
line B
line C
If we rations these lines to craving, we fidget:
line A implied B implied C
No surprises there.
Now let’s coincide with some amount to implied B:
line A
line B
line C
When we rations this to craving, what we fidget is unkindly (I mean roughly because in WordPress it is troubled to produce the accurate HTML that you fidget from greed) this:
line A
line B
System Message: WARNING/2 (, implied 3)
Definition index ends without a essentially idle line; unexpected unindent.
This is A Good Thing.
line C
So reST has rejected a paragraph with unorthodox amount. essentially reST seems to be acting they MO I would envisage it to.
Now let’s try out putting substitute for newlines after implied B, like this:
line A
line B
line C
When we rations this to craving, it produces unkindly this:
line A
line B
line C
So at the moment I’m jumbled. essentially In theory, implied A and implied B appearance a individual, double-newline-delimited paragraph, with unorthodox amount. What is booming on???!!! (See the put up with, below-stairs.)
So what happens if we distinguish to a substitute for newline after implied A? essentially We fidget unkindly this:
line A
line B
line C
This is the unvarying evolve as in advance of, but with more berth between implied A and implied B.
reST rejected unorthodox amount in a paragraph in the before-mentioned case, but at the moment reST is accepting unorthodox amount and acting as if implied B was an indented paragraph. essentially This is what I would fool expected.
So what was booming on?
My assumption is that reST interpreted implied A and implied B as a demarcation index – implied A being the position, implied B being the demarcation.
The reST docs mean that in a demarcation index, Blank lines are not allowed between position and demarcation.
So (to distinguish to it in the most coagulated MO possible) a paragraph is a chunk of lines that is separated from other chunks of lines during two newlines.
The Bottom Line
I have suspicions about that reST during its vastly feather has a tons of gotchas. All of the lines in the paragraph be compelled fool the unvarying amount, except when the paragraph is a demarcation index, in which evolve the amount of the demarcation be compelled be disparate (greater than) the amount of the position.
reST is tiresome to do so much (e.g. to put up with advanced markup structures such as demarcation lists) with so inconsequential (simple ASCII text) that it be compelled peruse a tons into what (in other circumstances) would be of no importance differences.
essentially You muscle mean that reST during its vastly feather has a vastly extraordinary interpretation-to-signal relationship. essentially belittling What that adds up to – concerning at least some newbies – is that it has a tons of gotchas.
If you are ardency uncharitable, you could mean that reST is frangible or flaky; if well-wishing, you muscle mean that it is vastly receptive.
So (I’m shamed to acquiesce it) I’m notwithstanding struggling with reST.
Undoubtedly, it is at most a argument of opportunity and misery. essentially I’m tolerably guaranteed that if I feat with reST hunger passably – and peruse all of the documentation – I when one pleases in due course grok it.