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

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

Repl example example:

```nix-repl
nix-shnepl> nope
dope
```

Expression example example:

```nix
null
```

If it evaluates into null then it's good. If it evaluates into anything else it's bad. If it fails to evaluate, it's bad. The idea is that the author will use Nix assertions to prove their points in the example.

In reply to @mightyiam:matrix.org
Sorry, there's no documentation. There are tests for the repl examples and there are tests for the WIP expression examples.
https://github.com/mobusoperandi/eelco/tree/0eb9042220befe188aa4399ffc6615579cebdd5f/crates/eelco/tests

In reply to @mightyiam:matrix.org
Sorry, there's no documentation. There are tests for the repl examples and there are tests for the WIP expression examples.
https://github.com/mobusoperandi/eelco/tree/0eb9042220befe188aa4399ffc6615579cebdd5f/crates/eelco/tests

How does a user specify input, precisely? If I look for example at the Rust doctests page, there's a fair bit there about syntax. There's also the additional constraint that these things exist in doc strings. We don't really/necessarily have docstrings here, so how do I present a list of assertions for a nix repl to check?

What kind of output does does a doc tester produce (is it just a pass/fail, is there a way to extract the LHS and RHS of the input assertions)? Would you find it useful to co-opt the language/structure in the issue linked above, or does it pose unnecessary constraints on your work?

In reply to @mightyiam:matrix.org
I lost you at "input". What's input, please?

In reply to @mightyiam:matrix.org
I lost you at "input". What's input, please?

How does a user specify input, precisely? If I look for example at the Rust doctests page, there's a fair bit there about syntax. There's also the additional constraint that these things exist in doc strings. We don't really/necessarily have docstrings here, so how do I present to the program what is essentially a list of assertions for a nix repl to check?

What kind of output does does a doc tester produce (is it just a pass/fail, is there a way to extract the LHS and RHS of the input assertions)? Would you find it useful to co-opt the language/structure in the issue linked above, or does it pose unnecessary constraints on your work?