Document new consult async dwim behavior

3 files changed, 33 insertions, 9 deletions

diff --git a/CHANGELOG.org b/CHANGELOG.org
index c5894a3..f3ed5ff 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -1,6 +1,16 @@
 #+title: Embark changelog
 
 * Development version
+- You can now use around action hooks with multitarget actions (that
+  you couldn't previously was an oversight).
+- Users of the =embark-consult= package can now use consult async search
+  commands such as =consult-grep= as multitarget actions (through
+  =embark-act-all=) to search a list of files. For example, you can use
+  =consult-find= to search among file /names/ and once you have the
+  relevant files in the minibuffer, you can use =embark-act-all= to
+  search for some text in those files. When acting on buffers consult
+  async search commands will search the associated file if there is
+  one, or else the =default-directory= of the buffer.
 - =embark-bindings= and similar commands now show definition of keyboard
   macros.
 - =embark-org= now recognizes Org links in non-org buffers.
diff --git a/README.org b/README.org
index b1e1967..1e24838 100644
--- a/README.org
+++ b/README.org
@@ -1094,11 +1094,18 @@ Besides those exporters and candidate collectors, the =embark-consult=
 package provides many subtle tweaks and small integrations between
 Embark and Consult. Some examples are:
 
-- The asynchronous search commands will start in the directory
-  associated to the Embark target if that target is a file, buffer,
-  bookmark or Emacs Lisp library.
-
- - For all other target types, a Consult search command (asynchronous
+- When used as actions, the asynchronous search commands will search
+  only the files associated to the targets: if the targets /are/ files,
+  it searches those files; for buffers it will search either the
+  associated file if there is one, else all files in the buffer's
+  =default-directory=; for bookmarks it will search the file they point
+  to, same for Emacs Lisp libraries. This is particularly powerful
+  when using =embark-act-all= to act on multiple files at once, for
+  example you can use =consult-find= to search among file /names/ and then
+  =embark-act-all= and =consult-grep= to search within the matching files.
+
+ - For all other target types, those that do not have a sensible
+   notion of associated file, a Consult search command (asynchronous
    or not) will search for the text of the target but leave the
    minibuffer open so you can interact with the Consult command.
 
diff --git a/embark.texi b/embark.texi
index 456bf2a..0cbed7e 100644
--- a/embark.texi
+++ b/embark.texi
@@ -1312,13 +1312,20 @@ Embark and Consult. Some examples are:
 
 @itemize
 @item
-The asynchronous search commands will start in the directory
-associated to the Embark target if that target is a file, buffer,
-bookmark or Emacs Lisp library.
+When used as actions, the asynchronous search commands will search
+only the files associated to the targets: if the targets @emph{are} files,
+it searches those files; for buffers it will search either the
+associated file if there is one, else all files in the buffer's
+@samp{default-directory}; for bookmarks it will search the file they point
+to, same for Emacs Lisp libraries. This is particularly powerful
+when using @samp{embark-act-all} to act on multiple files at once, for
+example you can use @samp{consult-find} to search among file @emph{names} and then
+@samp{embark-act-all} and @samp{consult-grep} to search within the matching files.
 
 @itemize
 @item
-For all other target types, a Consult search command (asynchronous
+For all other target types, those that do not have a sensible
+notion of associated file, a Consult search command (asynchronous
 or not) will search for the text of the target but leave the
 minibuffer open so you can interact with the Consult command.
 @end itemize