Use Python to format examples

[Thom1729]

Format examples in the Python script rather m2k.

This is a surprisingly complex operation. The original m2k code did a lot, and there are a lot of corner cases. In the future, I'd like to eliminate some of those corner cases (or possibly redo the example formatting entirely), but for this PR the objective was producing as close to identical output with as close to identical input as possible.

Nevertheless:

• There is one tiny change in spec.md. Kramdown wanted to turn the line * literal <!-- | --> into a table, so I used indices for the comment to avoid this.
• Example 9.10. Folded Lines is highlighted differently using this PR. I'm pretty sure this was actually a bug in the old script.

Aside from these two points, the input and output are identical (verified with xmldiff).

N.B. The new implementation checks production links in examples, and there are several broken links that should be fixed in another PR.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[Thom1729]

https://spec.yaml.io/pr-254/spec/1.3.0/

[Thom1729]

Here's the source for Example 9.10. Folded Lines:

**Example #. Folded Lines**

·folded↓ ·line↓ ↓ ·next ·line↓

• bullet

• list

• lines

·last↓ ·line↓

Comment

"\nfolded line\nnext line\n \

• bullet\n \n * list\n \
• lines\n\nlast line\n"

Legend:

• [folded-scalar-lines(n)]
• [folded-scalar-text(n)]

Take line 3, for instance. Columns 1–7 should be marked folded-scalar-lines(n) because of the 3:1,7 in that comment, and the entire line should be marked folded-scalar-text(n) because of the 3 in that comment. This is the output with this PR. I don't know why it's wrong in 1.2.2. But it's actually right in 1.2.1 — s-nb-folded-text(n) and l-nb-folded-lines(n) switched places between 1.2.1 and 1.2.2, which obscures this.

I think the switching of s-nb-folded-text(n) and l-nb-folded-lines(n) between 1.2.1 and 1.2.2 was actually wrong, and that this bug was obscured by a bug in the old script. The new script renders the highlights correctly in this case, which reveals that the comments are next to the wrong productions in the legend.

[ingydotnet]

I see what you mean.

I found another bug in 1.2.2. Line 5 needs to be highlighted.

Can you fix that bug in 1.3 and also file an errata issue for 1.2?

[Thom1729]

Yes, I'll do that in separate PRs.