Add/update a lot of documentation

DEVELOPMENT.md

@@ -0,0 +1,66 @@
+# Dependencies
+
+In addition to a fairly recent version of bash, it's helpful to have the
+following tools installed:
+
+- [shunit2](https://github.com/kward/shunit2)
+- [shellcheck](https://www.shellcheck.net/)
+- [shfmt](https://github.com/mvdan/sh)
+
+In general, code should pass shellcheck without warnings, be formatted with
+shfmt (please use it with `-i 4`), and come with new tests and pass them when
+relevant.
+
+If any of this causes you trouble, don't worry.  Please submit your pull
+request anyway and we can work on getting it up to snuff.
+
+# General goals and non-goals
+
+## Goals
+
+- Be as batteries-included as possible.  Go out of our way to just work, even
+  if not entirely optimally, in as many situations as possible.
+- Support "relatively isolated" projects.
+- Be easy to configure.
+- Be clearly documented.  Remember that many programmers are working in
+  high-stress situations.  Documentation that is incomplete, unclear, or cute
+  will make things even worse for them.  Use English correctly and, to the
+  extent possible, unambiguously.
+
+## Non-goals
+
+
+# Wishlist
+
+- Generalize this beyond emacs
+- In emacs, provide a minor mode or something to use instead of
+  `.dir-locals.el`, which I've always found to be very fragile
+- Add support for more programming languages and file formats
+- Clean up shell script code
+- Be better at "just working"
+- Make it easy to add "private" and alternate formatters
+- It should signal more clearly when the file has a syntax error, subject to
+  the limitations set by third party tools.
+- Would global (per-user) customization be useful?  My guess is that it'd
+  probably be more confusing than helpful but I'm not wedded to this
+  conclusion.
+- Write a doctor command to identify potential issues (you'd probably run it
+  similarly to how you run the install script, but `s/install/doctor`).
+
+# Problems
+
+- It would probably be better if we wrote reformatted code to temp files and
+  atomically renamed them.  This might mean that the tool-specific programs
+  should emit diffs rather than working silently as they currently do.
+- It probably doesn't work on Windows as-is.
+- There are probably some Linuxisms and maybe even some recentbashisms.
+- It doesn't work with tramp.
+- As long as it's written in shell, it's always going to be a little bit slow
+  and, of course, fairly difficult to hack on.  If the bulk of it were
+  rewritten in, say, go, then some problems would go away and some new ones
+  would be created.  On balance I'm not sure if it's a good idea or not, but
+  I'm tempted.
+- Stop writing files to `$PROJECT_ROOT/bin`; use
+  `$PROJECT_ROOT/.would-reformat/bin` instead.
+- `PROJECT_ROOT` and `WF_ROOT` are probably too generic.  Consider prefixing
+  them, maybe with `WOULD_FORMAT_`.