[elpa] externals/embark 9bf01e1c1d: Rewrite the documentation related to Marginalia and Consult

[ELPA Syncer]

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

    Rewrite the documentation related to Marginalia and Consult
---
 README.org  |  90 ++++++++++++++++++++++++++++++++++++++++----------
 embark.texi | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 163 insertions(+), 34 deletions(-)

diff --git a/README.org b/README.org
index 84c4fbdf84..d3857380ee 100644
--- a/README.org
+++ b/README.org
@@ -884,8 +884,15 @@ included in the list =embark-indicators=).
 * Embark, Marginalia and Consult
 
 Embark cooperates well with the 
[[https://github.com/minad/marginalia][Marginalia]] and 
[[https://github.com/minad/consult][Consult]] packages.
-Neither of those packages is a dependency of Embark, but Marginalia is
-highly recommended, for reasons explained in the rest of this section.
+Neither of those packages is a dependency of Embark, but both are
+highly recommended companions to Embark, for opposite reasons:
+Marginalia greatly enhances Embark's usefulness, while Embark can help
+enhance Consult.
+
+In the remainder of this section I'll explain what exactly Marginalia
+does for Embark, and what Embark can do for Consult.
+
+** Marginalia
 
 Embark comes with actions for symbols (commands, functions, variables
 with actions such as finding the definition, looking up the
@@ -905,28 +912,75 @@ augments many Emacs command to report accurate category 
metadata.
 Simply activating =marginalia-mode= allows Embark to offer you the
 package and symbol actions when appropriate again. Candidate
 annotations in the Embark collect buffer are also provided by the
-Marginalia package.
+Marginalia package:
 
-- If you install Marginalia and activate =marginalia-mode=, the list
-  view in Embark Collect buffers will use the Marginalia annotations
-  automatically.
+- If you install Marginalia and activate =marginalia-mode=, Embark
+  Collect buffers will use the Marginalia annotations automatically.
 
 - If you don't install Marginalia, you will see only the annotations
   that come with Emacs (such as key bindings in =M-x=, or the unicode
   characters in =C-x 8 RET=).
 
-- If you have Consult installed and call =embark-collect= from
-  =consult-line=, =consult-mark= or =consult-outline=, you will notice the
-  Embark Collect buffer starts in list view by default. Similarly,
-  you'll notice that the =consult-yank= family of commands start out in
-  list view with zebra stripes, so you can easily tell where
-  multi-line kill-ring entries start and end.
-
-- The function =embark-open-externally= has been removed following the
-  policy of avoiding overlap with Consult. If you used that action,
-  add 
[[https://github.com/minad/consult/blob/373498acb76b9395e5e590fb8e39f671a9363cd7/consult.el#L707][the
 small function]] to your configuration or install Consult and
-  use =consult-file-externally=.
-
+** Consult
+
+The excellent Consult package provides many commands that use
+minibuffer completion, via the =completing-read= function; plenty of its
+commands can be considered enhanced versions of built-in Emacs
+commands, and some are completely new functionality. One common
+enhancement provided in all commands for which it makes sense is
+preview functionality, for example =consult-buffer= will show you a
+quick preview of a buffer before you actually switch to it.
+
+If you use both Consult and Embark you should absolutely install the
+=embark-consult= package which provides integration between the two. It
+provides exporters for several Consult commands and also tweaks the
+behavior of many Consult commands when used as actions with =embark-act=
+in subtle ways that you may not even notice, but make for a smoother
+experience.
+
+The =embark-consult= package provides the following exporters:
+
+- You can use =embark-export= from =consult-line=, =consult-outline=, or
+  =consult-mark= to obtain an =occur-mode= buffer. As with the built-in
+  =occur= command you use that buffer to jump to a match and after that,
+  you can then use =next-error= and =previous-error= to navigate to other
+  matches. You can also press =e= to activate =occur-edit-mode= and edit
+  the matches in place!
+
+- You can export from any of the Consult asynchronous search commands,
+  =consult-grep=, =consult-git-grep=, or =consult-ripgrep= to get a
+  =grep-mode= buffer. Here too you can use =next-error= and =previous-error=
+  to navigate among matches, and, if you install the 
[[http://github.com/mhayashi1120/Emacs-wgrep/raw/master/wgrep.el ][wgrep]] 
package,
+  you can use it to edit the matches in place.
+
+In both cases, pressing =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.
+
+Besides those exporters, the =embark-consult= package provides many
+subtle tweaks and small integrations between Embark and Consult. For
+example, if you run =embark-collect= from any of the the =consult-yank=
+family of commands, you'll see the Embark Collect buffers has full
+multi-line kill-ring entries with zebra stripes, so you can easily tell
+where they start and end.
+
+Some examples of little tweaks provided by =embark-consult= to the
+behavior of Consult commands when used as Embark actions 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
+   or not) will search for the text of the target but leave the
+   minibuffer open so you can interact with the Consult command.
+
+- =consult-imenu= will search for the target and take you directly to
+  the location if it matches a unique imenu entry, otherwise it will
+  leave the minibuffer open so you can navigate among the matches.
+   
 * Resources
 
 If you want to learn more about how others have used Embark here are
diff --git a/embark.texi b/embark.texi
index 08681d76cd..bf4143d9bb 100644
--- a/embark.texi
+++ b/embark.texi
@@ -63,6 +63,11 @@ How does Embark call the actions?
 
 * Non-interactive functions as actions::
 
+Embark, Marginalia and Consult
+
+* Marginalia::
+* Consult::
+
 @end detailmenu
 @end menu
 
@@ -1053,8 +1058,21 @@ non-string target.
 @chapter Embark, Marginalia and Consult
 
 Embark cooperates well with the @uref{https://github.com/minad/marginalia, 
Marginalia} and @uref{https://github.com/minad/consult, Consult} packages.
-Neither of those packages is a dependency of Embark, but Marginalia is
-highly recommended, for reasons explained in the rest of this section.
+Neither of those packages is a dependency of Embark, but both are
+highly recommended companions to Embark, for opposite reasons:
+Marginalia greatly enhances Embark's usefulness, while Embark can help
+enhance Consult.
+
+In the remainder of this section I'll explain what exactly Marginalia
+does for Embark, and what Embark can do for Consult.
+
+@menu
+* Marginalia::
+* Consult::
+@end menu
+
+@node Marginalia
+@section Marginalia
 
 Embark comes with actions for symbols (commands, functions, variables
 with actions such as finding the definition, looking up the
@@ -1074,32 +1092,89 @@ augments many Emacs command to report accurate category 
metadata.
 Simply activating @samp{marginalia-mode} allows Embark to offer you the
 package and symbol actions when appropriate again. Candidate
 annotations in the Embark collect buffer are also provided by the
-Marginalia package.
+Marginalia package:
 
 @itemize
 @item
-If you install Marginalia and activate @samp{marginalia-mode}, the list
-view in Embark Collect buffers will use the Marginalia annotations
-automatically.
+If you install Marginalia and activate @samp{marginalia-mode}, Embark
+Collect buffers will use the Marginalia annotations automatically.
 
 @item
 If you don't install Marginalia, you will see only the annotations
 that come with Emacs (such as key bindings in @samp{M-x}, or the unicode
 characters in @samp{C-x 8 RET}).
+@end itemize
+
+@node Consult
+@section Consult
+
+The excellent Consult package provides many commands that use
+minibuffer completion, via the @samp{completing-read} function; plenty of its
+commands can be considered enhanced versions of built-in Emacs
+commands, and some are completely new functionality. One common
+enhancement provided in all commands for which it makes sense is
+preview functionality, for example @samp{consult-buffer} will show you a
+quick preview of a buffer before you actually switch to it.
+
+If you use both Consult and Embark you should absolutely install the
+@samp{embark-consult} package which provides integration between the two. It
+provides exporters for several Consult commands and also tweaks the
+behavior of many Consult commands when used as actions with @samp{embark-act}
+in subtle ways that you may not even notice, but make for a smoother
+experience.
+
+The @samp{embark-consult} package provides the following exporters:
+
+@itemize
+@item
+You can use @samp{embark-export} from @samp{consult-line}, 
@samp{consult-outline}, or
+@samp{consult-mark} to obtain an @samp{occur-mode} buffer. As with the built-in
+@samp{occur} command you use that buffer to jump to a match and after that,
+you can then use @samp{next-error} and @samp{previous-error} to navigate to 
other
+matches. You can also press @samp{e} to activate @samp{occur-edit-mode} and 
edit
+the matches in place!
 
 @item
-If you have Consult installed and call @samp{embark-collect} from
-@samp{consult-line}, @samp{consult-mark} or @samp{consult-outline}, you will 
notice the
-Embark Collect buffer starts in list view by default. Similarly,
-you'll notice that the @samp{consult-yank} family of commands start out in
-list view with zebra stripes, so you can easily tell where
-multi-line kill-ring entries start and end.
+You can export from any of the Consult asynchronous search commands,
+@samp{consult-grep}, @samp{consult-git-grep}, or @samp{consult-ripgrep} to get 
a
+@samp{grep-mode} buffer. Here too you can use @samp{next-error} and 
@samp{previous-error}
+to navigate among matches, and, if you install the 
@uref{http://github.com/mhayashi1120/Emacs-wgrep/raw/master/wgrep.el , wgrep} 
package,
+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.
+
+Besides those exporters, the @samp{embark-consult} package provides many
+subtle tweaks and small integrations between Embark and Consult. For
+example, if you run @samp{embark-collect} from any of the the 
@samp{consult-yank}
+family of commands, you'll see the Embark Collect buffers has full
+multi-line kill-ring entries with zebra stripes, so you can easily tell
+where they start and end.
+
+Some examples of little tweaks provided by @samp{embark-consult} to the
+behavior of Consult commands when used as Embark actions 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.
+
+@itemize
+@item
+For all other target types, 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
 
 @item
-The function @samp{embark-open-externally} has been removed following the
-policy of avoiding overlap with Consult. If you used that action,
-add 
@uref{https://github.com/minad/consult/blob/373498acb76b9395e5e590fb8e39f671a9363cd7/consult.el#L707,
 the small function} to your configuration or install Consult and
-use @samp{consult-file-externally}.
+@samp{consult-imenu} will search for the target and take you directly to
+the location if it matches a unique imenu entry, otherwise it will
+leave the minibuffer open so you can navigate among the matches.
 @end itemize
 
 @node Resources