it's a huge diff, but it doesn't change that much:
- start with a `mkDerivation` scaffold that uses `src = ./.`
- this saves the detour with an intentionally broken derivation and
the explanation it requires
- it provides an opportunity to drop another bit of information about
`toSource`, namely that it always creates a directory in the store
- use two source files to start with, otherwise the "try one file, then
the whole directory" approach is not well-motivated
- this obviates spending words on justifying a contrived example,
it flows more naturally
- mostly use diffs to highlight the changes
- this is not a strong proposal
- the explicit-include-union example starts over, so the build-up is
manageable
- it works out quite nicely overall: since there is sufficient repetition
where we reasonably expect learners to have gotten the point,
the last two sections can be reduced just to the relevant bit.
- rename section headers to match functions, not domain problems
- one exception is the split of the two union approaches, which should
be okay
- reword all instructions to be imperative
the review made clear how powerful and elegant the library is, and that
the tutorial is utterly well-structured and ordered in a way that feels
natural and covers all important aspects!
great job!
- readers may not have literally seen the examples
- "combinators" isn't even used in reference documentation and is
a potentially scary word. it doesn't even convey additional meaning
here, since combination ("two together") and composition ("put
together") are almost the same, composition being more general.
this follows the convention established in other tutorials.
also arguably, this file is *not* the package per se, but simply contains a representation of build instructions.
brackets in console output invoke weird associations, as they could be
syntactically relevant. bare ellipses are unusual enough one can expect
them to be intuitively parsed as artificial.
