Add/update a lot of documentation

README.md

@@ -38,16 +38,16 @@ saving a file and to run `do-reformat.sh` when you hit `<F1>`.
 - typescript
 - vue
 
-Python uses `black`; go uses `gofmt`; dart uses `dart format`.  The rest use
-`prettier`.  Adding new programming languages is easy, assuming they have a
-formatter with a dry run mode.
+Out of the box, python uses `isort` and `black`, go uses `gofmt`, and dart
+uses `dart format`.  The rest use `prettier`.  Adding new programming
+languages is easy, assuming they have a formatter with a dry run mode.
 
 # Installation
 
-- Change to the directory where you want to use **would-reformat**:
+- Change to the directory where you want to use `would-reformat`:
   `you@host:~ $ cd ~/devel/my-project`
 - From that directory, call the script `install.sh` in the directory where
-  you have **would-reformat** checked out:
+  you have `would-reformat` checked out:
   `you@host:~/devel/my-project $ ~/src/would-reformat/install.sh`
 
 Be sure to run the installation script from the root of your project's
@@ -65,7 +65,8 @@ This will do the following:
 
 This should work from a checkout wherever you happen to have it.  It doesn't
 need to be in `~/src`.  However, if you remove the checkout, then the symlinks
-will break, so don't do that.  If you rename the checkout, the symlinks will break.
+will break, so don't do that.  If you rename the checkout, the symlinks will
+break.
 
 The directory `bin` with respect to `my-project` however is hardcoded
 (enhancements here are welcome).
@@ -76,6 +77,20 @@ checks whether it is a symlink to `~/src/would-reformat/do-reformat.sh`.
 If it is not, then it just prints a warning rather than attempting to correct
 the situation.
 
+FIXME: Document how to reinstall if the checkout was moved, incompatible
+changes were made, etc.
+
+# Customization
+
+For information on changing how `would-format` handles different files, see
+[CUSTOMIZATION.md](CUSTOMIZATION.md).
+
+
+# Development
+
+If you want to hack on `would-format`, see [DEVELOPMENT.md](DEVELOPMENT.md)
+for more info.
+
 # Troubleshooting
 
 ## nothing works from emacs
@@ -106,21 +121,31 @@ cargoculty.  There should be a more solid basis for this answer.)
 
 The solution seems to be to run `pip install black pipx` somewhere.
 
-# Development
+## I need to use one version of `would-reformat` with one of my projects and another with another
 
-# Wishlist
+With the per-project configuration [see below] this should rarely be
+necessary, but in case it is, one thing you can try is creating different
+`would-reformat` checkouts for different projects.  For example, something
+like this might work:
 
-- 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
+```
+$ ls ~/devel
+new-project1      new-project2     old-and-weird-project1
+$ git clone https://github.com/maw/would-reformat
+$ cd new-project1; ../would-reformat/install.sh
+$ cd ../new-project2; ../would-reformat/install.sh
+$ cd ..
+$ git clone https://github.com/maw/would-reformat would-reformat-for-old-and-weird-project1
+$ cd would-reformat-for-old-and-weird-project1; git checkout vSome-old-tag
+$ cd ../old-and-weird-project1; ../would-reformat-for-old-and-weird-project1/install.sh
+```
 
-# Problems
+ 
+# Similar projects
 
-- It would probably be better if we wrote reformatted code to temp files and
-  atomically renamed them
-- This probably doesn't work on Windows as-is.
-- It doesn't work with tramp.
+If you don't like `would-reformat`'s approach, maybe one or more of these
+would be more suitable.
+
+- https://github.com/purcell/emacs-shfmt/
+- https://github.com/pythonic-emacs/blacken
+- https://github.com/dominikh/go-mode.el