From 44fd5a350fa12b62abe353749a3c07b4f3aa59f1 Mon Sep 17 00:00:00 2001 From: Michael Wolf Date: Wed, 30 Oct 2024 21:59:10 -0600 Subject: [PATCH] Improve documentation slightly --- CUSTOMIZATION.md | 17 +++++++++-------- DEVELOPMENT.md | 10 +++++----- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/CUSTOMIZATION.md b/CUSTOMIZATION.md index 5244bba..6c959b8 100644 --- a/CUSTOMIZATION.md +++ b/CUSTOMIZATION.md @@ -40,19 +40,19 @@ exit 0 [here](./examples/custom-sniffer).) Now, if you run this script against a file that ends in `.pl` or `.ts`, -`would-reformat` will not treat the file as perl or typescript as usual, but -instead as prolog or a qt-translation file. But if you run this script -against a file that ends in `.py` then it'll continue to be treated as python -as usual. +`would-reformat` will not treat the file as perl or typescript, which is what +happens by default, but instead as prolog or a qt-translation file. But if +you run this script against a file that ends in `.py` then it'll continue to +be treated as python as usual. You can perform arbitrarily sophisticated checks here. They're not limited to file names or extensions. You can take paths into account. You can can even take files' contents into account. But do keep in mind that this program will be run often. If it's slow you'll be frustrated by it. -Don't forget that this program can be written in something other than shell, -in case that's easier for you or if performance is a serious concern. It -doesn't actually need to be a "script". +This program can be written in something other than shell. This might make +implementation easier, and it might be worthwhile if performance is a serious +concern. It doesn't actually need to be a "script". Finally, keep in mind that if `would-reformat`'s defaults work for you, there is no need to have this file at all. @@ -67,7 +67,8 @@ include the `/` character. `would-reformat` doesn't care if you use uppercase, but some case-preserving filesystems make things difficult. It must not output `custom-sniffer`. If there is a hitherto unknown -programming language named "custom sniffer" you'll have to output something else. +programming language named "custom sniffer" you'll have to output something +else. ## Return values diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 349371e..51d5749 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -8,8 +8,8 @@ following tools installed: - [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. +shfmt (please use it with `-i 4`), and when relevant come with new tests and +pass them. 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. @@ -24,8 +24,8 @@ 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 - makes things even worse for them. Use English correctly and, to the - extent possible, unambiguously. + makes things even worse for them. Use English correctly and, to the extent + possible, unambiguously. ## Non-goals @@ -47,7 +47,7 @@ request anyway and we can work on getting it up to snuff. 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`). + 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?