[elpa] externals/denote a47f32ec71 184/355: Implement new backlink facility

[ELPA Syncer]

branch: externals/denote
commit a47f32ec71d3ef5f26892b962efb9d487bc3086a
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Implement new backlink facility
---
 README.org     |  23 +++++++++++-
 denote-link.el | 117 +++++++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 105 insertions(+), 35 deletions(-)

diff --git a/README.org b/README.org
index 65f9c1a6ea..cf879c0e3a 100644
--- a/README.org
+++ b/README.org
@@ -578,10 +578,29 @@ It uses minibuffer completion to visit a file that is 
linked to from the
 current note.  The candidates have the correct metadata, meaning that a
 package such as =marginalia= will display the correct annotations.
 
-** TODO Finalise first version of denote-link.el [1/4]
+#+findex: denote-link-backlinks
+The command ~denote-link-backlinks~ produces a bespoke buffer which
+displays the file name of all notes linking to the current one.  Each
+file name appears on its own line and is buttonized so that it performs
+the action of visiting the referenced file.
+
+#+vindex: denote-link-fontify-backlinks
+The backlinks' buffer is fontified by default, though the user has the
+~denote-link-fontify-backlinks~ to disable this effect, by setting the
+variable to nil.
+
+#+vindex: denote-link-backlinks-display-buffer-action
+The placement of the backlinks' buffer is subject to the user option
+~denote-link-backlinks-display-buffer-action~.  Due to the nature of the
+underlying ~display-buffer~ infrastructure, this is an advanced feature.
+By default, the backlinks' buffer is displayed below the current window.
+The doc string of our user option includes a configuration that places
+the buffer in a left side window instead.
+
+** TODO Finalise first version of denote-link.el [2/4]
 *** DONE Add generic linking mechanism
+*** DONE Flesh out the ~denote-link-backlinks~ prototype
 *** TODO Check if denote: is the right link type for Org/Markdown
-*** TODO Flesh out the ~denote-link-backlinks~ prototype
 *** TODO Document use of Embark with ~denote-link-find-file~
 
 * Fontification in Dired
diff --git a/denote-link.el b/denote-link.el
index d71abe656c..4572677cf9 100644
--- a/denote-link.el
+++ b/denote-link.el
@@ -36,6 +36,40 @@
   "Link facility for Denote."
   :group 'denote)
 
+;;;; User options
+
+(defcustom denote-link-fontify-backlinks nil
+  "When non-nil, apply faces to files in the backlinks' buffer."
+  :type 'boolean
+  :group 'denote-link)
+
+(defcustom denote-link-backlinks-display-buffer-action
+  '((display-buffer-reuse-window display-buffer-below-selected)
+    (window-height . fit-window-to-buffer))
+  "The action used to display the current file's backlinks buffer.
+
+The value has the form (FUNCTION . ALIST), where FUNCTION is
+either an \"action function\", a list thereof, or a possibly
+empty list.  ALIST is a list of \"action alist\" which may be
+omitted (or be empty).
+
+Sample configuration to display the buffer in a side window on
+the left of the Emacs frame:
+
+    (setq denote-link-backlinks-display-buffer-action
+          (quote ((display-buffer-reuse-window
+                   display-buffer-in-side-window)
+                  (side . left)
+                  (slot . 99)
+                  (window-width . 0.3))))
+
+See Info node `(elisp) Displaying Buffers' for more details
+and/or the documentation string of `display-buffer'."
+  :type '(cons (choice (function :tag "Display Function")
+                       (repeat :tag "Display Functions" function))
+               alist)
+  :group 'denote-link)
+
 ;;;; Link to note
 
 ;; FIXME 2022-06-14 16:58:24 +0300: Plain text links will use the
@@ -159,51 +193,68 @@ Run `denote-link-insert-functions' afterwards."
   'action #'denote-link--find-file
   'face 'unspecified)
 
+;; NOTE 2022-06-15: I add this as a variable for advanced users who may
+;; prefer something else.  If there is demand for it, we can make it a
+;; defcustom, but I think it would be premature at this stage.
+(defvar denote-link-buton-action #'find-file-other-window
+  "Action for `denote-link--find-file'.")
+
 (defun denote-link--find-file (button)
-  "Action for BUTTON."
-  (find-file (buffer-substring (button-start button) (button-end button))))
+  "Action for BUTTON to `find-file'."
+  (funcall denote-link-buton-action (buffer-substring (button-start button) 
(button-end button))))
 
 (declare-function denote-dired-mode "denote-dired")
 
-(defun denote-link--prettify-compilation (buffer _output)
-  "Narrow to grep matches in BUFFER.
-PROOF-OF-CONCEPT."
-  (with-current-buffer buffer
-    (narrow-to-region
-     (progn
-       (re-search-forward "find" nil t)
-       (forward-line 1)
-       (point))
-     (progn
-       (re-search-forward "Grep" nil t)
-       (forward-line -1)
-       (point)))
-    (save-excursion
+(defun denote-link--display-buffer (buf)
+  "Run `display-buffer' on BUF."
+  (display-buffer
+   buf
+   `(,@denote-link-backlinks-display-buffer-action)))
+
+(defun denote-link--prepare-backlinks (id files &optional title)
+  "Create backlinks' buffer for ID including FILES.
+Use optional TITLE for a prettier heading."
+  (let ((inhibit-read-only t)
+        (buf (format "*denote-backlinks to %s*" id)))
+    (with-current-buffer (get-buffer-create buf)
+      (erase-buffer)
+      (special-mode)
+      (goto-char (point-min))
+      (when-let* ((title)
+                  (heading (format "Backlinks to %S (%s)" title id))
+                  (l (length heading)))
+        (insert (format "%s\n%s\n\n" heading (make-string l ?-))))
+      (mapc (lambda (f)
+              (insert (file-name-nondirectory f))
+              (make-button (point-at-bol) (point-at-eol) :type 
'denote-link-find-file)
+              (newline))
+            files)
       (goto-char (point-min))
-      (while (re-search-forward (format "%s" denote--file-regexp) (point-max) 
t)
-        (make-button (match-beginning 0) (match-end 0) :type 
'denote-link-find-file)))
-    (denote-dired-mode 1)))
+      ;; NOTE 2022-06-15: Technically this is not Dired.  Maybe we
+      ;; should abstract the fontification into a general purpose
+      ;; minor-mode.
+      (when denote-link-fontify-backlinks
+        (denote-dired-mode 1)))
+    (denote-link--display-buffer buf)))
 
 ;;;###autoload
 (defun denote-link-backlinks ()
-  "PROOF-OF-CONCEPT."
+  "Produce a buffer with files linking to current note.
+Each file is a clickable/actionable button that visits the
+referenced entry.  Files are fontified if the user option
+`denote-link-fontify-backlinks' is non-nil.
+
+The placement of the backlinks' buffer is controlled by the user
+option `denote-link-backlinks-display-buffer-action'.  By
+default, it will show up below the current window."
   (interactive)
   (let* ((default-directory (denote-directory))
          (file (file-name-nondirectory (buffer-file-name)))
          (id (denote-retrieve--filename-identifier file))
-         (buf (format "*denote-backlinks to %s*" id)))
-  (compilation-start
-   (format "find * -type f ! -name '%s' -exec %s --color=auto -l -m 1 -e %s %s 
%s"
-           file
-           grep-program
-           id
-           (shell-quote-argument "{}")
-                  (shell-quote-argument ";"))
-   'grep-mode
-   (lambda (_) buf)
-   t)
-  (with-current-buffer buf
-    (add-hook 'compilation-finish-functions 
#'denote-link--prettify-compilation nil t))))
+         (title (denote-retrieve--value file 
denote-retrieve--title-front-matter-regexp)))
+    (if-let ((files (denote-retrieve--proces-grep id)))
+        (denote-link--prepare-backlinks id files title)
+      (user-error "No links to the current note"))))
 
 (provide 'denote-link)
 ;;; denote-link.el ends here