From 0bd49785a6aa4225e2d2ebcde559c1e2ee006a9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Omar=20Antol=C3=ADn?= Date: Tue, 19 Oct 2021 19:58:25 -0500 Subject: [PATCH] Documentation improvements Document indicators and embark-dwim, add links and acknowledgements (long overdue!). --- README.org | 240 ++++++++++++++++++++++++++++++---------- embark.texi | 309 +++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 430 insertions(+), 119 deletions(-) diff --git a/README.org b/README.org index 16022cc..45e6fee 100644 --- a/README.org +++ b/README.org @@ -9,22 +9,8 @@ [[https://melpa.org/#/embark][file:https://melpa.org/packages/embark-badge.svg]] :END: -* Breaking News - -- The pre-action, post-action and setup hook system has been made more - uniform and convenient. If you wrote your own hooks of any of those - types you'll have to update your configuration. Updating is easy, - see the docstrings of the new =embark-pre-action-hooks=, - =embark-setup-action-hooks= and =embark-post-action-hooks= variables for - details. - -- Embark uses something it calls /indicators/ to notify the user of what - the target of actions is and which actions are available. The - indicator protocol is in a state of flux, so please update before - reporting any bugs and, if you are using the which-key indicator, - please check the wiki to make sure you have the latest version. - * Overview + ** Acting on targets This package provides a sort of right-click contextual menu for Emacs, @@ -56,9 +42,14 @@ a few of the actions offered in the default configuration: such as setting the value directly or though the customize system, and some actions specific to commands, such as binding it to a key. -If you want a reminder of which actions are available after running -=embark-act= type =C-h= which will prompt you for an action with -completion, and remind you of the key bindings. +By default when you use =embark-act= if you don't immediately select an +action, after a short delay Embark will pop up a buffer showing a list +of actions and their corresponding key bindings. If you are using +=embark-act= outside the minibuffer, Embark will also highlight the +current target. These behaviors are configurable via the variable +=embark-indicators=. Instead of selecting an action via its key binding, +you can select it by name with completion by typing =C-h= after +=embark-act=. Everything is easily configurable: determining the current target, classifying it, and deciding which actions are offered for each type @@ -114,27 +105,43 @@ somewhat special case, actions for when the region is active. You can read about the [[https://github.com/oantolin/embark/wiki/Default-Actions][default actions and their key bindings]] on the GitHub project wiki. +** The default action on a target + +Embark has a notion of default action for a target: + +- If the target is a minibuffer completion candidate, then the default + action is whatever command opened the minibuffer in the first place. + For example if you run =kill-buffer=, then the default action will be + to kill buffers. +- If the target comes from a regular buffer (i.e., not a minibuffer), + then the default action is whatever is bound to =RET= in the keymap of + actions for that type of target. For example, in Embark's default + configuration for a URL found at point the default action is + =browse-url=, because =RET= is bound to =browse-url= in the =embark-url-map= + keymap. + +To run the default action you can press =RET= after running =embark-act=. +Note that if there are several different targets at a given location, +each has its own default action, so first cycle to the target you want +and then press =RET= to run the corresponding default action. + +There is also the =embark-dwim= which runs the default action for the +first target found. It's pretty handy in non-minibuffer buffers: with +Embark's default configuration it will + ** Working with sets of possible targets Besides acting individually on targets, Embark lets you work -collectively on a set of target /candidates/. For example, while you -are in the minibuffer the candidates are simply the possible -completions of your input. Embark provides three commands to work on -candidate sets: +collectively on a set of target /candidates/. For example, while you are +in the minibuffer the candidates are simply the possible completions +of your input. Embark provides two main commands to work on candidate +sets: - The =embark-collect-snapshot= command produces a buffer listing all the current candidates, for you to peruse and run actions on at your leisure. The candidates can be viewed in a grid or as a list showing additional annotations. -- The =embark-collect-live= variant of =embark-collect-snapshot= produces - "live" Embark Collect buffers, meaning they auto-update as the set - of candidates changes. Most users of visual completion UIs such as - Vertico, Icomplete, Selectrum or Ivy will probably either not want - to use this, to avoid seeing double, or to configure their - completion UI to hide while using =embark-collect-live=. See the - Embark wiki for [[https://github.com/oantolin/embark/wiki/Additional-Configuration#pause-selectrum-while-using-embark-collect-live][sample configuration for Selectrum]]. - - The =embark-export= command tries to open a buffer in an appropriate major mode for the set of candidates. If the candidates are files export produces a Dired buffer; if they are buffers, you get an @@ -147,11 +154,28 @@ candidate sets: adds support for exporting a list of grep results to an honest grep-mode buffer, on which you can even use [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]] if you wish. -These are always available as "actions" (although they do not act on -just the current target but on all candidates) for =embark-act= and are -bound to =S=, =L= and =E=, respectively, in =embark-general-map=. This means -that you do not have to bind your own key bindings for these -(although you can, of course), just a key binding for =embark-act=. +When in doubt choosing among these a good rule of thumb is to always +prefer =embark-export= since when an exporter to a special major mode is +available for a given type of target, it will be more featureful than +an Embark collect buffer, and if no such exporter is configured the +=embark-export= command falls back to the generic +=embark-collect-snapshot=. + +These commands are always available as "actions" (although they do not +act on just the current target but on all candidates) for =embark-act= +and are bound to =S=, =E=, respectively, in =embark-general-map=. This means +that you do not have to bind your own key bindings for these (although +you can, of course!), just a key binding for =embark-act=. + +There is also the =embark-collect-live= variant of +=embark-collect-snapshot= which produces "live" Embark Collect buffers, +meaning they auto-update as the set of candidates changes. Most users +of visual completion UIs such as Vertico, Icomplete, Selectrum or Ivy +will probably either not want to use this, to avoid seeing double (the +list of candidates is displayed both by Embark and by the completion +UI), or to configure their completion UI to hide while using +=embark-collect-live=. See the Embark wiki for [[https://github.com/oantolin/embark/wiki/Additional-Configuration#pause-selectrum-while-using-embark-collect-live][sample configuration for +Selectrum]]. ** Switching to a different command without losing what you've typed @@ -262,35 +286,83 @@ minibuffer completion candidates. (Embark does come with Ivy integration despite this.) * Advanced configuration -** Showing a reminder of available actions - -If you want a reminder of which actions are available after running -=embark-act=, use =embark-keymap-help=, which is bound to =C-h= in all of -Embark's action keymaps. That command will prompt you for the name of -an action with completion (but feel free to enter a command not among -the offered candidates!), and will also remind you of the key -bindings. You can press =@= at the prompt and then one of the key -bindings to enter the name of the corresponding action. +** Showing information about available targets and actions + +By default, if you run =embark-act= and do not immediately select an +action, after a short delay Embark will pop up a buffer called =*Embark +Actions*= containing a list of available actions with their key +bindings. You can scroll that buffer with the mouse of with the usual +commands =scroll-other-window= and =scroll-other-window-down= (bound by +default to =C-M-v= and =C-M-S-v=). + +That functionality is provided by the =embark-mixed-indicator=, but +Embark has other indicators that can provide information about the +target and its type, what other targets you can cycle to, and which +actions have key bindings in the action map for the current type of +target. Any number of indicators can be active at once and the user +option =embark-indicators= should be set to a list of the desired +indicators. + +Embark comes with the following indicators: + +- =embark-minimal-indicator=: shows a messages in the echo area or + minibuffer prompt showing the current target and the types of all + targets starting with the current one; this one is on by default. + +- =embark-highlight-indicator=: highlights the target at point; + also on by default. + +- =embark-verbose-indicator=: displays a table of actions and their key + bindings in a buffer; this is not on by default, in favor of the + mixed indicator described next. + +- =embark-mixed-indicator=: starts out by behaving as the minimal + indicator but after a short delay acts as the verbose indicator; + this is on by default. + +- =embark-isearch-highlight-indicator=: this only does something when + the current target is the symbol at point, in which case it + lazily highlights all occurrences of that symbol in the current + buffer, like isearch; also on by default. + +Users of the popular [[https://github.com/justbur/emacs-which-key][which-key]] package may prefer to use the +=embark-which-key-indicator= from the [[https://github.com/oantolin/embark/wiki/Additional-Configuration#use-which-key-like-a-key-menu-prompt][Embark wiki]]. Just copy its +definition from the wiki into your configuration and customize the +=embark-indicators= user option to exclude the mixed and verbose +indicators and to include =embark-which-key-indicator=. + +** Selecting commands via completions instead of key bindings + +As an alternative to reading the list of actions in the verbose or +mixed indicators (see the previous section for a description of +these), you can use =embark-keymap-help= after running =embark-act= which +is bound to =C-h= in all of Embark's action keymaps. That command will +prompt you for the name of an action with completion (but feel free to +enter a command that is not among the offered candidates!), and will +also remind you of the key bindings. You can press =@= at the prompt and +then one of the key bindings to enter the name of the corresponding +action. + +You may think that with the =*Embark Actions*= buffer popping up to +remind you of the key bindings you'd never want to use completion to +select an action by name, but personally I find that typing a small +portion of the action name to narrow down the list of candidates feels +significantly faster than visually scanning the entire list of actions. If you find you prefer entering actions that way, you can configure embark to always prompt you for actions by setting the variable =embark-prompter= to =embark-completing-read-prompter=. -If you want to see the actions and their key bindings, but want to use -the key bindings rather than completing the command name, you can -install [[https://github.com/justbur/emacs-which-key][which-key]] and add the =embark-which-key-indicator= from [[https://github.com/oantolin/embark/wiki/Additional-Configuration#use-which-key-like-a-key-menu-prompt][Embark -wiki]] to your configuration. - ** Quitting the minibuffer after an action By default, if you call =embark-act= from the minibuffer it quits the minibuffer after performing the action. You can change this by setting -the customizable variable =embark-quit-after-action= to =nil=. That -variable controls whether or not =embark-act= quits the minibuffer when -you call it without a prefix argument, and you can select the opposite -behavior to what the variable says by calling =embark-act= with =C-u=. -Note that both the variable =embark-quit-after-action= and =C-u= have no -effect when you call =embark-act= outside the minibuffer. +the user option =embark-quit-after-action= to =nil=. That variable +controls whether or not =embark-act= quits the minibuffer when you call +it without a prefix argument, and you can select the opposite behavior +to what the variable says by calling =embark-act= with =C-u=. Note that +both the variable =embark-quit-after-action= and =C-u= have no effect when +you call =embark-act= outside the minibuffer. Having =embark-act= /not/ quit the minibuffer can be useful to turn commands into little "thing managers". For example, you can use @@ -673,3 +745,61 @@ the Marginalia package. 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=. + +* Resources + +If you want to learn more about how others have used Embark here are +some links to read: + +- [[https://karthinks.com/software/fifteen-ways-to-use-embark/][Fifteen ways to use Embark]], a blog post by Karthik Chikmagalur. +- [[https://protesilaos.com/dotemacs/][Protesilaos Stavrou's dotemacs]], look for the section called + "Extended minibuffer actions and more (embark.el and + prot-embark.el)" + +And some videos to watch: + +- [[https://protesilaos.com/codelog/2021-01-09-emacs-embark-extras/][Embark and my extras]] by Protesilaos Stavrou. +- [[https://youtu.be/qpoQiiinCtY][Embark -- Key features and tweaks]] by Raoul Comninos on the + Emacs-Elements YouTube channel. +- [[https://youtu.be/WsxXr1ncukY][Livestreamed: Adding an Embark context action to send a stream + message]] by Sacha Chua. +- [[https://youtu.be/qk2Is_sC8Lk][System Crafters Live! - The Many Uses of Embark]] by David Wilson. + +* Acknowledgements + +While I, Omar Antolín Camarena, have written most of the Embark code +and remain very stubborn about some of the design decisions, Embark +has recieved substantial help from a number of other people which this +document has neglected to mention for far too long. In particular, +Daniel Mendler has been absolutely invaluable, implementing several +important features, and providing a lot of useful advice. + +Code contributions: + +- [[https://github.com/minad][Daniel Mendler]] +- [[https://github.com/clemera/][Clemens Radermacher]] +- [[https://codeberg.org/jao/][José Antonio Ortega Ruiz]] +- [[https://github.com/iyefrat][Itai Y. Efrat]] +- [[https://github.com/a13][a13]] +- [[https://github.com/jakanakaevangeli][jakanakaevangeli]] +- [[https://github.com/mihakam][mihakam]] +- [[https://github.com/leungbk][Brian Leung]] +- [[https://github.com/karthink][Karthik Chikmagalur]] +- [[https://github.com/roshanshariff][Roshan Shariff]] +- [[https://github.com/condy0919][condy0919]] +- [[https://github.com/DamienCassou][Damien Cassou]] +- [[https://github.com/JimDBh][JimDBh]] + +Advice and useful discussions: + +- [[https://github.com/minad][Daniel Mendler]] +- [[https://gitlab.com/protesilaos/][Protesilaos Stavrou]] +- [[https://github.com/clemera/][Clemens Radermacher]] +- [[https://github.com/hmelman/][Howard Melman]] +- [[https://github.com/astoff][Augusto Stoffel]] +- [[https://github.com/bdarcus][Bruce d'Arcus]] +- [[https://github.com/jdtsmith][JD Smith]] +- [[https://github.com/karthink][Karthik Chikmagalur]] +- [[https://github.com/jakanakaevangeli][jakanakaevangeli]] +- [[https://github.com/iyefrat][Itai Y. Efrat]] +- [[https://github.com/mohkale][Mohsin Kaleem]] diff --git a/embark.texi b/embark.texi index 2fc4d11..c6c3a03 100644 --- a/embark.texi +++ b/embark.texi @@ -25,12 +25,13 @@ @end ifnottex @menu -* Breaking News:: * Overview:: * Quick start:: * Advanced configuration:: * How does Embark call the actions?:: * Embark, Marginalia and Consult: Embark Marginalia and Consult. +* Resources:: +* Acknowledgements:: @detailmenu --- The Detailed Node Listing --- @@ -38,12 +39,14 @@ Overview * Acting on targets:: +* The default action on a target:: * Working with sets of possible targets:: * Switching to a different command without losing what you've typed:: Advanced configuration -* Showing a reminder of available actions:: +* 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:: @@ -62,31 +65,12 @@ How does Embark call the actions? @end detailmenu @end menu -@node Breaking News -@chapter Breaking News - -@itemize -@item -The pre-action, post-action and setup hook system has been made more -uniform and convenient. If you wrote your own hooks of any of those -types you'll have to update your configuration. Updating is easy, -see the docstrings of the new @samp{embark-pre-action-hooks}, -@samp{embark-setup-action-hooks} and @samp{embark-post-action-hooks} variables for -details. - -@item -Embark uses something it calls @emph{indicators} to notify the user of what -the target of actions is and which actions are available. The -indicator protocol is in a state of flux, so please update before -reporting any bugs and, if you are using the which-key indicator, -please check the wiki to make sure you have the latest version. -@end itemize - @node Overview @chapter Overview @menu * Acting on targets:: +* The default action on a target:: * Working with sets of possible targets:: * Switching to a different command without losing what you've typed:: @end menu @@ -134,9 +118,14 @@ such as setting the value directly or though the customize system, and some actions specific to commands, such as binding it to a key. @end itemize -If you want a reminder of which actions are available after running -@samp{embark-act} type @samp{C-h} which will prompt you for an action with -completion, and remind you of the key bindings. +By default when you use @samp{embark-act} if you don't immediately select an +action, after a short delay Embark will pop up a buffer showing a list +of actions and their corresponding key bindings. If you are using +@samp{embark-act} outside the minibuffer, Embark will also highlight the +current target. These behaviors are configurable via the variable +@samp{embark-indicators}. Instead of selecting an action via its key binding, +you can select it by name with completion by typing @samp{C-h} after +@samp{embark-act}. Everything is easily configurable: determining the current target, classifying it, and deciding which actions are offered for each type @@ -192,14 +181,43 @@ somewhat special case, actions for when the region is active. You can read about the @uref{https://github.com/oantolin/embark/wiki/Default-Actions, default actions and their key bindings} on the GitHub project wiki. +@node The default action on a target +@section The default action on a target + +Embark has a notion of default action for a target: + +@itemize +@item +If the target is a minibuffer completion candidate, then the default +action is whatever command opened the minibuffer in the first place. +For example if you run @samp{kill-buffer}, then the default action will be +to kill buffers. +@item +If the target comes from a regular buffer (i.e., not a minibuffer), +then the default action is whatever is bound to @samp{RET} in the keymap of +actions for that type of target. For example, in Embark's default +configuration for a URL found at point the default action is +@samp{browse-url}, because @samp{RET} is bound to @samp{browse-url} in the @samp{embark-url-map} +keymap. +@end itemize + +To run the default action you can press @samp{RET} after running @samp{embark-act}. +Note that if there are several different targets at a given location, +each has its own default action, so first cycle to the target you want +and then press @samp{RET} to run the corresponding default action. + +There is also the @samp{embark-dwim} which runs the default action for the +first target found. It's pretty handy in non-minibuffer buffers: with +Embark's default configuration it will + @node Working with sets of possible targets @section Working with sets of possible targets Besides acting individually on targets, Embark lets you work -collectively on a set of target @emph{candidates}. For example, while you -are in the minibuffer the candidates are simply the possible -completions of your input. Embark provides three commands to work on -candidate sets: +collectively on a set of target @emph{candidates}. For example, while you are +in the minibuffer the candidates are simply the possible completions +of your input. Embark provides two main commands to work on candidate +sets: @itemize @item @@ -208,15 +226,6 @@ the current candidates, for you to peruse and run actions on at your leisure. The candidates can be viewed in a grid or as a list showing additional annotations. -@item -The @samp{embark-collect-live} variant of @samp{embark-collect-snapshot} produces -``live'' Embark Collect buffers, meaning they auto-update as the set -of candidates changes. Most users of visual completion UIs such as -Vertico, Icomplete, Selectrum or Ivy will probably either not want -to use this, to avoid seeing double, or to configure their -completion UI to hide while using @samp{embark-collect-live}. See the -Embark wiki for @uref{https://github.com/oantolin/embark/wiki/Additional-Configuration#pause-selectrum-while-using-embark-collect-live, sample configuration for Selectrum}. - @item The @samp{embark-export} command tries to open a buffer in an appropriate major mode for the set of candidates. If the candidates are files @@ -231,11 +240,28 @@ adds support for exporting a list of grep results to an honest grep-mode buffer, on which you can even use @uref{https://github.com/mhayashi1120/Emacs-wgrep, wgrep} if you wish. @end itemize -These are always available as ``actions'' (although they do not act on -just the current target but on all candidates) for @samp{embark-act} and are -bound to @samp{S}, @samp{L} and @samp{E}, respectively, in @samp{embark-general-map}. This means -that you do not have to bind your own key bindings for these -(although you can, of course), just a key binding for @samp{embark-act}. +When in doubt choosing among these a good rule of thumb is to always +prefer @samp{embark-export} since when an exporter to a special major mode is +available for a given type of target, it will be more featureful than +an Embark collect buffer, and if no such exporter is configured the +@samp{embark-export} command falls back to the generic +@samp{embark-collect-snapshot}. + +These commands are always available as ``actions'' (although they do not +act on just the current target but on all candidates) for @samp{embark-act} +and are bound to @samp{S}, @samp{E}, respectively, in @samp{embark-general-map}. This means +that you do not have to bind your own key bindings for these (although +you can, of course!), just a key binding for @samp{embark-act}. + +There is also the @samp{embark-collect-live} variant of +@samp{embark-collect-snapshot} which produces ``live'' Embark Collect buffers, +meaning they auto-update as the set of candidates changes. Most users +of visual completion UIs such as Vertico, Icomplete, Selectrum or Ivy +will probably either not want to use this, to avoid seeing double (the +list of candidates is displayed both by Embark and by the completion +UI), or to configure their completion UI to hide while using +@samp{embark-collect-live}. See the Embark wiki for @uref{https://github.com/oantolin/embark/wiki/Additional-Configuration#pause-selectrum-while-using-embark-collect-live, sample configuration for +Selectrum}. @node Switching to a different command without losing what you've typed @section Switching to a different command without losing what you've typed @@ -351,7 +377,8 @@ integration despite this.) @chapter Advanced configuration @menu -* Showing a reminder of available actions:: +* 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:: @@ -359,37 +386,93 @@ integration despite this.) * Defining actions for new categories of targets:: @end menu -@node Showing a reminder of available actions -@section Showing a reminder of available actions +@node Showing information about available targets and actions +@section Showing information about available targets and actions + +By default, if you run @samp{embark-act} and do not immediately select an +action, after a short delay Embark will pop up a buffer called @samp{*Embark +Actions*} containing a list of available actions with their key +bindings. You can scroll that buffer with the mouse of with the usual +commands @samp{scroll-other-window} and @samp{scroll-other-window-down} (bound by +default to @samp{C-M-v} and @samp{C-M-S-v}). + +That functionality is provided by the @samp{embark-mixed-indicator}, but +Embark has other indicators that can provide information about the +target and its type, what other targets you can cycle to, and which +actions have key bindings in the action map for the current type of +target. Any number of indicators can be active at once and the user +option @samp{embark-indicators} should be set to a list of the desired +indicators. + +Embark comes with the following indicators: -If you want a reminder of which actions are available after running -@samp{embark-act}, use @samp{embark-keymap-help}, which is bound to @samp{C-h} in all of -Embark's action keymaps. That command will prompt you for the name of -an action with completion (but feel free to enter a command not among -the offered candidates!), and will also remind you of the key -bindings. You can press @samp{@@} at the prompt and then one of the key -bindings to enter the name of the corresponding action. +@itemize +@item +@samp{embark-minimal-indicator}: shows a messages in the echo area or +minibuffer prompt showing the current target and the types of all +targets starting with the current one; this one is on by default. + +@item +@samp{embark-highlight-indicator}: highlights the target at point; +also on by default. + +@item +@samp{embark-verbose-indicator}: displays a table of actions and their key +bindings in a buffer; this is not on by default, in favor of the +mixed indicator described next. + +@item +@samp{embark-mixed-indicator}: starts out by behaving as the minimal +indicator but after a short delay acts as the verbose indicator; +this is on by default. + +@item +@samp{embark-isearch-highlight-indicator}: this only does something when +the current target is the symbol at point, in which case it +lazily highlights all occurrences of that symbol in the current +buffer, like isearch; also on by default. +@end itemize + +Users of the popular @uref{https://github.com/justbur/emacs-which-key, which-key} package may prefer to use the +@samp{embark-which-key-indicator} from the @uref{https://github.com/oantolin/embark/wiki/Additional-Configuration#use-which-key-like-a-key-menu-prompt, Embark wiki}. Just copy its +definition from the wiki into your configuration and customize the +@samp{embark-indicators} user option to exclude the mixed and verbose +indicators and to include @samp{embark-which-key-indicator}. + +@node Selecting commands via completions instead of key bindings +@section Selecting commands via completions instead of key bindings + +As an alternative to reading the list of actions in the verbose or +mixed indicators (see the previous section for a description of +these), you can use @samp{embark-keymap-help} after running @samp{embark-act} which +is bound to @samp{C-h} in all of Embark's action keymaps. That command will +prompt you for the name of an action with completion (but feel free to +enter a command that is not among the offered candidates!), and will +also remind you of the key bindings. You can press @samp{@@} at the prompt and +then one of the key bindings to enter the name of the corresponding +action. + +You may think that with the @samp{*Embark Actions*} buffer popping up to +remind you of the key bindings you'd never want to use completion to +select an action by name, but personally I find that typing a small +portion of the action name to narrow down the list of candidates feels +significantly faster than visually scanning the entire list of actions. If you find you prefer entering actions that way, you can configure embark to always prompt you for actions by setting the variable @samp{embark-prompter} to @samp{embark-completing-read-prompter}. -If you want to see the actions and their key bindings, but want to use -the key bindings rather than completing the command name, you can -install @uref{https://github.com/justbur/emacs-which-key, which-key} and add the @samp{embark-which-key-indicator} from @uref{https://github.com/oantolin/embark/wiki/Additional-Configuration#use-which-key-like-a-key-menu-prompt, Embark -wiki} to your configuration. - @node Quitting the minibuffer after an action @section Quitting the minibuffer after an action By default, if you call @samp{embark-act} from the minibuffer it quits the minibuffer after performing the action. You can change this by setting -the customizable variable @samp{embark-quit-after-action} to @samp{nil}. That -variable controls whether or not @samp{embark-act} quits the minibuffer when -you call it without a prefix argument, and you can select the opposite -behavior to what the variable says by calling @samp{embark-act} with @samp{C-u}. -Note that both the variable @samp{embark-quit-after-action} and @samp{C-u} have no -effect when you call @samp{embark-act} outside the minibuffer. +the user option @samp{embark-quit-after-action} to @samp{nil}. That variable +controls whether or not @samp{embark-act} quits the minibuffer when you call +it without a prefix argument, and you can select the opposite behavior +to what the variable says by calling @samp{embark-act} with @samp{C-u}. Note that +both the variable @samp{embark-quit-after-action} and @samp{C-u} have no effect when +you call @samp{embark-act} outside the minibuffer. Having @samp{embark-act} @emph{not} quit the minibuffer can be useful to turn commands into little ``thing managers''. For example, you can use @@ -811,4 +894,102 @@ add @uref{https://github.com/minad/consult/blob/373498acb76b9395e5e590fb8e39f671 use @samp{consult-file-externally}. @end itemize +@node Resources +@chapter Resources + +If you want to learn more about how others have used Embark here are +some links to read: + +@itemize +@item +@uref{https://karthinks.com/software/fifteen-ways-to-use-embark/, Fifteen ways to use Embark}, a blog post by Karthik Chikmagalur. +@item +@uref{https://protesilaos.com/dotemacs/, Protesilaos Stavrou's dotemacs}, look for the section called +``Extended minibuffer actions and more (embark.el and +prot-embark.el)'' +@end itemize + +And some videos to watch: + +@itemize +@item +@uref{https://protesilaos.com/codelog/2021-01-09-emacs-embark-extras/, Embark and my extras} by Protesilaos Stavrou. +@item +@uref{https://youtu.be/qpoQiiinCtY, Embark -- Key features and tweaks} by Raoul Comninos on the +Emacs-Elements YouTube channel. +@item +@uref{https://youtu.be/WsxXr1ncukY, Livestreamed: Adding an Embark context action to send a stream +message} by Sacha Chua. +@item +@uref{https://youtu.be/qk2Is_sC8Lk, System Crafters Live! - The Many Uses of Embark} by David Wilson. +@end itemize + +@node Acknowledgements +@chapter Acknowledgements + +While I, Omar Antolín Camarena, have written most of the Embark code +and remain very stubborn about some of the design decisions, Embark +has recieved substantial help from a number of other people which this +document has neglected to mention for far too long. In particular, +Daniel Mendler has been absolutely invaluable, implementing several +important features, and providing a lot of useful advice. + +Code contributions: + +@itemize +@item +@uref{https://github.com/minad, Daniel Mendler} +@item +@uref{https://github.com/clemera/, Clemens Radermacher} +@item +@uref{https://codeberg.org/jao/, José Antonio Ortega Ruiz} +@item +@uref{https://github.com/iyefrat, Itai Y@. Efrat} +@item +@uref{https://github.com/a13, a13} +@item +@uref{https://github.com/jakanakaevangeli, jakanakaevangeli} +@item +@uref{https://github.com/mihakam, mihakam} +@item +@uref{https://github.com/leungbk, Brian Leung} +@item +@uref{https://github.com/karthink, Karthik Chikmagalur} +@item +@uref{https://github.com/roshanshariff, Roshan Shariff} +@item +@uref{https://github.com/condy0919, condy0919} +@item +@uref{https://github.com/DamienCassou, Damien Cassou} +@item +@uref{https://github.com/JimDBh, JimDBh} +@end itemize + +Advice and useful discussions: + +@itemize +@item +@uref{https://github.com/minad, Daniel Mendler} +@item +@uref{https://gitlab.com/protesilaos/, Protesilaos Stavrou} +@item +@uref{https://github.com/clemera/, Clemens Radermacher} +@item +@uref{https://github.com/hmelman/, Howard Melman} +@item +@uref{https://github.com/astoff, Augusto Stoffel} +@item +@uref{https://github.com/bdarcus, Bruce d'Arcus} +@item +@uref{https://github.com/jdtsmith, JD Smith} +@item +@uref{https://github.com/karthink, Karthik Chikmagalur} +@item +@uref{https://github.com/jakanakaevangeli, jakanakaevangeli} +@item +@uref{https://github.com/iyefrat, Itai Y@. Efrat} +@item +@uref{https://github.com/mohkale, Mohsin Kaleem} +@end itemize + @bye \ No newline at end of file