If a string of lines Ls constitute a block quote with contents Bs, then the result of deleting the initial block quote marker from one or more lines in which the next non-whitespace character after the block quote marker is paragraph continuation text is a block quote with Bs as its content."
I think many people will struggle to follow this sentence.
It’s the “Laziness” section. The key aspect of the “lazy” method of marking a block quote is that you can just type one > on the first line of the block. I don’t think that comes through in the spec.
That section could use a clean rewrite. (I’m not even sure how one would certify that the condition in the first sentence is met.)
I also suggest that an example of the one > on the first line be included – none of the many examples of block quotes feature it. A quick check on Babelmark confirms that CommonMark is indeed treating such markup as a block quote, as are most of the libraries.
For people learning Markdown/CommonMark, something like Gruber’s syntax description will be just right – something like, “you can omit the
> signs after the first line of a pargraph, like so…” The spec doesn’t aim to replace this kind of beginner’s document; it aims to give a completely general rule. If there’s a better and clearer way of stating the general rule, I’m certainly open to hearing it.
I’m not even sure how one would certify that the condition in the first sentence is met.
The idea here is that you might know from rules 1 and 3 that lines Ls constitute a block quote with contents Bs. Then rule 2 gives you some more things that count as block quotes.
I also suggest that an example of the one > on the first line be included
You mean like Example 197?
Yeah, Gruber’s description looks clear on this. I’ll think about a spec-friendly version of it.
I missed Example 197, sorry. In my defense, it is the twentieth example down from section 5.1. Since it’s the modal form of laziness, I’d move it way up. 5.1 starts with Example 178.
Descriptions that are helpful for teaching beginners are rarely sufficiently general or accurate for a spec, and spec descriptions tend to be terrible for beginners. We never imagined that beginners would want to learn CommonMark by reading the spec. There should be separate documents for this purpose: see the thread Markdown Tutorial contest feedback.