From 1ed617565691b70f312f25ee9fe611ce682fd90f Mon Sep 17 00:00:00 2001
From: Michael Wolf <maw@pobox.com>
Date: Thu, 13 Oct 2022 19:29:33 -0500
Subject: [PATCH] Update README.md

---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/README.md b/README.md
index 456c0de..9c9c331 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,44 @@ would-reformat - automatic reformatting for emacs without being annoying
 
 # Motivation
 
+I've never liked it when a text editor formats code for me without my asking.
+I don't like it when the editor uses cheap heuristics (indent a new line to
+match the previous one?  blah!) and I don't like it when the editor shells out
+to one of the new generation of automatic code formatters.
+
+But I don't enjoy formatting code by hand either.  Who does?
+
+This is my solution: some shell scripts and some emacs lisp code.
+
+The shell script `would-reformat.sh` takes a file's full path as
+its argument.  It tells you if that file would be reformatted.
+
+The shell script `do-reformat.sh` takes a file's full path as its argument.  It
+reformats the file.
+
+Finally, there is some rudimentary machinery to run `would-reformat.sh` when
+saving a file and to run `do-reformat.sh` when you hit `<F1>`.
+
+## Supported programming languages and file formats
+
+- python
+- go
+- javascript
+- typescript
+- vue
+- css
+- php
+- html
+- jsx
+- tsx
+- css
+- cscc
+- sh
+
+Python and go use `black` and `gofmt` respectively.  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**:
@@ -10,6 +48,9 @@ would-reformat - automatic reformatting for emacs without being annoying
   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
+directory, not a subdirectory.
+
 This will do the following:
 
 - create the directory `~/devel/my-project/bin` if it does not exist
@@ -35,6 +76,17 @@ the situation.
 
 # Troubleshooting
 
+## nothing works from emacs
+
+Be sure to run the install script from your project's root as determined by
+`(projectile-project-root)`.
+
+## problems with nvm, pyenv, goenv, etc
+
+The problem might be that their shims aren't in your `PATH`.  To work around
+this sort of problem I run emacs from a wrapper script that ensures the shims
+are loaded in my `PATH`.
+
 ## Running prettier is slow
 
 The scripts by default call `npx prettier` with some arguments.  If you call
@@ -48,6 +100,15 @@ The solution, therefore, seems to be to say `yarn add --dev prettier` (or
 (This seems to work for me, but it is admittedly still uncomfortably
 cargoculty.  There should be a more solid basis for this answer.)
 
+## problems running black
+
+The solution seems to be to run `pip install black pipx` somewhere.
 
 # Development
 
+# Wishlist
+
+- Generalize this beyond emacs
+- Add support for more programming languages and file formats
+- Clean up shell script code
+- Be better at "just working"