commit d840eb8cb08413c17b9a082f6e099033879c25b1
parent cde0b8cd56d4faae2ed6a276e7baee5666fb0ee1
Author: Daniel Barlow <dan@telent.net>
Date: Fri, 23 Dec 2022 16:19:13 +0000
describe commands and bindings
Diffstat:
1 file changed, 30 insertions(+), 0 deletions(-)
diff --git a/doc/index.md b/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`
+
