Selecting some targets to make an ad hoc candidate set

The commands for working with sets of candidates just described, namely ‘embark-act-all’, ‘embark-export’ and ‘embark-collect’ by default work with all candidates defined in the current context. For example, in the minibuffer they operate on all currently completion candidates, or in a dired buffer they work on all marked files (or all files if none are marked). Embark also has a notion of selection, where you can accumulate an ad hoc list of targets for these commands to work on.

The selection is controlled by using the ‘embark-select’ action, bound to ‘SPC’ in ‘embark-general-map’ so that it is always available (you can also give ‘embark-select’ a global key binding if you wish; when called directly, not as an action for ‘embark-act’, it will select the first target at point). Calling this action on a target toggles its membership in the current buffer’s Embark selection; that is, it adds it to selection if not selected and removes it from the selection if it was selected. Whenever the selection for a buffer is non-empty, the commands ‘embark-act-all’, ‘embark-export’ and ‘embark-collect’ will act on the selection.

To deselect all selected targets, you can use the ‘embark-select’ action through ‘embark-act-all’, since this will run ‘embark-select’ on each member of the current selection. Similarly if no targets are selected and you are in a minibuffer completion session, running ‘embark-select’ from ‘embark-act-all’ will select all the current completion candidates.

By default, whenever some targets are selected in the current buffer, a count of selected targets appears in the mode line. This can be turned off or customized through the ‘embark-selection-indicator’ user option.

The selection functionality is supported in every buffer:

• In the minibuffer this gives a convenient way to act on several completion candidates that don’t follow any simple pattern: just go through the completions selecting the ones you want, then use ‘embark-act-all’. For example, you could attach several files at once to an email.
• For Embark Collect buffers this functionality enables a dired-like workflow, in which you mark various candidates and apply an action to all at once. (It supersedes a previous ad hoc dired-like interface that was implemented only in Embark Collect buffers, with a slightly different interface.)
• In a eww buffer you could use this to select various links you wish to follow up on, and then collect them into a buffer. Similarly, while reading Emacs’s info manual you could select some symbols you want to read more about and export them to an ‘apropos-mode’ buffer.
• You can use selections in regular text or programming buffers to do complex editing operations. For example, if you have three paragraphs scattered over a file and you want to bring them together, you can select each one, insert them all somewhere and finally delete all of them (from their original locations).