branch: externals/embark
commit 7de77635ab575d9a1fc9eab2513f99460c6a6bf6
Author: Omar Antolín <omar.anto...@gmail.com>
Commit: Omar Antolín <omar.anto...@gmail.com>
Attempt to improve the introduction in the manual
See the discussion in #504
---
README.org | 36 ++++++++++++++++++++++++++++++++----
embark.texi | 36 ++++++++++++++++++++++++++++++++----
2 files changed, 64 insertions(+), 8 deletions(-)
diff --git a/README.org b/README.org
index 4bb2fd8554..8de2c3f550 100644
--- a/README.org
+++ b/README.org
@@ -12,12 +12,40 @@
* Overview
+Embark makes it easy to choose a command to run based on what is near
+point. If the command you choose prompts you for input, Embark can
+fill in the data for you. Bind the =embark-act= command to a key and it
+acts like a prefix key for a keymap of /actions/ (commands) relevant to
+the /target/ found around point. For example, if point is on a file
+name, you can rename or copy it by choosing the standard Emacs
+commands =rename-file= or =copy-file=. Those commands prompt for a
+filename to copy or rename and Embark will enter the file name at
+point.
+
+Other examples include: with point on a URL you can open it in a
+browser or in eww; with point on a lisp function name you can go to
+its definition, get help for it, or trace calls to it; if while
+switching buffers you spot an old one, you can kill it right there and
+continue to select another.
+
+Users of Helm or Counsel will be familiar with this way of choosing
+actions for minibuffer completion candidates, and Embark extends this
+idea to all buffers, not just the minibuffer.
+
+Embark can also gather all minibuffer completion candidates into
+their own buffer where you can examine them and run commands on them
+at your leisure. The buffer the candidates are gathered into can be in
+a dired-like major mode provided by Embark suitable for all types of
+candidates, or it can be in a major mode specific to the type of
+candidates you are collecting such as dired mode for files, ibuffer
+for buffers, occur-mode for search results in the current buffer,
+or grep-mode for search results from several files.
+
** Acting on targets
-This package provides a sort of right-click contextual menu for Emacs,
-accessed through the =embark-act= command (which you should bind to a
-convenient key), offering you relevant /actions/ to use on a /target/
-determined by the context:
+The =embark-act= command (which you should bind to a convenient key),
+acts as a prefix for a keymap offering you relevant /actions/ to use on
+a /target/ determined by the context:
- In the minibuffer, the target is the current top completion
candidate.
diff --git a/embark.texi b/embark.texi
index fb5ddd6502..71ae5e3a83 100644
--- a/embark.texi
+++ b/embark.texi
@@ -78,6 +78,35 @@ Embark, Marginalia and Consult
@node Overview
@chapter Overview
+Embark makes it easy to choose a command to run based on what is near
+point. If the command you choose prompts you for input, Embark can
+fill in the data for you. Bind the @samp{embark-act} command to a key and it
+acts like a prefix key for a keymap of @emph{actions} (commands) relevant to
+the @emph{target} found around point. For example, if point is on a file
+name, you can rename or copy it by choosing the standard Emacs
+commands @samp{rename-file} or @samp{copy-file}. Those commands prompt for a
+filename to copy or rename and Embark will enter the file name at
+point.
+
+Other examples include: with point on a URL you can open it in a
+browser or in eww; with point on a lisp function name you can go to
+its definition, get help for it, or trace calls to it; if while
+switching buffers you spot an old one, you can kill it right there and
+continue to select another.
+
+Users of Helm or Counsel will be familiar with this way of choosing
+actions for minibuffer completion candidates, and Embark extends this
+idea to all buffers, not just the minibuffer.
+
+Embark can also gather all minibuffer completion candidates into
+their own buffer where you can examine them and run commands on them
+at your leisure. The buffer the candidates are gathered into can be in
+a dired-like major mode provided by Embark suitable for all types of
+candidates, or it can be in a major mode specific to the type of
+candidates you are collecting such as dired mode for files, ibuffer
+for buffers, occur-mode for search results in the current buffer,
+or grep-mode for search results from several files.
+
@menu
* Acting on targets::
* The default action on a target::
@@ -88,10 +117,9 @@ Embark, Marginalia and Consult
@node Acting on targets
@section Acting on targets
-This package provides a sort of right-click contextual menu for Emacs,
-accessed through the @samp{embark-act} command (which you should bind to a
-convenient key), offering you relevant @emph{actions} to use on a @emph{target}
-determined by the context:
+The @samp{embark-act} command (which you should bind to a convenient key),
+acts as a prefix for a keymap offering you relevant @emph{actions} to use on
+a @emph{target} determined by the context:
@itemize
@item
