From 970a92def990f168a0883738c5afafce088cd688 Mon Sep 17 00:00:00 2001 From: Michael Wolf Date: Wed, 3 Apr 2024 11:26:30 -0600 Subject: [PATCH] Update some docs --- CUSTOMIZATION.md | 8 ++++---- DEVELOPMENT.md | 10 ++++++++-- README.md | 12 ++++++++---- 3 files changed, 20 insertions(+), 10 deletions(-) diff --git a/CUSTOMIZATION.md b/CUSTOMIZATION.md index ee800ee..5244bba 100644 --- a/CUSTOMIZATION.md +++ b/CUSTOMIZATION.md @@ -168,12 +168,12 @@ As output, this script should emit whatever the programs it calls emit. - 255: error internal to the script in question (FIXME: Unsurprisingly, `gofmt` is the only tool I've tested so far that gets -this right. That a file should be reformatted isn't an exceptional condition, -so there's no good reason to signal failure here. +this right. It isn't an exceptional condition when a file should be +reformatted, so there's no good reason to signal failure here. Even less unsurprisingly, Laravel pint gets it worse than all the others I -checked; it doesn't distinguish misformatted files from files with actual -syntax errors. +checked; it doesn't distinguish files that need to be reformatted from files +with actual syntax errors. Anyway, `gofmt` is the obviously the model to follow. So we should probably drop `1`.) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index a7f0efd..349371e 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -24,11 +24,13 @@ request anyway and we can work on getting it up to snuff. - 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 + makes things even worse for them. Use English correctly and, to the extent possible, unambiguously. ## Non-goals +- We don't want to do anything with warnings etc that aren't specifically + formatting-related # Wishlist @@ -46,12 +48,16 @@ request anyway and we can work on getting it up to snuff. 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`). +- Create a nix setup that includes all the tools as fallbacks +- Cache file type sniffing results? How? # 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. + should emit diffs rather than working silently as they currently do. The + rationale is that this makes it a lot easier to atomically apply two or more + fixers. - 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. diff --git a/README.md b/README.md index 1f3ba93..6aca212 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -would-reformat - automatic reformatting for emacs without being annoying +would-reformat - automatic reformatting for emacs (and maybe other editors) without being annoying # Motivation @@ -38,9 +38,13 @@ saving a file and to run `do-reformat.sh` when you hit ``. - typescript - vue -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. +Out of the box, for python we use `isort` and `black`, for go we use `gofmt`, +for dart we use `dart format`, for rust we use `rustfmt`, and for everything +else we use `prettier`. + +Adding suuport for other programming languages is easy, assuming they have a +formatter with a dry run mode. And even if they don't it shouldn't be that +bad. # Installation