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.

In reply to @fricklerhandwerk:matrix.org

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.

Based on your input: https://github.com/NixOS/nix.dev/issues/864

I am not sure if this qualifies as low-tech. Maybe it does because all it uses is a CLI tool. With modern tools, it is easy to make a heavily automatically documented CLI tool (e.g. if using Rust: can use bpaf/clap both convert doc strings into CLI help strings).

However, low-tech ought to be measured against cost-of-manual-work? In this particular case: cost of copying+pasting, verifying output expression against expectation, validating that examples remain valid across Nix updates.

In reply to @fricklerhandwerk:matrix.org

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.

Based on your input: https://github.com/NixOS/nix.dev/issues/864

I am not sure if this qualifies as low-tech. Maybe it does because all it uses is a CLI tool. With modern tools, it is easy to make a heavily automatically documented CLI tool (e.g. if using Rust: can use bpaf/clap both convert doc strings into CLI help strings).

However, low-tech ought to be measured against cost-of-manual-work? In this particular case: cost of copying+pasting, verifying output expression against expectation, validating that examples remain valid across Nix updates.

(Regardless: not a "must-do". Only a "could-do". Happy to execute on a draft version, if time can be made for its review, with full understanding that it will likely not be accepted.)

Based on your input: https://github.com/NixOS/nix.dev/issues/864

I am not sure if this qualifies as low-tech. Maybe it does because all it uses is a CLI tool. With modern tools, it is easy to make a heavily automatically documented CLI tool (e.g. if using Rust: can use bpaf/clap both convert doc strings into CLI help strings).

However, low-tech ought to be measured against cost-of-manual-work? In this particular case: cost of copying+pasting, verifying output expression against expectation, validating that examples remain valid across Nix updates.

(Regardless: not a "must-do". Only a "could-do". Happy to execute on a draft version, if time can be made for its review, with full understanding that it will likely not be accepted. Will not create a draft version if it only adds to review burden.)

Based on your input: https://github.com/NixOS/nix.dev/issues/864

I am not sure if this qualifies as low-tech. Maybe it does because all it uses is a CLI tool. With modern tools, it is easy to make a heavily automatically documented CLI tool (e.g. if using Rust: can use bpaf/clap both convert doc strings into CLI help strings). However, it is still a tool, and the use of a tool necessarily moves us farther away from low-tech.

However, low-tech ought to be measured against cost-of-manual-work? In this particular case: cost of copying+pasting, verifying output expression against expectation, validating that examples remain valid across Nix updates.

(Regardless: not a "must-do". Only a "could-do". Happy to execute on a draft version, if time can be made for its review, with full understanding that it will likely not be accepted. Will not create a draft version if it only adds to review burden.)

In reply to @mightyiam:matrix.org
bzm3r: the doctester is coming along