You could consider something like this:

The insert processors provided by org-cite use depend only on Emacs and use completing-read to select one or more citation keys for insertion. Completing-read is intended for selecting a single item, and org-cite compensates for this by letting you select multiple keys, and exiting when the selected candidate is an empty string. With a vanilla Emacs installation, you can press Tab to see a list of possible candidates, and use Tab for completion. Each time you press return with a completed candidate in the minibuffer that key is added to a list to be inserted. Press return with an empty minibuffer to finish and insert the selected keys.

If you use an alternate completion-backend like helm, ivy, selectrum, etc. you will see different behavior because they have a different concept of the selected candidate vs the current input to select the current input (which must be empty). 

With helm, you cannot mark candidates, and there are no alternate actions. You press return on each entry you want to select, and when you are done selecting them you press C-return or M-return (bound to helm-cr-empty-string) to insert all the entries at once.

With ivy, you press return on each entry you want to select, and when you are done selecting them you press C-M-j (exits with current input instead of the current candidate) to insert them.

With Selectrum, ... (don't know what the keybinding here is)

(not sure if there are other ones that should also be included)

Other insert processors may use these backends natively, so this information may not apply to them.

John

-----------------------------------
Professor John Kitchin (he/him/his)
Doherty Hall A207F
Department of Chemical Engineering
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803


On Mon, Dec 6, 2021 at 9:43 AM Bruce D'Arcus <bdarcus@gmail.com> wrote:
On Mon, Dec 6, 2021 at 9:33 AM Daniel Nemenyi <daniel@pompo.co> wrote:
> Apologies, I did ('Thanks org-ref I'm done...'), slip of the tongue.

Oh, I missed that; sorry John.

> Could have a go though if someone could give me a pointer? But if this is left to the user, perhaps we should include a line in the documentation telling them?

The completion UIs have different keybindings for this. What should
the documentation say?

Bruce