From c8731ecd5db2beecc434a65448a7302212aab95a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tor-bj=C3=B6rn=20Claesson?= > Date: Mon, 11 Nov 2024 11:46:32 +0200 Subject: [PATCH] lisp/oc-basic.el: Transient menu for following citations * lisp/oc-basic.el (require 'transient): Pull in transient. (org-cite-basic-follow-ask): New customization option. should `org-cite-basic-follow' should prompt the user for an action? (org-cite-basic-follow-actions): New customization option, that specifies the contents of the transient menu. (org-cite-basic-follow): New function. Displays a menu asking how to follow a citation if called with a negative prefix, or `org-cite-basic-follow-ask' is non-nil. Otherwise, it retains the default behaviour of opening the bibliography entry. (org-cite-basic-follow--parse-suffix-specification, org-cite-basic-follow--setup): Helper functions for `org-cite-basic-follow'. (org-cite-register-processor 'basic): Update the basic citation processor to follow citations using `org-cite-basic-follow'. * etc/ORG_NEWS (Menu for choosing how to follow citations): Describe the new feature (New option ~org-cite-basic-follow-ask~): Describe this new customization option. (New option ~org-cite-basic-follow-actions~): Describe this new customization option, which specifies the layaout of the `org-cite-basic-follow' transient menu. This change was co-authored with much support from Ihor Radchenko and Jonas Bernoulli, thanks! --- etc/ORG-NEWS | 22 +++++++++++++ lisp/oc-basic.el | 84 ++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 103 insertions(+), 3 deletions(-) diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index de4f11b25..cf87e11bf 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -114,6 +114,17 @@ The keybindings in the repeat-maps can be changed by customizing See the new [[info:org#Repeating commands]["Repeating commands"]] section in Org mode manual. +*** Menu for choosing how to follow citations +If invoked with a prefix of C-- C-u, following citations with +the org-cite-basic citation backend will no present a transient menu, +offering choices for how to follow citations. + +The contents of this menu can be customized in +~org-cite-basic-follow-actions~. + +In order to always show this menu, set ~org-cite-basic-follow-ask~ +to non-nil. + ** New and changed options # Chanes deadling with changing default values of customizations, @@ -158,6 +169,17 @@ English. The default value is ~t~ as the CSL standard assumes that English titles are specified in sentence-case but the bibtex bibliography format requires them to be written in title-case. +*** New option ~org-cite-basic-follow-ask~ +When this option is non-nil, following a citation with the basic citation +backend will present a transient menu with choices for how to follow the +citation. +If nil, following a citation will open its bibliography entry. + +*** New option ~org-cite-basic-follow-actions~ +This option specifies the options presented by ~org-cite-basic-follow~ +if it is invoked with a C-- C-u prefix or ~org-cite-basic-follow-ask~ +is non-nil. + ** New functions and changes in function arguments # This also includes changes in function behavior from Elisp perspective. diff --git a/lisp/oc-basic.el b/lisp/oc-basic.el index e207a1997..8add329b7 100644 --- a/lisp/oc-basic.el +++ b/lisp/oc-basic.el @@ -74,6 +74,7 @@ (require 'map) (require 'oc) (require 'seq) +(require 'transient) (declare-function org-open-at-point "org" (&optional arg)) (declare-function org-open-file "org" (path &optional in-emacs line search)) @@ -140,6 +141,36 @@ :type 'face :safe #'facep) +(defcustom org-cite-basic-follow-ask nil + "Should `org-cite-basic' ask how to follow citations? + +When this option is nil, `org-cite-basic-follow' opens the bibliography entry. +Otherwise, `org-cite-basic-follow' will display a transient menu prompting the +user for an action. The contents of this menu can be customized in +`org-cite-basic-follow-actions'." + :group 'org-cite + :package-version '(Org . "9.8") + :type 'boolean) + +(defcustom org-cite-basic-follow-actions + '[["Open" + ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]] + "Actions in the `org-cite-basic-follow' transient menu. + +This option uses the same syntax as `transient-define-prefix', see Info node +`(transient)Binding Suffix and Infix Commands'. In addition, it is possible +to specify a function call for the COMMAND part, where !citation, +!prefix, and !citation-key can be used to access those values. + +If COMMAND is a lambda form, it can access the citation and prefix like this: + + (lambda (citation prefix) + (interactive (transient-scope)) + ...)" + :group 'org-cite + :package-version '(Org . "9.8") + :type 'sexp) + ;;; Internal variables (defvar org-cite-basic--bibliography-cache nil @@ -832,6 +863,53 @@ present in the citation." (bibtex-set-dialect) (bibtex-search-entry key))))) +(transient-define-prefix org-cite-basic-follow (citation &optional prefix) + "Follow citation. + +This transient is invoked through `org-open-at-point'. +When `org-open-at-point' is invoked with a negative prefix, +or `org-cite-basic-follow-ask' is non-nil, it will present +a transient menu prompting the user for an action. Otherwise, +it will open the bibliography entry for the citation at point. + +Suffixes can not be added to this transient menu using the ordinary +`transient-append-suffix' or `transient-insert-suffix', instead, the +contents of the menu are defined in the variable +`org-cite-basic-follow-actions'." + [:class transient-columns + :setup-children org-cite-basic-follow--setup + :pad-keys t] + (interactive) + (if (or org-cite-basic-follow-ask + (equal prefix '(-4))) + (transient-setup 'org-cite-basic-follow nil nil + :scope (list citation prefix)) + (org-cite-basic-goto citation prefix))) + +(defun org-cite-basic-follow--parse-suffix-specification (specification) + (pcase specification + ((and val `(,key ,desc (,fn . ,fn-args) . ,other)) + (if (eq fn 'lambda) val + `(,key ,desc + (lambda () + (interactive) + (let ((!citation (car (transient-scope))) + (!prefix (cadr (transient-scope))) + (!citation-key + (org-element-property :key (car (transient-scope))))) + (,fn ,@fn-args))) + ,@other))) + (other other))) + +(defun org-cite-basic-follow--setup (_) + (transient-parse-suffixes + 'org-cite-basic-follow + (cl-map 'vector + (lambda (group) + (cl-map 'vector #'org-cite-basic-follow--parse-suffix-specification + group)) + org-cite-basic-follow-actions))) + ;;; "Insert" capability (defun org-cite-basic--complete-style (_) @@ -920,9 +998,9 @@ Raise an error when no bibliography is set in the buffer." :activate #'org-cite-basic-activate :export-citation #'org-cite-basic-export-citation :export-bibliography #'org-cite-basic-export-bibliography - :follow #'org-cite-basic-goto - :insert (org-cite-make-insert-processor #'org-cite-basic--complete-key - #'org-cite-basic--complete-style) + :follow #'org-cite-basic-follow + :insert (org-cite-make-insert-processor #'org-cite-basic--complete-key + #'org-cite-basic--complete-style) :cite-styles '((("author" "a") ("caps" "c")) (("noauthor" "na") ("bare" "b")) -- 2.45.2