In reply to @bzzm3r:matrix.org
I think I understand sufficiently now: "executing sequential steps" here refers to explicit sequencing of computing operations. There is no explicit sequencing of computing operations. Sequencing of computing operations only happens implicitly through specification of data dependencies.

In reply to @bzzm3r:matrix.org
I think I understand sufficiently now: "executing sequential steps" here refers to explicit sequencing of computing operations. There is no explicit sequencing of computing operations. Sequencing of computing operations only happens implicitly through specification of data dependencies.

In reply to @bzzm3r:matrix.org
Sounds good. Currently I'm working on a PR to enable auto-formatting of EBNF in the Nix (reference) manual. (Rather than manually formatting the markdown...)

In reply to @bzzm3r:matrix.org
Sounds good. Currently I'm working on a PR to enable auto-formatting of EBNF in the Nix (reference) manual. (Rather than manually formatting the markdown...)

In reply to @fricklerhandwerk:matrix.org
That would be cool. Just writing down the EBNF in the first place would be way cooler though because the first is cosmetic while the second is essential.

I can do that first quite happily!

But then it won't live in the docs "properly", as it won't be formatted per the contributing instructions. Perhaps it can just live in a side branch, where it can still receive reviews?

In reply to @bzzm3r:matrix.org

I can do that first quite happily!

But then it won't live in the docs "properly", as it won't be formatted per the contributing instructions. Perhaps it can just live in a side branch, where it can still receive reviews?

In reply to @bzzm3r:matrix.org
(The other thing I was noticing while writing out the EBNF: it would be very, very nice to be able to link between meta-identifiers. So that would be missing in the first pass too, hopefully not to the chagrin of reviewers.)

In reply to @bzzm3r:matrix.org
Yeah, the block quotes are what I am referring to: backticking each piece..., putting >

fricklerhandwerk: https://github.com/NixOS/nix/pull/9783

I forced myself to stay small. Tried to put most of that aside to prioritize "keep it small" and "get feedback fast and early"; punted plenty to todo lists, and the "Draft" status of the PR.

fricklerhandwerk: https://github.com/NixOS/nix/pull/9783

I forced myself to stay small. Tried to put most of what I felt would be necessary in a final product aside to prioritize "keep it small" and "get feedback fast and early"; punted plenty to todo lists, and the "Draft" status of the PR.

Am I right in thinking the next part of this PR should be a push which has a guide to the EBNF we plan on using? As much as possible, I want to eliminate ... and use repetition operators.

(Ideally, we would have "raw" EBNF live in a bunch of separate files, which are processed and formatted as markdown, then inserted into the guide for presentation. These files can then also be used to drive parsers. During the processing stage, inter-linking would be performed as well, between the EBNF, and those regions of the documentation that mention something from the EBNF.)

Am I right in thinking the next part of this PR should be a push which has a guide to the EBNF we plan on using? Especially because: as much as possible, I want to eliminate ... and use repetition operators.

(Ideally, we would have "raw" EBNF live in a bunch of separate files, which are processed and formatted as markdown, then inserted into the guide for presentation. These files can then also be used to drive parsers. During the processing stage, inter-linking would be performed as well, between the EBNF, and those regions of the documentation that mention something from the EBNF.)

are there any downsides to using nix-repl output directly as examples? For example, in the language reference we see the example:

''
  This is the first line.
  This is the second line.
    This is the third line.
''

(is the same as)

"This is the first line.\nThis is the second line.\n  This is the third line.\n"

This could also be presented as:

nix-repl> indentedString =   ''
              This is the first line
              This is the second line
                This is the third line
            '' # "empty-line", it has no non-whitespace characters

nix-repl> indentedString
"This is the first line\nThis is the second line\n  This is the third line\n"

are there any downsides to using nix-repl output directly as examples? For example, in the language reference we see the example:

''
  This is the first line.
  This is the second line.
    This is the third line.
''

(whole bunch of language explaining "this is the same as"....)

"This is the first line.\nThis is the second line.\n  This is the third line.\n"

This could also be presented as:

nix-repl> indentedString =   ''
              This is the first line
              This is the second line
                This is the third line
            '' # "empty-line", it has no non-whitespace characters

nix-repl> indentedString
"This is the first line\nThis is the second line\n  This is the third line\n"

My opinion on this somewhat technically unqualified because I haven’t done concrete work on it, but I see a few theoretical advantages to have pairs of code blocks for input/output:

• No fancy parsing needed, can be hooked into markdown processors. On nix.dev we have highlighting of expression/value pairs which demonstrate this.
• Easier to type, obvious how to copy paste
• No implicit state possible or required. State bad.

Generally documentation (and everything, really) should be low-tech so it’s easy to contribute to and understand how it works. That is, it shouldn’t do anything clever, because it will be hard to change for most people if it does, if only because it requires time to figure out. And time is a very scarce resource.