describe commands and bindings

doc/index.md

@@ -65,3 +65,33 @@ tests whenever something changes.
 There's a `Procfile` that starts the test runner and a Fennel repl and
 probably in time some other useful things. I use it with [Overmind](https://github.com/DarthSim/overmind#readme) - `overmind start -D;  overmind connect`
 to create a tmux session.
+
+## Customizing
+
+_This is all quite fluid right now and I reserve the right to change
+things_. In particular, I anticipate the need to bind to non-key events
+(mouse events, on-screen buttons, touch gestures)
+
+(Among) the concepts you need to know here are "commands" and "bindings".
+
+* A "command" is a chunk of code that may be invoked interactively,
+plus a descrition of the parameters it needs and their default values.
+For example, `visit-location` needs a `url` parameter for the location
+and a `buffer` parameter that says which tab should visit it.
+
+* A "binding" is a sequence of keystrokes which map to a command: it
+may supply zero or more parameter values to the command. For example,
+(as of git commit cde0b8cd56d; YMMV if you're reading this significantly
+before or after 2022-12-23) the `g` binding invokes `visit-location`
+with the `buffer` parameter set to `main`, and the `url` parameter
+unset.
+
+When a command is invoked without all parameter values, Dunlin will
+prompt for each missing parameter in the "commander" text entry widget.
+A command with no binding may be invoked by pressing `M-x` (hold down
+the "meta" or "alt" key and press `x`) and then typing the command name.
+
+To see how commands are implemented, read the code in `command.fnl`.
+There is a simple keymap in `dunlin.fnl`, and you can see the details
+of how keymaps work in `keymap.fnl`
+