It would be helpful if we could see actual requirements in the spec. Normally done by marking non-normative paras as such.
Yes, I agree it’s an important distinction.
Given the structure of the CommonMark spec, with its embedded test cases, I thing we should think beyond simply tagging paragraphs as normative or not. The some key parts are the examples, and they are a very special case.
Some examples are completely normative, some negative, and there are other flavors of example flavors in between. For example, it could be very useful flag to tag locations in the of the output section of a side-by-side example where additional attributes are permitted, but not required, in the output of a CommonMark processor. In fact I think this would be key in applying the principles of Semantic Versioning to the CommonMark specification.
Normative examples strike me as counter intuitive. They would be better as plain text. I saw them as examples, rather than a test case? Either way they add too much bulk to the spec and would better serve as a separate document, which would require the ‘normaitve’ examples to be re-worked.
OK, I’m sure you aren’t alone finding this counter-intuitive. I’ll try to clarify.
Right now, the side-by-side examples, (labeled Example 1, Example 2, in the HTML version) are the most normative part of the spec!
That’s because it is written in a way that supports test-driven development. Using this approach, a software developer, writing an implementation of CommonMark, knows quickly if the output of his tool doesn’t match all of the side-by-side examples in the spec. Those examples are are the primary test cases.
To support this, the spec is written in a special way, its not (just) the HTML document most people start looking at. The core specification file spec.txt is use for several purposes, producing the HTML is just one of them. It is written in its own special dialect, created just for this purpose, each dual purpose example/test delimited by lines containing just a dot.
You can have a look at https://github.com/jgm/stmd/blob/master/spec.txt see the raw spec in its current form, I’ll put a small extract below: Example 3 in the HTML comes from lines in spec.txt that read
.
- `one
- two`
.
<ul>
<li>`one</li>
<li>two`</li>
</ul>
.
It seems funny to have this corner-case, be the third example in the spec, until you realize it’s primary purpose is test implementations, not to inform a gentle reader. This jaring result (focuing on corner-cases) can probably be best mitigated in the short term by improving the introduction, rather than restructuring the specification.
There are several different tools that read spec.txt and do special things with it. A toolset for producing the human-readable view of the specification is just one of those. While these tools aren’t part of the specification, they are intimately connected to it, and are written in several different programming languages. If you know regex’s and a little JavaScript, spec2js.js is a good place to start.
This special ‘dot’ language the spec is written in is not CommonMark, I’m not even sure if it has a name. But what I was saying above was that we may need to extend the ‘dot’ language some as the specification evolves, and it needs to support an refined version of the normative/informative distinction, among other things.
Another common request is separating out the corner-case examples, which exist to better test implementations, not necessarily inform human readers. This would be done by extending the ‘dot’ language too.