I want to make the readme more aimed at people interested in the tool
and project in general, not necessarily at developers hacking on RCL
itself. Let's move that to a separate manual section, since there is
already a development section in there.
There are more and more steps every time, without some checklist, one
day I'm going to forget or mess up one of these steps.
It could be a bit more automated, but I don't want to add a critical
dependency on e.g. GitHub Actions, and having some written playbook is
better than having to keep it all in my head.
I decided, after going through a few iterations of a blog post that
explains the trade-offs, to have only a single Number type, and to
remove Int. This is an invasive change, let's start with the docs
because those are somewhat easier.
I realized yesterday, the interaction between Int and Float creates a
rabbit hole of subtleties. I wrote down some thoughts on GitHub, but
important decisions like these are best kept under source control.
I just encountered "Reduce Cognitive Load" in a comment on Hacker News
and it fits the acronym very well, I'm going to keep a list of possible
meanings of the name "RCL".
I was struggling with this before, but now I found the problem:
tree-sitter calls CC, and I had CC=clang, but somehow then I get an
executable that links against some files in the Nix store, but also
against a libstdc++.so.6 which is nowhere to be found. When I set CC
to a GCC that Nix provides, everything works fine.
This is also running ahead to the static type checks that I already
implemented on top of this branch, so the documentation does not reflect
so much the work preceding this commit, as the plans for how the type
system will work.
I realized I'm often complaining about tools for not having good
documentation. I tried to get started with D for the Advent of Code
for example, and although it has a reference, I couldn't find good
introductory material. RCL doesn't even have an introduction, so let's
fix that.
This also includes docs for the CLI for sandboxing modes, which at
this point are completely hypothetical, as well as relative and
workdir-relative import paths, which are also not implemented. One
might call it "readme-driven development".
And we have syntax highlighting in the docs! So nice that this is even
possible with Nix (even though it took some fiddling to get it to work),
it would be basically impossible without.
