branch: externals/consult-recoll
commit 8e45c4d3df0b5bd291d91e045354437cc0b9a74e
Author: jao <j...@gnu.org>
Commit: jao <j...@gnu.org>
new feature: inline snippets
---
consult-recoll.el | 51 +++++++++++++++++++++++++++++----------
readme.org | 71 +++++++++++++++++++++++++++++++++++++++----------------
2 files changed, 88 insertions(+), 34 deletions(-)
diff --git a/consult-recoll.el b/consult-recoll.el
index d885ac83e4..50ba2e5a82 100644
--- a/consult-recoll.el
+++ b/consult-recoll.el
@@ -54,16 +54,25 @@
(const :tag "All terms" ("-a"))
(list string)))
-(defcustom consult-recoll-open-fn #'find-file
+(defcustom consult-recoll-open-fn nil
"Default function used to open candidate URLs.
-It receives a single argument, the full path to the file to open.
-See also `consult-recoll-open-fns'"
- :type 'function)
+It receives the full path to the file to open and (if
+`consult-recoll-inline-snippets' is set, a page number for the
+snippet at hand. If set to nil, find-file is used. See also
+`consult-recoll-open-fns'"
+ :type '(choice (const nil) function))
(defcustom consult-recoll-open-fns ()
- "Alist mapping mime types to functions to open a selected candidate."
+ "Alist mapping mime types to functions to open a selected candidate.
+If you are setting `consult-list-snippets' to t, these functions
+will be called with two arguments (a file path and a page
+number), otherwise just with one."
:type '(alist :key-type string :value-type function))
+(defcustom consult-recoll-inline-snippets nil
+ "Show snippets as completion candidates in the minibuffer."
+ :type 'boolean)
+
(defcustom consult-recoll-group-by-mime t
"When set, list search results grouped by mime type."
:type 'boolean)
@@ -109,21 +118,28 @@ Set to nil to use the default 'title (path)' format."
(defsubst consult-recoll--candidate-url (candidate)
(get-text-property 0 'url candidate))
+(defsubst consult-recoll--candidate-page (candidate)
+ (get-text-property 0 'page candidate))
+
(defsubst consult-recoll--candidate-index (candidate)
(get-text-property 0 'index candidate))
(defsubst consult-recoll--snippets (&optional candidate)
(get-text-property 0 'snippets (or candidate consult-recoll--current)))
+(defsubst consult-recoll--find-file (file &optional _page) (find-file file))
+
(defun consult-recoll--open (candidate)
"Open file of corresponding completion CANDIDATE."
(when candidate
(let ((url (consult-recoll--candidate-url candidate))
- (opener (alist-get (consult-recoll--candidate-mime candidate)
- consult-recoll-open-fns
- (or consult-recoll-open-fn #'find-file)
- nil 'string=)))
- (funcall opener url))))
+ (open (alist-get (consult-recoll--candidate-mime candidate)
+ consult-recoll-open-fns
+ (or consult-recoll-open-fn
'consult-recoll--find-file)
+ nil 'string=)))
+ (if consult-recoll-inline-snippets
+ (funcall open url (consult-recoll--candidate-page candidate))
+ (funcall open url)))))
(defun consult-recoll--transformer (str)
"Decode STR, as returned by recollq."
@@ -141,8 +157,16 @@ Set to nil to use the default 'title (path)' format."
'index idx)))
(setq consult-recoll--current cand)
nil))
- ((string= "/SNIPPETS" str) consult-recoll--current)
- ((string= "SNIPPETS" str) nil)
+ ((string= "/SNIPPETS" str)
+ (and (not consult-recoll-inline-snippets) consult-recoll--current))
+ ((string= "SNIPPETS" str)
+ (and consult-recoll-inline-snippets consult-recoll--current))
+ ((and consult-recoll-inline-snippets consult-recoll--current)
+ (when-let* ((page (and (string-match "^\\([0-9]+\\) :" str)
+ (match-string 1 str)))
+ (pageno (and page (string-to-number page)))
+ (props (text-properties-at 0 consult-recoll--current)))
+ (apply #'propertize (concat " " str) 'page pageno props)))
(consult-recoll--current
(let ((snippets (concat (consult-recoll--snippets) "\n" str)))
(setq consult-recoll--current
@@ -191,7 +215,8 @@ If given, use INITIAL as the starting point of the query."
:require-match t
:lookup #'consult--lookup-member
:sort nil
- :state #'consult-recoll--preview
+ :state (and (not consult-recoll-inline-snippets)
+ #'consult-recoll--preview)
:group (and consult-recoll-group-by-mime
#'consult-recoll--group)
:initial (consult--async-split-initial initial)
diff --git a/readme.org b/readme.org
index d5d83adc44..67c40ba561 100644
--- a/readme.org
+++ b/readme.org
@@ -21,8 +21,6 @@ text in the found document actually matching the query.
This package provides an emacs interface to perform recoll queries, and
display its results, via [[https://github.com/minad/consult][consult]].
-[[./consult-recoll.png]]
-
* Usage
** Searching
@@ -65,18 +63,21 @@ display its results, via
[[https://github.com/minad/consult][consult]].
** Displaying results
- For each matching result, ~consult-recoll~ retrieves its title, full file
- name and mime type, and shows, by default, a line with the first two in
- the minibuffer, using the customizable faces ~consult-recoll-title-face~
and
- ~consult-recoll-url-face~. You can provide your own formatting function
- (perhaps stripping common prefixes of the file name, or displaying also
- the MIME) as the value of the customizable variable
- ~consult-recoll-format-candidate~.
+ For each matching result, ~consult-recoll~ retrieves its title, full file
+ name and mime type, and shows, by default, a line with the first two in the
+ minibuffer, using the customizable faces ~consult-recoll-title-face~ and
+ ~consult-recoll-url-face~. You can provide your own formatting function
+ (perhaps stripping common prefixes of the file name, or displaying also the
+ MIME) as the value of the customizable variable
+ ~consult-recoll-format-candidate~.
+
+ By default, ~consult-recoll~ uses consult's
[[https://github.com/minad/consult#live-previews][live previews]] to show, for
each
+ selected candidate hit, a buffer with further information, including
+ snippets of the file (when provided by recoll). The title, path and mime
+ type of the document are also shown in previews.
- ~consult-recoll~ also uses consult's
[[https://github.com/minad/consult#live-previews][live previews]] to show, for
each
- selected candidate hit, a buffer with further information, including
- snippets of the file (when provided by recoll). The title, path and mime
- type of the document are also shown in previews.
+ See [[#opening-results][Opening search results]] below for ways of
customizing how Emacs will
+ open selected results.
*** Tip: formatting results list
As mentioned, one can use ~consult-recoll-format-candidate~ to customize
how
@@ -98,17 +99,45 @@ display its results, via
[[https://github.com/minad/consult][consult]].
(setq consult-recoll-format-candidate #'jao-recoll-format)
#+end_src
+*** Tip: displaying snippets in results list
+ Instead of relying on a separate preview buffer to display snippets, you
+ can set ~consult-recoll-inline-snippets~ to ~t~ to show them in the
minibuffer,
+ as individual candidates.
*** Tip: disabling mime type groups
By default, results are listed grouped by their mime type. You can
disable grouping by setting the customizable variable
~consult-recoll-group-by-mime~ to ~nil~.
+ [[./consult-recoll.png]]
+
** Opening search results
- :PROPERTIES:
- :CUSTOM_ID: opening-results
- :END:
-
- When a search result candidate is selected, its MIME type is used to
- look up a function to open its associated file in the customizable variable
- ~consult-recoll-open-fns~. If no entry is found, consult-recoll uses the
- value of ~consult-open-fn~ as a default.
+ :PROPERTIES:
+ :CUSTOM_ID: opening-results
+ :END:
+
+ When a search result candidate is selected, its MIME type is used to look
+ up a function to open its associated file in the customizable variable
+ ~consult-recoll-open-fns~. If no entry is found, consult-recoll uses the
+ value of ~consult-open-fn~ as a default.
+
+ If ~consult-recoll-inline-snippets~ is set, the functions above take two
+ arguments: the URL of the file to open and, if present, the snippet page
+ number (or ~nil~ if it is not available, e.g., because the selected
candidate
+ is the one showing the document data)
+
+*** Tip: PDF open with external viewer
+
+ For instance, if you want to use ~zathura~ to open PDF documents, you could
+ define an elisp helper like:
+
+ #+begin_src emacs-lisp
+ (defun open-pdf/zathura (file &optional page)
+ (shell-command (format "zathura %s -P %s" file (or page 1))))
+ #+end_src
+
+ and then add it to ~consult-recoll-open-fns~:
+
+ #+begin_src emacs-lisp
+ (add-to-list 'consult-recoll-open-fns
+ '("application/pdf" . open-pdf/zathura))
+ #+end_src
