Testing Nickel snippets in the manual

[vkleen]

Add a new test suite in core/tests/manual which parses the Markdown files in doc/manual to extract all Nickel code blocks and checks that they parse or evaluate correctly. For now, REPL sessions in the manual aren't evaluated during testing but only parsed.

To facilitate this, code blocks in the manual are annotated with nickel, nickel-lines, nickel-parse, nickel-repl or nickel-no-check depending on the parsing or evaluation mode desired.

Closes #1154

[jneem]

I'm a little confused by this example. I guess you had to indent it extra so that the final "% will be caught by the parser? But even before this change, the "This line has no indentation" line had indentation...

[vkleen]

The multiline string parser strips common indentation. So this line doesn't have any indentation in the final string and that's what this example is supposed to illustrate.

[jneem]

Isn't this always true?

[vkleen]

If value isn't an integer, value % 1 returns the fractional part of value. I suppose that's in line with writing x mod 1 for the residue class of x in $\mathbb R/\mathbb Z$...

[yannham]

A good step forward!

I wonder if putting a space after nickel in the textinfo of fenced code block isn't more idiomatic markdown. In particular, according to the common mark spec, only the first word of the textinfo (up to the first space) is considered for highlighting purpose (see eg https://spec.commonmark.org/0.28/#example-112). We adapted the website, but for example I often read the manual inside NeoVim which has syntax coloring for Nickel snippet, and who knows what markdown rendered people will use to read the manual outside of the website. Would that make sense to do:

• nickel-repl => nickel repl
• nickel-parse => nickel parse

It could be something even more specific to indicate that it doesn't concern rendering, such as nickel @test.parse-only (this is an absolutely random suggestion, not necessarily a good one)

[yannham]

The example doesn't check out with practice: it seems that you are requiring a - instead of a space, ie nickel-repl.

[vkleen]

Right, I tried what you were suggesting about spaces before. Unfortunately, gatsby doesn't seem to ignore the extra information after nickel. In fact, it seems to remove the space after nickel and try to look for a Prismjs language nickelrepl if given nickel repl in the code block. Relying on that behaviour felt a bit too spooky for me, though...

[vkleen]

On the other hand, relying on it and just continuing to check when updating the website should make syntax highlighting work in saner markdown renderers, I guess. It's easy to change back here, so whichever you think would make more sense long term.

[yannham]

Yeah, and what about using a special character and a space, something like nickel #repl or nickel !repl? Gatsby would parse that as nickel#repl which has almost no chance of conflicting with anything, keeping the alias approach (could even be nickel -repl, even if that feels...slightly wrong for some reason), and such that other markdown parser would be ok with it? I tried it into Neovim and some random HTML markdown renderer extension I have and indeed adding a space preserves highlighting, while the dash doesn't. It seems like it doesn't make a difference for Gatsby in one direction or the other, but preserve other renderers

[vkleen]

I like nickel #... 👍 I'll make the change here and update the gatsby config on the website.

[yannham]

Whatever approach you choose for the textinfo string, it's not a blocker.