branch: externals/substitute
commit 591d6df15b485a697a26fcc6cb3e0ba1cfc57cdb
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Expand README; add video demo
---
README.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 74 insertions(+), 14 deletions(-)
diff --git a/README.md b/README.md
index e879fbc2fe..b119573262 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,72 @@
# Substitute (substitute.el)
-Read: <https://protesilaos.com/codelog/2023-01-14-emacs-substitute-package/>.
-
Efficiently replace targets in the buffer or context.
-Sample configuration:
+**Video demo:**
<https://protesilaos.com/codelog/2023-01-16-emacs-substitute-package-demo/>
+
++ Package name (GNU ELPA): `substitute`
++ Git repo on SourceHut: <https://git.sr.ht/~protesilaos/substitute>
+ - Mirrors:
+ + GitHub: <https://github.com/protesilaos/substitute>
+ + GitLab: <https://gitlab.com/protesilaos/substitute>
++ Mailing list: <https://lists.sr.ht/~protesilaos/general-issues>
++ Backronym: Some Utilities Built to Substitute Targets Independent of
+ Their Utterances, Thoroughly and Easily.
+
+## Overview
+
+Substitute is a set of commands that perform text replacement (i)
+throughout the buffer, (ii) limited to the current definition (per
+`narrow-to-defun`), (iii) from point to the end of the buffer, and
+(iv) from point to the beginning of the buffer.
+
+These substitutions are meant to be as quick as possible and, as such,
+differ from the standard `query-replace` (which I still use). The
+provided commands prompt for substitute text and perform the
+substitution outright.
+
+The substitution prompt mentions the target-to-be-substituted. It is
+possible to use the "future history" at this prompt (by typing `M-n`
+with the default key bindings for the `next-history-element` command).
+This populates the prompt with the text of the target. As such, if we
+want to operate on `FOO` to make it `FOO-BAR`, we use `M-n` and then
+append `-BAR`.
+
+By default, the design is visually austere: the substitution prompt
+informs the user about the target but otherwise does not highlight
+anything. The post-substitution stage is also silent, with no report
+on how many occurrences were replaced. This can be changed so that
+the substitution prompt highlights occurrences (like `isearch`) and
+the post-substitution stage prints an informative message on what
+changed and where. Refer to the "Sample configuration" further below.
+
+The substitution commands behave the same way except for their scope
+of application. What they have in common is how they identify the
+target of the substitution: it is either the symbol at point or the
+text within the boundaries of the active region. The differences in
+scope are as follows:
+
+1. `substitute-target-in-buffer`: Substitute the target across the
+ entire buffer.
+2. `substitute-target-in-defun`: Substitute the target only in the
+ current definition (per `narrow-to-defun`).
+3. `substitute-target-below-point`: Substitute the target from point
+ to the end of the buffer (alias
+ `substitute-target-to-end-of-buffer`).
+4. `substitute-target-above-point`: Substitute the target from point
+ to the beginning of the buffer (alias
+ `substitute-target-to-beginning-of-buffer`).
+
+## Sample configuration
```elisp
(require 'substitute)
-;; If you like visual feedback on matching target. Default is nil.
+;; If you like visual feedback on the matching target. Default is nil.
(setq substitute-highlight t)
-;; If you want a message reporting the matches that changed. We don't
-;; do it by default
+;; If you want a message reporting the matches that changed in the
+;; given context. We don't do it by default.
(add-hook 'substitute-post-replace-hook #'substitute-report-operation)
;; We do not bind any keys. This is just an idea. The mnemonic is
@@ -25,11 +78,18 @@ Sample configuration:
(define-key map (kbd "M-# b") #'substitute-target-in-buffer))
```
-+ Package name (GNU ELPA): `substitute` (not available yet)
-+ Git repo on SourceHut: <https://git.sr.ht/~protesilaos/substitute>
- - Mirrors:
- + GitHub: <https://github.com/protesilaos/substitute>
- + GitLab: <https://gitlab.com/protesilaos/substitute>
-+ Mailing list: <https://lists.sr.ht/~protesilaos/general-issues>
-+ Backronym: Some Utilities Built to Substitute Targets Independent of
- Their Utterances, Thoroughly and Easily.
+## Why this instead of `multiple-cursors` or `iedit`
+
+What I do not like about those packages is that they are visually
+"busy". Oftentimes, I want to perform a replacement in some context
+with multiple occurrences of a given target. Using either of those
+echoes my input across all occurrences, resulting in a dance of sorts
+within the buffer as texts moves around. I find that disorienting.
+Beside that, I do not need the visual feedback as I already know what
+I want to do: the default minimalist presentation of `substitute`
+provides all the information I need.
+
+Otherwise, this package is small and limited in scope. Beside
+`substitute`, I also use, keyboard macros, `query-replace`, and,
+rarely `rectangle-mark-mode` in tandem with `string-rectangle`. I
+have no need for `multiple-cursors` or `iedit`.
