docs: extending the usage of EBNF in doc/manual/language

[bzm3r]

Motivation

Decrease the rambling nature of existing documentation around language primitives, by describing their syntax using "EBNF".

Since this is a reference documentation, some allowance can be made for precision over minimizing pre-requisite knowledge. Still, to accommodate ease-of-access, a guide should be provided which clearly explains the EBNF syntax used by this reference, along with some examples.

Furthermore, careful attention should b paid to formatting, and interlinking between concepts. This will likely require the inclusion of some tools.

Context

This is a Draft PR. It does not include many important things, as listed in Required for removal of draft status.

It is meant to provide a small (as in, relatively easy-to-review, isolated) "proof-of-concept" of what an English to EBNF documentation change would look like.

Currently, the index.md has table listing "various examples". This table would be shortened to a list that links to the relevant documentation on each primitive.

Required for removal of draft status

• A guide to the EBNF used in the reference
• removal of repetition by using include to repeat identical fragments
• As much inter-linking as possible (with the help of <a> tags)
• Complete glossary
• Complete examples
• Correct formatting
• Add references to this documentation in lexer/parser code documentation

Priorities and Process

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

[roberth]

While it is reference documentation, the audience is largely Nix users, who I estimate to be interested in semantics more so than syntax. For that reason I believe it'd be better to move definitions of syntax to a separate page, which the language pages can refer to with links.

(with the help of tags)

We normally use markdown links and markdown anchors; see e.g. https://github.com/NixOS/nix/blob/7e5fa5c25ce585da5399038bc92980fddbb65d8b/doc/manual/src/glossary.md?plain=1

Could you add comments to the lexer and parser, which EBNF declarations they map to? That will also serve as a reminder to keep them in sync when making (rare) changes.

[bzm3r]

@roberth

• markdown links/anchors: thanks for the example link. That is helpful to know. Linking of this sort is not part of the CommonMark spec, right? Nor does it seem to be an mdBook thing? Also, I do see <a> style tags in the documentation too; is that a holdover from before markdown style links/anchors could be processed?

• adding comments to the lexer and parser: that's a great idea. I'll put it down as part of TODO.

[roberth]

• Linking of this sort is not part of the CommonMark spec, right?

All I know is our section about links, and it doesn't say anything about the specific syntax.

Maybe @fricklerhandwerk knows why [foo]{#anchor-foo} works?

holdover

I suppose so. I wasn't aware that we have a mix that includes <a> for links.

[fricklerhandwerk]

why [foo]{#anchor-foo} works?

This is mdBook's markdown extension.

@bzm3r for the sake of getting things merged timely I suggest, rather than further expanding the scope of this PR, that you add only the syntax declarations to the existing section on strings.

Large changes are hard to review and easy to stall by getting hung up on details. And long-standing PRs accumulate overhead for everyone.

You can always add more stuff later or move things around (and moving things requires some care to avoid breaking URLs).

[fricklerhandwerk]

Related: #7259