[elpa] externals/embark 5ebe2dfd91: Replace embark-allow-edit-actions with a setup hook

[ELPA Syncer]

branch: externals/embark
commit 5ebe2dfd91868ec525ea34ffd45941c5e9ce5358
Author: Omar Antolín <omar.antolin@gmail.com>
Commit: Omar Antolín <omar.antolin@gmail.com>

    Replace embark-allow-edit-actions with a setup hook
    
    The variable embark-allow-edit-actions is unnecessary, since its
    effect can be achieved with just a setup hook! That's what the new
    embark--allow-edit function is for.
    
    While this change is a nice simplification anyway, it's really
    prompted by a bug I introduced in commit 
c672dcf1eb8c1be0462778b2ab5a115150568c83. :P
    
    There I noticed that the minibuffer-setup-hook used for injection was
    also applied during the pre-action hook! That meant that if a
    pre-action hook happened to prompt the user in the minibuffer, the
    target would be erroneously injected there. This caused problems with
    embark--confirm, so I tightened the scope of the injection to exclude
    the pre-action hook and just apply to the action. Unfortunately, that
    completely broke the implementation of embark--ignore-target as a
    pre-action hook, which worked by artificially reading from the
    minibuffer to gobble up the target.
    
    Now, I want to keep the narrower scope of the target injection, since
    it makes more sense, so to fix that bug I decided to reimplement
    embark--ingore-target as a setup hook (which also makes more sense
    since setup hooks are exactly about what happens during target
    injection). This required swapping the order of calling the pre-action
    hook and scheduling the minibuffer exit.
    
    Once I did that, I noticed that now embark--allow-edit was possible as
    a setup hook and decided to remove the embark-allow-edit-actions
    variable. The fewer variables the better, and we're already committed
    to extensive hook use.
---
 README.org        | 112 ++++++++++++++++++++++++++++++--------------------
 embark-consult.el |  14 ++++---
 embark.el         |  94 +++++++++++++++++++++---------------------
 embark.texi       | 120 +++++++++++++++++++++++++++++++-----------------------
 4 files changed, 192 insertions(+), 148 deletions(-)

diff --git a/README.org b/README.org
index 469793427c..30451b62cf 100644
--- a/README.org
+++ b/README.org
@@ -408,25 +408,6 @@ behavior of =embark-act= and define a non-quitting version 
as follows:
       (embark-act)))
 #+end_src
 
-** Allowing the target to be edited before acting on it
-
-By default, for most commands =embark= inserts the target of the action
-into the next minibuffer prompt and "presses =RET=" for you, accepting
-the target as is.
-
-For some commands this might be undesirable because further input is
-required next to the target, like when using =shell-command=: the target
-is the file and you still need to enter a shell command to run on it,
-at the same prompt. You can add such commands to the
-=embark-allow-edit-actions= variable (which by default already contains
-the examples mentioned, and a few others as well).
-
-You could abuse this feature so that you have to confirm "dangerous"
-actions such as =delete-file= (and indeed, Embark used to have
-=delete-file= in the default value of =embark-allow-edit-actions=), but it
-is better to implement confirmation by adding the =embark--confirm=
-function to the appropriate entry of =embark-pre-action-hooks=.
-
 ** Running some setup after injecting the target
 
 You can customize what happens after the target is inserted at the
@@ -441,11 +422,56 @@ the action.
 For example, consider using =shell-command= as an action during file
 completion. It would be useful to insert a space before the target
 file name and to leave the point at the beginning, so you can
-immediately type the shell command. That's why in =embark='s default
-configuration there is an entry in =embark-setup-action-hooks= associating
-=shell-command= to =embark--shell-prep=, a simple helper command that
-quotes all the spaces in the file name, inserts an extra space at the
-beginning of the line and leaves point to the left of it.
+immediately type the shell command to run on that file. That's why in
+Embark's default configuration there is an entry in
+=embark-setup-action-hooks= associating =shell-command= to a hook that
+includes =embark--shell-prep=, a simple helper function that quotes all
+the spaces in the file name, inserts an extra space at the beginning
+of the line and leaves point to the left of it.
+
+Now, the preparation that =embark--shell-prep= does would be useless if
+Embark did what it normally does after it inserts the target of the
+action at the minibuffer prompt, which is to "press =RET=" for you,
+accepting the target as is; if Embark did that for =shell-command= you
+wouldn't get a chance to type in the command to execute! That is why
+in Embark's default configuration the entry for =shell-command= in
+=embark-setup-action-hooks= also contains the function
+=embark--allow-edit=.
+
+Embark used to have a dedicated variable =embark-allow-edit-actions= to
+which you could add commands for which Embark should forgo pressing
+=RET= for you after inserting the target. Since its effect can also be
+achieved via the general =embark-setup-action-hooks= mechanism, that
+variable has been removed to simply Embark. Be sure to update your
+configuration; if you had something like:
+
+#+begin_src emacs-lisp
+  (add-to-list 'embark-allow-edit-actions 'my-command)
+#+end_src
+
+you should replace it with:
+
+#+begin_src emacs-lisp
+  (push 'embark--allow-edit
+        (alist-get 'my-command embark-setup-action-hooks))
+#+end_src
+
+
+Also note that while you could abuse =embark--allow-edit= so that you
+have to confirm "dangerous" actions such as =delete-file=, it is better
+to implement confirmation by adding the =embark--confirm= function to
+the appropriate entry of a different hook alist, namely,
+=embark-pre-action-hooks=.
+
+Besides =embark--allow-edit=, Embark comes with another function that is
+of general utility in action setup hooks: =embark--ignore-target=. Use
+it for commands that do prompt you in the minibuffer but for which
+inserting the target would be inappropriate. This is not a common
+situation but does occasionally arise. For example it is used by
+default for =shell-command-on-region=: that command is used as an action
+for region targets, and it prompts you for a shell command; you
+typically do /not/ want the target, that is the contents of the region,
+to be entered at that prompt!
 
 ** Running hooks before or after an action
 
@@ -461,16 +487,9 @@ The default values of those variables are fairly 
extensive, adding
 creature comforts to make running actions a smooth experience. Embark
 comes with several functions intended to be added to these hooks, and
 used in the default values of =embark-pre-action-hooks= and
-=embark-post-action-hooks=:
+=embark-post-action-hooks=.
 
-- =embark--ignore-target= :: Ignore the target. Use this for commands
-  that do prompt you in the minibuffer but for which inserting the
-  target would be inappropriate. This is not a common situation but
-  does occasionally arise. For example it is used by default for
-  =shell-command-on-region=: this is used as action for region targets,
-  and it prompts for a shell command, you typically do /not/ want the
-  target, that is the contents of the region, to be entered at that
-  prompt!
+For pre-action hooks:
 
 - =embark--confirm= :: Prompt the user for confirmation before executing
   the action. This is used be default for commands deemed "dangerous",
@@ -503,6 +522,8 @@ used in the default values of =embark-pre-action-hooks= and
   which you'd like to be able to come back to where you were using
   =xref-pop-marker-stack=. This is used by default for =find-library=.
 
+For post-action hooks:
+
 - =embark--restart= :: Restart the command currently prompting in the
   minibuffer, so that the list of completion candidates is updated.
   This is useful as a post action hook for commands that delete or
@@ -693,8 +714,8 @@ included in the list =embark-indicators=).
 
   Embark actions are normal Emacs commands, that is, functions with an
   interactive specification. In order to execute an action, Embark
-  calls the command with =call-interactively=, so the command reads
-  user input exactly as if run directly by the user. For example the
+  calls the command with =call-interactively=, so the command reads user
+  input exactly as if run directly by the user. For example the
   command may open a minibuffer and read a string
   (=read-from-minibuffer=) or open a completion interface
   (=completing-read=). If this happens, Embark takes the target string
@@ -702,16 +723,17 @@ included in the list =embark-indicators=).
   input this way. After inserting the string, Embark exits the
   minibuffer, submitting the input. (The immediate minibuffer exit can
   be disabled for specific actions in order to allow editing the
-  input: see the =embark-allow-edit-actions= configuration variable).
-  Embark inserts the target string at the first minibuffer opened by
-  the action command, and if the command happens to prompt the user
-  for input more than once, the user still interacts with the second
-  and further prompts in the normal fashion. Note that if a command
-  does not prompt the user for input in the minibuffer, Embark still
-  allows you to use it as an action, but of course, never inserts the
-  target anywhere. (There are plenty of examples in the default
-  configuration of commands that do not prompt the user bound to keys
-  in the action maps, most of the region actions, for instance.)
+  input; this is done by adding the =embark--allow-edit= function to the
+  appropriate entry of =embark-setup-action-hooks=). Embark inserts the
+  target string at the first minibuffer opened by the action command,
+  and if the command happens to prompt the user for input more than
+  once, the user still interacts with the second and further prompts
+  in the normal fashion. Note that if a command does not prompt the
+  user for input in the minibuffer, Embark still allows you to use it
+  as an action, but of course, never inserts the target anywhere.
+  (There are plenty of examples in the default configuration of
+  commands that do not prompt the user bound to keys in the action
+  maps, most of the region actions, for instance.)
 
   This is how Embark manages to reuse normal commands as actions. The
   mechanism allows you to use as Embark actions commands that were not
diff --git a/embark-consult.el b/embark-consult.el
index fb9e0dd6c1..723a4d2015 100644
--- a/embark-consult.el
+++ b/embark-consult.el
@@ -266,20 +266,22 @@ actual type."
 (define-key embark-general-map "C" 'embark-consult-search-map)
 
 (map-keymap
- (lambda (_key cmd) (cl-pushnew cmd embark-allow-edit-actions))
+ (lambda (_key cmd)
+   (cl-pushnew 'embark--allow-edit (alist-get cmd embark-setup-action-hooks)))
  embark-consult-search-map)
 
 (defun embark-consult--unique-match (&rest _)
   "If there is a unique matching candidate, accept it.
-This is intended to be used in `embark-setup-action-hooks' for some
-actions that are on `embark-allow-edit-actions'."
+This is intended to be used in `embark-setup-action-hooks'."
   (let ((candidates (cdr (embark-minibuffer-candidates))))
-    (unless (or (null candidates) (cdr candidates))
+    (if (or (null candidates) (cdr candidates))
+        (embark--allow-edit)
       (delete-minibuffer-contents)
-      (insert (car candidates))
-      (add-hook 'post-command-hook #'exit-minibuffer nil t))))
+      (insert (car candidates)))))
 
 (dolist (cmd '(consult-outline consult-imenu consult-imenu-multi))
+  (setf (alist-get cmd embark-setup-action-hooks)
+        (remq 'embark--allow-edit (alist-get cmd embark-setup-action-hooks)))
   (cl-pushnew #'embark-consult--unique-match
               (alist-get cmd embark-setup-action-hooks)))
 
diff --git a/embark.el b/embark.el
index 43a429ac56..2cb85bc6e2 100644
--- a/embark.el
+++ b/embark.el
@@ -5,7 +5,7 @@
 ;; Author: Omar Antolín Camarena <omar@matem.unam.mx>
 ;; Maintainer: Omar Antolín Camarena <omar@matem.unam.mx>
 ;; Keywords: convenience
-;; Version: 0.13
+;; Version: 0.14
 ;; Homepage: https://github.com/oantolin/embark
 ;; Package-Requires: ((emacs "26.1"))
 
@@ -367,25 +367,12 @@ with `find-file'."
   'embark-allow-edit-commands
   'embark-allow-edit-actions
   "0.12")
-(defcustom embark-allow-edit-actions
-  '(shell-command
-    shell-command-on-region
-    async-shell-command
-    pp-eval-expression)
-  "Enable editing of target prior to acting for these commands.
-Put commands on this list for which additional information needs
-to be entered at the same minibuffer prompt where the target is
-placed.  For example, `shell-command' is on the default value of
-this list because when using `shell-command' as an action
-typically the target is a file name, and you still need to type
-the program and possibly other command line parameters, at the
-same prompt.
-
-Embark used to recommend abusing this as a means of asking the
-user for confirmation before an action, but it is preferable to
-add `embark--confirm' as a pre-action hook for the action in
-`embark-pre-action-hooks'."
-  :type '(repeat function))
+
+(make-obsolete-variable
+   'embark-allow-edit-actions
+   "To allow editing for an action add `embark--allow-edit' to the
+entry of `embark-setup-action-hooks' whose key is the action."
+   "0.14")
 
 (defvar embark-skip-edit-commands nil)
 (defvar embark-allow-edit-default t)
@@ -397,10 +384,22 @@ replaced by the single `embark-allow-edit-actions' 
variable."
    "0.12"))
 
 (defcustom embark-setup-action-hooks
-  '((async-shell-command embark--shell-prep)
-    (shell-command embark--shell-prep)
+  '((async-shell-command embark--allow-edit embark--shell-prep)
+    (shell-command embark--allow-edit embark--shell-prep)
+    (shell-command-on-region embark--allow-edit)
     (pp-eval-expression embark--eval-prep)
-    (package-delete embark--force-complete))
+    (package-delete embark--force-complete)
+    ;; commands evaluating code found in the buffer, which may in turn prompt
+    (embark-pp-eval-defun embark--ignore-target)
+    (eval-defun embark--ignore-target)
+    (eval-last-sexp embark--ignore-target)
+    (embark-eval-replace embark--ignore-target)
+    ;; commands which prompt for something that is *not* the target
+    (write-region embark--ignore-target)
+    (append-to-file embark--ignore-target)
+    (shell-command-on-region embark--ignore-target)
+    (format-encode-region embark--ignore-target)
+    (format-decode-region embark--ignore-target))
   "Alist associating commands with post-injection setup hooks.
 For commands appearing as keys in this alist, run the
 corresponding value as a setup hook after injecting the target
@@ -423,16 +422,8 @@ the key :always are executed always."
                  "0.12"))
 
 (defcustom embark-pre-action-hooks
-  '(;; region commands which prompt for a filename or command
-    (write-region embark--ignore-target embark--mark-target)
-    (append-to-file embark--ignore-target embark--mark-target)
-    (shell-command-on-region embark--ignore-target embark--mark-target)
-    ;; commands which evaluate code not given at a prompt
-    (embark-pp-eval-defun embark--ignore-target)
-    (eval-defun embark--ignore-target)
-    (eval-last-sexp embark--end-of-target embark--ignore-target)
-    (embark-eval-replace embark--ignore-target embark--mark-target)
-    ;; motion commands that need to position point to skip current match
+  '(;; commands that need to position point at the beginning or end
+    (eval-last-sexp embark--end-of-target)
     (indent-pp-sexp embark--beginning-of-target)
     (backward-up-list embark--beginning-of-target)
     (backward-list embark--beginning-of-target)
@@ -461,8 +452,12 @@ the key :always are executed always."
     (count-words-region embark--mark-target)
     (shell-command-on-region embark--mark-target)
     (delete-region embark--mark-target)
-    (format-encode-region embark--mark-target embark--ignore-target)
-    (format-decode-region embark--mark-target embark--ignore-target)
+    (format-encode-region embark--mark-target)
+    (format-decode-region embark--mark-target)
+    (write-region embark--mark-target)
+    (append-to-file embark--mark-target)
+    (shell-command-on-region embark--mark-target)
+    (embark-eval-replace embark--mark-target)
     ;; commands we want to be able to jump back from
     ;; (embark-find-definition achieves this by calling
     ;; xref-find-definitions which pushes the markers itself)
@@ -1768,16 +1763,15 @@ minibuffer before executing the action."
             (lambda ()
               (delete-minibuffer-contents)
               (insert (substring-no-properties (plist-get target :target)))
+              (if (memq 'ivy--queue-exhibit post-command-hook)
+                  ;; Ivy has special needs: (1) for file names
+                  ;; ivy-immediate-done is not equivalent to
+                  ;; exit-minibuffer, (2) it needs a chance to run
+                  ;; its post command hook first, so use depth 10
+                  (add-hook 'post-command-hook 'ivy-immediate-done 10 t)
+                (add-hook 'post-command-hook #'exit-minibuffer nil t))
               (embark--run-action-hooks embark-setup-action-hooks
-                                        action target quit)
-              (unless (memq action embark-allow-edit-actions)
-                (if (memq 'ivy--queue-exhibit post-command-hook)
-                    ;; Ivy has special needs: (1) for file names
-                    ;; ivy-immediate-done is not equivalent to
-                    ;; exit-minibuffer, (2) it needs a chance to run
-                    ;; its post command hook first, so use depth 10
-                    (add-hook 'post-command-hook 'ivy-immediate-done 10 t)
-                  (add-hook 'post-command-hook #'exit-minibuffer nil t)))))
+                                        action target quit)))
            (dedicate (and (derived-mode-p 'embark-collect-mode)
                           (not (window-dedicated-p))
                           (selected-window)))
@@ -3667,8 +3661,8 @@ and leaves the point to the left of it."
 
 (defun embark--eval-prep (&rest _)
   "If target is: a variable, skip edit; a function, wrap in parens."
-  (if (not (fboundp (intern-soft (minibuffer-contents))))
-      (add-hook 'post-command-hook #'exit-minibuffer nil t)
+  (when (fboundp (intern-soft (minibuffer-contents)))
+    (embark--allow-edit)
     (goto-char (minibuffer-prompt-end))
     (insert "(")
     (goto-char (point-max))
@@ -3691,9 +3685,15 @@ and leaves the point to the left of it."
     (set-mark (cdr bounds))
     (goto-char (car bounds))))
 
+(defun embark--allow-edit (&rest _)
+  "Allow editing the target."
+  (remove-hook 'post-command-hook 'exit-minibuffer t)
+  (remove-hook 'post-command-hook 'ivy-immediate-done t))
+
 (defun embark--ignore-target (&rest _)
   "Ignore the target."
-  (ignore (read-from-minibuffer "")))
+  (delete-minibuffer-contents)
+  (embark--allow-edit))
 
 (autoload 'xref--push-markers "xref")
 (defun embark--xref-push-markers (&rest _)
diff --git a/embark.texi b/embark.texi
index 93c452eb1d..1c1afbd90f 100644
--- a/embark.texi
+++ b/embark.texi
@@ -49,7 +49,6 @@ Advanced configuration
 * Showing information about available targets and actions::
 * Selecting commands via completions instead of key bindings::
 * Quitting the minibuffer after an action::
-* Allowing the target to be edited before acting on it::
 * Running some setup after injecting the target::
 * Running hooks before or after an action::
 * Creating your own keymaps::
@@ -413,7 +412,6 @@ integration despite this.)
 * Showing information about available targets and actions::
 * Selecting commands via completions instead of key bindings::
 * Quitting the minibuffer after an action::
-* Allowing the target to be edited before acting on it::
 * Running some setup after injecting the target::
 * Running hooks before or after an action::
 * Creating your own keymaps::
@@ -529,26 +527,6 @@ behavior of @samp{embark-act} and define a non-quitting 
version as follows:
     (embark-act)))
 @end lisp
 
-@node Allowing the target to be edited before acting on it
-@section Allowing the target to be edited before acting on it
-
-By default, for most commands @samp{embark} inserts the target of the action
-into the next minibuffer prompt and ``presses @samp{RET}'' for you, accepting
-the target as is.
-
-For some commands this might be undesirable because further input is
-required next to the target, like when using @samp{shell-command}: the target
-is the file and you still need to enter a shell command to run on it,
-at the same prompt. You can add such commands to the
-@samp{embark-allow-edit-actions} variable (which by default already contains
-the examples mentioned, and a few others as well).
-
-You could abuse this feature so that you have to confirm ``dangerous''
-actions such as @samp{delete-file} (and indeed, Embark used to have
-@samp{delete-file} in the default value of @samp{embark-allow-edit-actions}), 
but it
-is better to implement confirmation by adding the @samp{embark--confirm}
-function to the appropriate entry of @samp{embark-pre-action-hooks}.
-
 @node Running some setup after injecting the target
 @section Running some setup after injecting the target
 
@@ -564,11 +542,56 @@ the action.
 For example, consider using @samp{shell-command} as an action during file
 completion. It would be useful to insert a space before the target
 file name and to leave the point at the beginning, so you can
-immediately type the shell command. That's why in @samp{embark}'s default
-configuration there is an entry in @samp{embark-setup-action-hooks} associating
-@samp{shell-command} to @samp{embark--shell-prep}, a simple helper command that
-quotes all the spaces in the file name, inserts an extra space at the
-beginning of the line and leaves point to the left of it.
+immediately type the shell command to run on that file. That's why in
+Embark's default configuration there is an entry in
+@samp{embark-setup-action-hooks} associating @samp{shell-command} to a hook 
that
+includes @samp{embark--shell-prep}, a simple helper function that quotes all
+the spaces in the file name, inserts an extra space at the beginning
+of the line and leaves point to the left of it.
+
+Now, the preparation that @samp{embark--shell-prep} does would be useless if
+Embark did what it normally does after it inserts the target of the
+action at the minibuffer prompt, which is to ``press @samp{RET}'' for you,
+accepting the target as is; if Embark did that for @samp{shell-command} you
+wouldn't get a chance to type in the command to execute! That is why
+in Embark's default configuration the entry for @samp{shell-command} in
+@samp{embark-setup-action-hooks} also contains the function
+@samp{embark--allow-edit}.
+
+Embark used to have a dedicated variable @samp{embark-allow-edit-actions} to
+which you could add commands for which Embark should forgo pressing
+@samp{RET} for you after inserting the target. Since its effect can also be
+achieved via the general @samp{embark-setup-action-hooks} mechanism, that
+variable has been removed to simply Embark. Be sure to update your
+configuration; if you had something like:
+
+@lisp
+(add-to-list 'embark-allow-edit-actions 'my-command)
+@end lisp
+
+you should replace it with:
+
+@lisp
+(push 'embark--allow-edit
+      (alist-get 'my-command embark-setup-action-hooks))
+@end lisp
+
+
+Also note that while you could abuse @samp{embark--allow-edit} so that you
+have to confirm ``dangerous'' actions such as @samp{delete-file}, it is better
+to implement confirmation by adding the @samp{embark--confirm} function to
+the appropriate entry of a different hook alist, namely,
+@samp{embark-pre-action-hooks}.
+
+Besides @samp{embark--allow-edit}, Embark comes with another function that is
+of general utility in action setup hooks: @samp{embark--ignore-target}. Use
+it for commands that do prompt you in the minibuffer but for which
+inserting the target would be inappropriate. This is not a common
+situation but does occasionally arise. For example it is used by
+default for @samp{shell-command-on-region}: that command is used as an action
+for region targets, and it prompts you for a shell command; you
+typically do @emph{not} want the target, that is the contents of the region,
+to be entered at that prompt!
 
 @node Running hooks before or after an action
 @section Running hooks before or after an action
@@ -585,19 +608,11 @@ The default values of those variables are fairly 
extensive, adding
 creature comforts to make running actions a smooth experience. Embark
 comes with several functions intended to be added to these hooks, and
 used in the default values of @samp{embark-pre-action-hooks} and
-@samp{embark-post-action-hooks}:
+@samp{embark-post-action-hooks}.
 
-@table @asis
-@item @samp{embark--ignore-target}
-Ignore the target. Use this for commands
-that do prompt you in the minibuffer but for which inserting the
-target would be inappropriate. This is not a common situation but
-does occasionally arise. For example it is used by default for
-@samp{shell-command-on-region}: this is used as action for region targets,
-and it prompts for a shell command, you typically do @emph{not} want the
-target, that is the contents of the region, to be entered at that
-prompt!
+For pre-action hooks:
 
+@table @asis
 @item @samp{embark--confirm}
 Prompt the user for confirmation before executing
 the action. This is used be default for commands deemed ``dangerous'',
@@ -633,7 +648,11 @@ Push the current location on the xref
 marker stack. Use this for commands that take you somewhere and for
 which you'd like to be able to come back to where you were using
 @samp{xref-pop-marker-stack}. This is used by default for @samp{find-library}.
+@end table
 
+For post-action hooks:
+
+@table @asis
 @item @samp{embark--restart}
 Restart the command currently prompting in the
 minibuffer, so that the list of completion candidates is updated.
@@ -846,8 +865,8 @@ included in the list @samp{embark-indicators}).
 
 Embark actions are normal Emacs commands, that is, functions with an
 interactive specification. In order to execute an action, Embark
-calls the command with @samp{call-interactively}, so the command reads
-user input exactly as if run directly by the user. For example the
+calls the command with @samp{call-interactively}, so the command reads user
+input exactly as if run directly by the user. For example the
 command may open a minibuffer and read a string
 (@samp{read-from-minibuffer}) or open a completion interface
 (@samp{completing-read}). If this happens, Embark takes the target string
@@ -855,16 +874,17 @@ and inserts it automatically into the minibuffer, 
simulating user
 input this way. After inserting the string, Embark exits the
 minibuffer, submitting the input. (The immediate minibuffer exit can
 be disabled for specific actions in order to allow editing the
-input: see the @samp{embark-allow-edit-actions} configuration variable).
-Embark inserts the target string at the first minibuffer opened by
-the action command, and if the command happens to prompt the user
-for input more than once, the user still interacts with the second
-and further prompts in the normal fashion. Note that if a command
-does not prompt the user for input in the minibuffer, Embark still
-allows you to use it as an action, but of course, never inserts the
-target anywhere. (There are plenty of examples in the default
-configuration of commands that do not prompt the user bound to keys
-in the action maps, most of the region actions, for instance.)
+input; this is done by adding the @samp{embark--allow-edit} function to the
+appropriate entry of @samp{embark-setup-action-hooks}). Embark inserts the
+target string at the first minibuffer opened by the action command,
+and if the command happens to prompt the user for input more than
+once, the user still interacts with the second and further prompts
+in the normal fashion. Note that if a command does not prompt the
+user for input in the minibuffer, Embark still allows you to use it
+as an action, but of course, never inserts the target anywhere.
+(There are plenty of examples in the default configuration of
+commands that do not prompt the user bound to keys in the action
+maps, most of the region actions, for instance.)
 
 This is how Embark manages to reuse normal commands as actions. The
 mechanism allows you to use as Embark actions commands that were not