branch: externals/substitute
commit e2663b288fb8a7adb94060014f9dd61b842717a0
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
Update the manual to mention the three new commands and make some stylistic
refinements
---
README.org | 228 +++++++++++++++++++++++++++++++++++--------------------------
1 file changed, 132 insertions(+), 96 deletions(-)
diff --git a/README.org b/README.org
index ec26cfe08a..7afc1e3411 100644
--- a/README.org
+++ b/README.org
@@ -45,39 +45,119 @@ the GNU ELPA machinery automatically generates an Info
manual out of it.
#+toc: headlines 8 insert TOC here, with eight headline levels
+* Installation
+:PROPERTIES:
+:CUSTOM_ID: h:4943ebc8-45e5-4352-8d51-9a09efa16b74
+:END:
+#+cindex: Installation instructions
+
+** GNU ELPA package
+:PROPERTIES:
+:CUSTOM_ID: h:ab97c462-01cc-408a-adf2-aadd87a22e90
+:END:
+
+The package is available as ~substitute~. Simply do:
+
+: M-x package-refresh-contents
+: M-x package-install
+
+And search for it.
+
+GNU ELPA provides the latest stable release. Those who prefer to follow
+the development process in order to report bugs or suggest changes, can
+use the version of the package from the GNU-devel ELPA archive. Read:
+https://protesilaos.com/codelog/2022-05-13-emacs-elpa-devel/.
+
+** Manual installation
+:PROPERTIES:
+:CUSTOM_ID: h:7fbd9efd-284a-41fb-bbfa-8e28f102e78e
+:END:
+
+Assuming your Emacs files are found in =~/.emacs.d/=, execute the
+following commands in a shell prompt:
+
+#+begin_src sh
+cd ~/.emacs.d
+
+# Create a directory for manually-installed packages
+mkdir manual-packages
+
+# Go to the new directory
+cd manual-packages
+
+# Clone this repo, naming it "substitute"
+git clone https://github.com/protesilaos/substitute substitute
+#+end_src
+
+Finally, in your =init.el= (or equivalent) evaluate this:
+
+#+begin_src emacs-lisp
+;; Make Elisp files in that directory available to the user.
+(add-to-list 'load-path "~/.emacs.d/manual-packages/substitute")
+#+end_src
+
+Everything is in place to set up the package.
+
+* Sample configuration
+:PROPERTIES:
+:CUSTOM_ID: h:e8691728-79b2-4b37-b6ce-e29a4cd9114f
+:END:
+
+#+begin_src emacs-lisp
+(use-package substitute
+ :ensure t
+ :config
+ ;; Set this to nil if you do not like visual feedback on the matching
+ ;; target. Default is t.
+ (setq substitute-highlight nil)
+
+ ;; Set this to t if you want to always treat the letter casing
+ ;; literally. Otherwise each command accepts a `C-u' prefix
+ ;; argument to do this on-demand.
+ (setq substitute-fixed-letter-case t)
+
+ ;; 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-functions #'substitute-report-operation)
+
+ ;; Use C-c s as a prefix for all Substitute commands.
+ (define-key global-map (kbd "C-c s") #'substitute-prefix-map))
+#+end_src
+
* Overview
:PROPERTIES:
:CUSTOM_ID: h:beae1a59-81ae-41ad-803b-f08caa03732b
:END:
-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.
+Substitute is a set of commands that perform text replacement for the
+symbol at point (i) throughout the buffer, (ii) limited to the current
+definition or outline, (iii) from point to the end of the buffer, and
+(iv) from point to the beginning of the buffer. Variations of these
+are also available ([[#h:577fa565-b43a-4e8a-939a-5b08837c1cb1][Substitutions
by their scope of application]]).
+[ Variations are available as part of {{{development-version}}}. ]
These substitutions are meant to be as quick as possible and, as such,
-differ from the standard ~query-replace~ (which I still use). The
+differ from the standard ~query-replace~ (which I still use). The
provided commands prompt for substitute text and perform the
-substitution outright.
+substitution outright against the symbol at point.
-The substitution prompt mentions the target-to-be-substituted. It is
-possible to use the "future history" at this prompt (by typing ~M-n~
+The substitution prompt mentions the thing-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
+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=.
-#+vindex: substitute-highlight
-By default, the substitution prompt informs the user about the target
-and highlights matches in the given scope (what the current command
-will substitute). Highlights can be disabled by setting the user
-option ~substitute-highlight~ to nil.
+** Substitutions by their scope of application
+:PROPERTIES:
+:CUSTOM_ID: h:577fa565-b43a-4e8a-939a-5b08837c1cb1
+:END:
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:
+of application ([[#h:563f265f-c904-47f5-93c7-3d0e315fca33][User options for
the substitution commands]]). 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:
#+findex: substitute-target-in-buffer
1. ~substitute-target-in-buffer~: Substitute the target across the
@@ -97,6 +177,40 @@ scope are as follows:
4. ~substitute-target-above-point~: Substitute the target from point
to the beginning of the buffer (alias
~substitute-target-to-beginning-of-buffer~).
+#+findex: substitute-target-in-outline
+5. ~substitute-target-in-outline~: Substitute the target within the
+ boundaries of the current outline level. In Org mode, for example,
+ the current outline is the heading plus its paragraph text but not
+ the subheadings and their text. In programming modes the outline
+ might be the same as the current definition, or could be a longer
+ stretch of text. It depends on the buffer-local value of the
+ variable ~outline-regexp~. [ The ~substitute-target-in-outline~ is
+ part of {{{development-version}}}. ]
+
+#+findex: substitute-target-in-page
+6. ~substitute-target-in-page~: Substitute the target within the
+ boundaries of the current page. A page is demarcated by the
+ buffer-local value of the variable ~page-delimiter~. [ The command
+ ~substitute-target-in-page~ is part of {{{development-version}}}. ]
+
+#+findex: substitute-target-in-defun-and-below
+7. ~substitute-target-in-defun-and-below~: Substitute the target
+ within the boundaries of the current definition only from point
+ onwards. [ This is part of {{{development-version}}}. ]
+
+** User options for the substitution commands
+:PROPERTIES:
+:CUSTOM_ID: h:563f265f-c904-47f5-93c7-3d0e315fca33
+:END:
+
+These are applicable to all our commands
([[#h:577fa565-b43a-4e8a-939a-5b08837c1cb1][Substitutions by their scope of
application]]).
+
+#+vindex: substitute-highlight
+By default, the substitution prompt informs the user about the target
+and highlights matches in the given scope (what the current command
+will substitute). Highlights can be disabled by setting the user
+option ~substitute-highlight~ to nil.
+
#+vindex: substitute-fixed-letter-case
All of the aforementioned commands accept an optional prefix argument
(=C-u= with the default key bindings). This passes the =FIXED-CASE=
@@ -141,84 +255,6 @@ bindings. To change those, use something like this:
(define-key substitute-prefix-map (kbd "s") #'substitute-target-below-point)
#+end_src
-* Installation
-:PROPERTIES:
-:CUSTOM_ID: h:4943ebc8-45e5-4352-8d51-9a09efa16b74
-:END:
-#+cindex: Installation instructions
-
-** GNU ELPA package
-:PROPERTIES:
-:CUSTOM_ID: h:ab97c462-01cc-408a-adf2-aadd87a22e90
-:END:
-
-The package is available as ~substitute~. Simply do:
-
-: M-x package-refresh-contents
-: M-x package-install
-
-And search for it.
-
-GNU ELPA provides the latest stable release. Those who prefer to follow
-the development process in order to report bugs or suggest changes, can
-use the version of the package from the GNU-devel ELPA archive. Read:
-https://protesilaos.com/codelog/2022-05-13-emacs-elpa-devel/.
-
-** Manual installation
-:PROPERTIES:
-:CUSTOM_ID: h:7fbd9efd-284a-41fb-bbfa-8e28f102e78e
-:END:
-
-Assuming your Emacs files are found in =~/.emacs.d/=, execute the
-following commands in a shell prompt:
-
-#+begin_src sh
-cd ~/.emacs.d
-
-# Create a directory for manually-installed packages
-mkdir manual-packages
-
-# Go to the new directory
-cd manual-packages
-
-# Clone this repo, naming it "substitute"
-git clone https://github.com/protesilaos/substitute substitute
-#+end_src
-
-Finally, in your =init.el= (or equivalent) evaluate this:
-
-#+begin_src emacs-lisp
-;; Make Elisp files in that directory available to the user.
-(add-to-list 'load-path "~/.emacs.d/manual-packages/substitute")
-#+end_src
-
-Everything is in place to set up the package.
-
-* Sample configuration
-:PROPERTIES:
-:CUSTOM_ID: h:e8691728-79b2-4b37-b6ce-e29a4cd9114f
-:END:
-
-#+begin_src emacs-lisp
-(require 'substitute)
-
-;; Set this to nil if you do not like visual feedback on the matching
-;; target. Default is t.
-(setq substitute-highlight nil)
-
-;; Set this to t if you want to always treat the letter casing
-;; literally. Otherwise each command accepts a `C-u' prefix
-;; argument to do this on-demand.
-(setq substitute-fixed-letter-case t)
-
-;; 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-functions #'substitute-report-operation)
-
-;; Use C-c s as a prefix for all Substitute commands.
-(define-key global-map (kbd "C-c s") #'substitute-prefix-map)
-#+end_src
-
* Acknowledgements
:PROPERTIES:
:CUSTOM_ID: h:532c5398-9510-47d4-a718-a5dfa8f86a3f
