[elpa] externals/embark 5655c1415f 2/3: Document around hooks in the manual

[ELPA Syncer]

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

    Document around hooks in the manual
---
 README.org  |  67 +++++++++++++++++++----------------
 embark.texi | 113 +++++++++++++++++++++++++++++++++---------------------------
 2 files changed, 100 insertions(+), 80 deletions(-)

diff --git a/README.org b/README.org
index 8a94f9db97..e22c489b9b 100644
--- a/README.org
+++ b/README.org
@@ -545,21 +545,22 @@ 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
+** Running hooks before, after or around an action
 
-Embark has two variables, =embark-pre-action-hooks= and
-=embark-post-action-hooks=, which are alists associating commands to
-hooks that should run before or after the command is used as an
-action. As with, =embark-target-injection-hooks=, there are two special keys
-for the alists: =t= designates the default hook to run when no specific
-hook is specified for a command; and the hook associated to =:always=
-runs regardless.
+Embark has three variables, =embark-pre-action-hooks=,
+=embark-post-action-hooks= and =embark-around-action-hooks=, which are
+alists associating commands to hooks that should run before or after
+or as around advice for the command when used as an action. As with
+=embark-target-injection-hooks=, there are two special keys for the
+alists: =t= designates the default hook to run when no specific hook is
+specified for a command; and the hook associated to =:always= runs
+regardless.
 
 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=.
+used in the default values of =embark-pre-action-hooks=,
+=embark-post-action-hooks= and =embark-around-action-hooks=.
 
 For pre-action hooks:
 
@@ -568,16 +569,6 @@ For pre-action hooks:
   or, more accurately, hard to undo, such as =delete-file= and
   =kill-buffer=.
 
-- =embark--mark-target= :: Mark the target as an active region. Most
-  targets at point outside the minibuffer report which region of the
-  buffer they correspond to (this is the information used by
-  =embark-highlight-indicator= to know what portion of the buffer to
-  highlight); this function marks that region. It is useful as a pre
-  action hook for commands that expect a region to be marked, for
-  example, it is used by default for =indent-region= so that it works on
-  s-expression targets, or for =fill-region= so that it works on
-  paragraph targets.
-
 - =embark--unmark-target= :: Unmark the active region. Use this for
   commands you want to act on the region contents but without the
   region being active. The default configuration uses this function as
@@ -600,21 +591,11 @@ For pre-action hooks:
   on an s-expression from anywhere inside it and still use
   =eval-last-sexp= as an action.
 
-- =embark--narrow-to-target= :: Narrow buffer to current target. Use
-  this as a pre-action hook to localize the effect of actions that
-  don't already work on just the region. In the default configuration
-  it is used for =repunctuate-sentences=.
-
 - =embark--xref-push-markers= :: 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
   =xref-pop-marker-stack=. This is used by default for =find-library=.
 
-- =embark--cd= :: Run the action with =default-directory= set to the
-  directory associated to the current target. The target should be of
-  type =file=, =buffer=, =bookmark= or =library=, and the associated directory
-  is what you'd expect in each case.
-
 For post-action hooks:
 
 - =embark--restart= :: Restart the command currently prompting in the
@@ -624,6 +605,32 @@ For post-action hooks:
   =embark-post-action-hooks= uses it for =delete-file=, =kill-buffer=,
   =rename-file=, =rename-buffer=, etc.
 
+For around-action hooks:
+
+- =embark--mark-target= :: Save existing mark and point location, mark
+  the target and run the action. Most targets at point outside the
+  minibuffer report which region of the buffer they correspond to
+  (this is the information used by =embark-highlight-indicator= to
+  know what portion of the buffer to highlight); this function marks
+  that region. It is useful as an around action hook for commands that
+  expect a region to be marked, for example, it is used by default for
+  =indent-region= so that it works on s-expression targets, or for
+  =fill-region= so that it works on paragraph targets.
+
+- =embark--cd= :: Run the action with =default-directory= set to the
+  directory associated to the current target. The target should be of
+  type =file=, =buffer=, =bookmark= or =library=, and the associated directory
+  is what you'd expect in each case.
+
+- =embark--narrow-to-target= :: Run the action with buffer narrowed to
+  current target. Use this as an around hook to localize the effect of
+  actions that don't already work on just the region. In the default
+  configuration it is used for =repunctuate-sentences=.
+
+- =embark--save-excursion= :: Run the action restoring point at the end.
+  The current default configuration doesn't use this but it is
+  available for users.
+
 ** Creating your own keymaps
 
 All internal keymaps are defined with a helper macro
diff --git a/embark.texi b/embark.texi
index 780969bb0e..5d355139bf 100644
--- a/embark.texi
+++ b/embark.texi
@@ -54,7 +54,7 @@ Advanced configuration
 * Selecting commands via completions instead of key bindings::
 * Quitting the minibuffer after an action::
 * Running some setup after injecting the target::
-* Running hooks before or after an action::
+* Running hooks before, after or around an action: Running hooks before after 
or around an action. 
 * Creating your own keymaps::
 * Defining actions for new categories of targets::
 
@@ -312,14 +312,14 @@ and are bound to @samp{A}, @samp{S} (for ``snapshot''), 
and @samp{E}, respective
 key bindings for these (although you can, of course!), just a key
 binding for @samp{embark-act}.
 
-Reverting an Embark Collect or Embark Export buffer has slightly
-unusual behavior if the buffer was obtained by running @samp{embark-collect}
-or @samp{embark-export} from within a minibuffer completion session. In that
-case reverting just restarts the completion session, that is, the
-command that opened the minibuffer is run again and the minibuffer
-contents restored. You can then interact normally with the command,
-perhaps editing the minibuffer contents, and, if you wish, you can
-rerun @samp{embark-collect} or @samp{embark-export} to get an updated buffer.
+In Embark Collect or Embark Export buffers that were obtained by
+running @samp{embark-collect} or @samp{embark-export} from within a minibuffer
+completion session, @samp{g} is bound to a command that restarts the
+completion session, that is, the command that opened the minibuffer is
+run again and the minibuffer contents restored. You can then interact
+normally with the command, perhaps editing the minibuffer contents,
+and, if you wish, you can rerun @samp{embark-collect} or @samp{embark-export} 
to get
+an updated buffer.
 
 @menu
 * @samp{embark-live} a live-updating variant of @samp{embark-collect}::
@@ -489,7 +489,7 @@ integration despite this.)
 * Selecting commands via completions instead of key bindings::
 * Quitting the minibuffer after an action::
 * Running some setup after injecting the target::
-* Running hooks before or after an action::
+* Running hooks before, after or around an action: Running hooks before after 
or around an action. 
 * Creating your own keymaps::
 * Defining actions for new categories of targets::
 @end menu
@@ -684,22 +684,23 @@ 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
+@node Running hooks before after or around an action
+@section Running hooks before, after or around an action
 
-Embark has two variables, @samp{embark-pre-action-hooks} and
-@samp{embark-post-action-hooks}, which are alists associating commands to
-hooks that should run before or after the command is used as an
-action. As with, @samp{embark-target-injection-hooks}, there are two special 
keys
-for the alists: @samp{t} designates the default hook to run when no specific
-hook is specified for a command; and the hook associated to @samp{:always}
-runs regardless.
+Embark has three variables, @samp{embark-pre-action-hooks},
+@samp{embark-post-action-hooks} and @samp{embark-around-action-hooks}, which 
are
+alists associating commands to hooks that should run before or after
+or as around advice for the command when used as an action. As with
+@samp{embark-target-injection-hooks}, there are two special keys for the
+alists: @samp{t} designates the default hook to run when no specific hook is
+specified for a command; and the hook associated to @samp{:always} runs
+regardless.
 
 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}.
+used in the default values of @samp{embark-pre-action-hooks},
+@samp{embark-post-action-hooks} and @samp{embark-around-action-hooks}.
 
 For pre-action hooks:
 
@@ -710,17 +711,6 @@ the action. This is used be default for commands deemed 
``dangerous'',
 or, more accurately, hard to undo, such as @samp{delete-file} and
 @samp{kill-buffer}.
 
-@item @samp{embark--mark-target}
-Mark the target as an active region. Most
-targets at point outside the minibuffer report which region of the
-buffer they correspond to (this is the information used by
-@samp{embark-highlight-indicator} to know what portion of the buffer to
-highlight); this function marks that region. It is useful as a pre
-action hook for commands that expect a region to be marked, for
-example, it is used by default for @samp{indent-region} so that it works on
-s-expression targets, or for @samp{fill-region} so that it works on
-paragraph targets.
-
 @item @samp{embark--unmark-target}
 Unmark the active region. Use this for
 commands you want to act on the region contents but without the
@@ -746,23 +736,11 @@ on the last s-expression like @samp{eval-last-sexp}. This 
allow you to act
 on an s-expression from anywhere inside it and still use
 @samp{eval-last-sexp} as an action.
 
-@item @samp{embark--narrow-to-target}
-Narrow buffer to current target. Use
-this as a pre-action hook to localize the effect of actions that
-don't already work on just the region. In the default configuration
-it is used for @samp{repunctuate-sentences}.
-
 @item @samp{embark--xref-push-markers}
 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}.
-
-@item @samp{embark--cd}
-Run the action with @samp{default-directory} set to the
-directory associated to the current target. The target should be of
-type @samp{file}, @samp{buffer}, @samp{bookmark} or @samp{library}, and the 
associated directory
-is what you'd expect in each case.
 @end table
 
 For post-action hooks:
@@ -777,6 +755,38 @@ rename a completion candidate; for example the default 
value of
 @samp{rename-file}, @samp{rename-buffer}, etc.
 @end table
 
+For around-action hooks:
+
+@table @asis
+@item @samp{embark--mark-target}
+Save existing mark and point location, mark
+the target and run the action. Most targets at point outside the
+minibuffer report which region of the buffer they correspond to
+(this is the information used by @samp{embark-highlight-indicator} to
+know what portion of the buffer to highlight); this function marks
+that region. It is useful as an around action hook for commands that
+expect a region to be marked, for example, it is used by default for
+@samp{indent-region} so that it works on s-expression targets, or for
+@samp{fill-region} so that it works on paragraph targets.
+
+@item @samp{embark--cd}
+Run the action with @samp{default-directory} set to the
+directory associated to the current target. The target should be of
+type @samp{file}, @samp{buffer}, @samp{bookmark} or @samp{library}, and the 
associated directory
+is what you'd expect in each case.
+
+@item @samp{embark--narrow-to-target}
+Run the action with buffer narrowed to
+current target. Use this as an around hook to localize the effect of
+actions that don't already work on just the region. In the default
+configuration it is used for @samp{repunctuate-sentences}.
+
+@item @samp{embark--save-excursion}
+Run the action restoring point at the end.
+The current default configuration doesn't use this but it is
+available for users.
+@end table
+
 @node Creating your own keymaps
 @section Creating your own keymaps
 
@@ -918,15 +928,18 @@ without confirmation is dangerous? You have a couple of 
options:
 @item
 You can keep using the @samp{tab-bar-close-tab-by-name} command, but have
 Embark ask you for confirmation:
+@end enumerate
 @lisp
 (push #'embark--confirm
       (alist-get 'tab-bar-close-tab-by-name
                  embark-pre-action-hooks))
 @end lisp
 
+@enumerate
 @item
 You can write your own command that prompts for confirmation and
 use that instead of @samp{tab-bar-close-tab-by-name} in the above keymap:
+@end enumerate
 @lisp
 (defun my-confirm-close-tab-by-name (tab)
   (interactive "sTab to close: ")
@@ -939,7 +952,6 @@ independently of Embark. Using it from @samp{M-x} leaves 
something to be
 desired, though, since you don't get completion for the tab names.
 You can fix this if you wish as described in the previous section.
 @end enumerate
-@end enumerate
 
 @node New target example in regular buffers - short Wikipedia links
 @subsection New target example in regular buffers - short Wikipedia links
@@ -1188,11 +1200,12 @@ to navigate among matches, and, if you install the 
@uref{http://github.com/mhaya
 you can use it to edit the matches in place.
 @end itemize
 
-In both cases, pressing @samp{g} to revert the exported buffer will rerun the
-Consult command you had exported from and re-enter the input you had
-typed. You can then proceed to re-export if that's what you want, but
-you can also edit the input changing the search terms or simply cancel
-if you see you are done with that search.
+In both cases, pressing @samp{g} will rerun the Consult command you had
+exported from and re-enter the input you had typed (which is similar
+to reverting but a little more flexible). You can then proceed to
+re-export if that's what you want, but you can also edit the input
+changing the search terms or simply cancel if you see you are done
+with that search.
 
 The @samp{embark-consult} also contains some candidates collectors that allow
 you to run @samp{embark-live} to get a live-updating table of contents for