update docs

default.nix

@@ -47,9 +47,9 @@ in stdenv.mkDerivation rec {
   ];
   nativeBuildInputs = [
     lua
+    pandoc
     makeWrapper
     copyDesktopItems
-    pandoc
   ];
 
   makeFlags = [ "PREFIX=${placeholder "out"}" ];

doc/index.md

@@ -13,20 +13,55 @@
 Dunlin is a GTK-based Webkit browser which can be extended in (indeed,
 is mostly written in) [Fennel](https://www.fennel-lang.org).
 
-## Hacking
+## Why does the world need another half-assed Webkit browser?
 
-        $ nix-shell
-        nix-shell$ overmind start -D
-        nix-shell$ overmind connect
+It doesn't, really. But me, personally, I think I do. I want
+a browser that lets me easily change keybindings/add commands to do things
+like:
 
+* find the open Fediverse tab and post a message
+* watch a local html file and reload when it changes
+* search the {Lua reference, Ruby docs, GTK docs} for term instead of wading through the the SEO cesspool that is the internet in 2022
+* search in previously "liked" pages for the thing I found three weeks ago,
+instead of ... ditto
+* find the tab that's playing music and pause the player (instead of
+muting it)
+* more stuff I haven't thought of
 
-This starts a Fennel interpreter and a test runner in tmux windows. Use `C-b n`
-to switch between them or `C-b d` to detach.
+Full disclosure: Dunlin today can do none of these things, but if I borrow
+enough design decisions from Emacs, I hope some day it will
 
-        $ fennel dunlin.fnl &
-        $ ./repl.sh
+## Installation and getting started
 
+If you're using Nix, you can run `nix-shell` to pull all the
+dependencies. Otherwise .. Luarocks? Refer to `default.nix` and
+`shell.nix` and obtain:
+
+* All Lua packages listed in any `lua5_3.withPackages` stanza
+* All system packages listed in any `buildInputs` or `nativeBuildInputs`
+ stanzas.
+
+To run the browser,
+
+```sh
+$ fennel dunlin.fnl
+```
 
 Dunlin will open a socket in `$XDG_RUNTIME_DIR` to allow communication
-with a Fennel REPL. The repl.sh script uses
-[socat](http://www.dest-unreach.org/socat/) to connect to it.
+with a Fennel REPL. You can run the `repl.sh` script to connect to it
+with [socat](http://www.dest-unreach.org/socat/).
+
+### Running tests
+
+Tests are in `test/*.fnl`. The test coverage is not 100% nor will it
+ever be, probably: tests exist only for the bits that were hard to
+write (algorithmically complex) and easy to test (not full of UI).
+
+`make watch` will watch the filesystem in this directory and run the
+tests whenever something changes.
+
+### Running everything
+
+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.