[elpa] externals/consult-recoll 8e45c4d3df 42/50: new feature: inline snippets

[ELPA Syncer]

branch: externals/consult-recoll
commit 8e45c4d3df0b5bd291d91e045354437cc0b9a74e
Author: jao <jao@gnu.org>
Commit: jao <jao@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