docs

README.org

@@ -108,6 +108,8 @@ If you would like to try vertico instead, just do =M-x vertico-mode=.
     :CUSTOM_ID: rich-ui
     :END:
 
+**** Browsing
+
 There are three sections of the browsing UI.
 
 1. The prefix, exploiting the affixation feature only available starting with Emacs 28, and holding the symbols to indicate the presence of PDFs or notes associated with the entries.
@@ -154,7 +156,7 @@ Here's how to configure it to use =all-the-icons=:
        :group 'all-the-icons-faces)
 #+END_SRC
 
-*** History and predefined searches
+**** History and predefined searches
     :PROPERTIES:
     :CUSTOM_ID: history-and-predefined-searches
     :END:
@@ -174,7 +176,7 @@ You then have two ways to access these strings from the completion prompt:
 =Bibtex-actions= also preserves the history of your selections (see caveat below about multiple candidate selection though), which are also accessible in your completion UI, but by using =M-p=.
 You can save this history across sessions by adding =bibtex-actions-history= to =savehist-additional-variables=.
 
-*** Pre-filtering entries
+**** Pre-filtering entries
     :PROPERTIES:
     :CUSTOM_ID: prefiltering-entries
     :END:
@@ -201,7 +203,7 @@ If you want to modify those values, or remove them entirely, you can set =bibtex
     (source . "has:link\\|has:pdf"))
 #+end_src
 
-*** Refreshing the library display
+**** Refreshing the library display
     :PROPERTIES:
     :CUSTOM_ID: refreshing-the-library-display
     :END:
@@ -233,6 +235,11 @@ You can also extend this to do the same thing for your PDF files, or notes:
 
 For additional configuration options on this, see [[https://github.com/bdarcus/bibtex-actions/wiki/Configuration#automating-path-watches][the wiki]].
 
+*** Selection
+
+Bibtex-actions implements a custom UI to select candidates.
+Unlike the standard =completing-read-multiple= fallback option, with this UI you should only use `RET` to select and deselect items, and then `RET` to run the command.
+
 *** Finding citation keys at point
     :PROPERTIES:
     :CUSTOM_ID: finding-citation-keys-at-point