Change in spec.txt examples format

Spec
1

I’ve changed the format of spec.txt. Previously an ad hoc, non-Markdown syntax was used for the spec examples:

.
input text here
.
expected html result here
.

This had the drawback that spec.txt wasn’t really in Markdown format, and wouldn’t render sensibly as a Markdown file. I have changed the format to

```````````````````````````````` example
input text here
.
expected html result here
````````````````````````````````

This has two advantages. It makes each example more visible as a unit, and it allows spec.txt to be handled with standard Markdown/CommonMark tools.

Accordingly, I have replaced the old python script that was used to create the HTML version of the spec with a new lua script. The old python script used regex substitutions to add internal links, not entirely reliably (as you can see if you look at the bottom part of the current spec. The new lua script uses my lcmark library, which wraps libcmark. It operates on the parse tree produced by cmark, and is faster and more reliable. It can also produce a LaTeX version, suitable for rendering to pdf (doing this previously required pandoc and a custom filter).

3 Likes
2

That’s setting a good example indeed. Maybe, one day, your script will evolve into a more generic tool with more variable info-string syntax like example Markdown, HTML or example Markdown -> HTML and with the separator `.
´ made configurable somehow (because this one will fail in some combinations, maybe even with future extensions to CM).