From 2fb915bb610eec7436e5b2cbdf70153ac6893746 Mon Sep 17 00:00:00 2001 From: Mykhailo Shevchuk Date: Sat, 2 May 2020 20:39:33 +0200 Subject: [PATCH] rename namespace org-roam-bibtex>orb; v0.2 --- README.md | 52 +++--- orb-compat.el | 60 ++++++ ...tex-note-actions.el => orb-note-actions.el | 102 +++++----- org-roam-bibtex.el | 174 +++++++++--------- 4 files changed, 226 insertions(+), 162 deletions(-) create mode 100644 orb-compat.el rename org-roam-bibtex-note-actions.el => orb-note-actions.el (66%) diff --git a/README.md b/README.md index a848057..3ffda1c 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,10 @@ This means that a lot of things may change in the future (e.g. renaming variable 2. If there is a problem with your configuration, most notably variables which do not exist anymore or functions which are not called with the right number of arguments, you will need to check this page to see what has changed. 3. If neither 1. nor 2. resolved your problem, please open an **issue**. (This is what an Alpha version is for!) +##### WARNING! + +- **As of v0.2 `org-roam-bibtex` namespace was renamed into `orb`. Besides, `org-roam-bibtex-mode` is now `orb-minor-mode`. The existing functions and variables bearing the old prefix will be supported for a while but the support will be dropped eventually. All new functions and variables will have the new prefix.** + Installation --------------- @@ -67,12 +71,12 @@ You can get `org-roam-bibtex` up and running by pasting the following sexps in y ```el ;; If you installed via MELPA (use-package org-roam-bibtex - :hook (org-roam-mode . org-roam-bibtex-mode)) + :hook (org-roam-mode . orb-minor-mode)) ;; If you cloned the repository (use-package org-roam-bibtex :load-path "~/projects/org-roam-bibtex/" ;Modify with your own path - :hook (org-roam-mode . org-roam-bibtex-mode)) + :hook (org-roam-mode . orb-minor-mode)) ``` ### Without `use-package` @@ -80,28 +84,28 @@ You can get `org-roam-bibtex` up and running by pasting the following sexps in y ```el ;; If you installed via MELPA (require 'org-roam-bibtex) -(add-hook 'after-init-hook #'org-roam-bibtex-mode) +(add-hook 'after-init-hook #'orb-minor-mode) ;; If you cloned the repository (add-to-list 'load-path "~/projects/org-roam-bibtex/") ;Modify with your own path (require 'org-roam-bibtex) -(add-hook 'after-init-hook #'org-roam-bibtex-mode) +(add-hook 'after-init-hook #'orb-minor-mode) ``` Usage --------------- -You can now access your bibliographical notes in your `org-roam-directory` via `helm-bibtex`/`ivy-bibtex` or by opening `org-ref` links. This is done in the background by modifying the `Edit notes` actions used by these packages to use `org-roam-bibtex-edit-notes` instead of their defaults. +You can now access your bibliographical notes in your `org-roam-directory` via `helm-bibtex`/`ivy-bibtex` or by opening `org-ref` links. This is done in the background by modifying the `Edit notes` actions used by these packages to use `orb-edit-notes` instead of their defaults. -To revert those actions to their defaults, disable `org-roam-bibtex-mode`. +To revert those actions to their defaults, disable `orb-minor-mode`. ### Commands -#### `org-roam-bibtex-find-non-ref-file` +#### `orb-find-non-ref-file` Similar to `org-roam-find-file`, but it excludes your bibliographical notes from the completion-candidates. This is useful if you have a lot of them and do not want to clutter up your other notes. -#### `org-roam-bibtex-insert-non-ref` +#### `orb-insert-non-ref` Similar to `org-roam-insert`, but it excludes your bibliographical notes from the completion-list. @@ -110,13 +114,13 @@ Configuration ### Variables -#### `org-roam-bibtex-templates` +#### `orb-templates` This variable specifies the templates to use when creating a new bibliographical note. It builds on the syntax of `org-roam-capture-templates` by allowing you to expand predefined variables to the value of a BibTeX fields. -See `org-roam-bibtex-edit-notes` and [`org-roam-bibtex-preformat-keywords`](#org-roam-bibtex-preformat-keywords) for details. (You can access the docstrings of any loaded function/variable from within Emacs with `C-h f` for functions/commands, and `C-h v` for variables.) +See `orb-edit-notes` and [`orb-preformat-keywords`](#orb-preformat-keywords) for details. (You can access the docstrings of any loaded function/variable from within Emacs with `C-h f` for functions/commands, and `C-h v` for variables.) -Here’s the default value of `org-roam-bibtex-templates`: +Here’s the default value of `orb-templates`: ```el (("r" "ref" plain (function org-roam-capture--get-point) "" :file-name "${citekey}" @@ -126,27 +130,27 @@ Here’s the default value of `org-roam-bibtex-templates`: You can modify it with `setq`. For instance, if you want to add the cite-key in the title of the notes, you can modify the code like this (pay attention to the line with `:head`): ```el -(setq org-roam-bibtex-templates +(setq orb-templates '(("r" "ref" plain (function org-roam-capture--get-point) "" :file-name "${citekey}" :head "#+TITLE: ${=key=}: ${title}\n#+ROAM_KEY: ${ref}\n" ; <-- :unnarrowed t))) ``` -If you have more than one template in `org-roam-bibtex-templates`, you will be prompted for the key of the template you want to use (`r` in the example above). If you only have one template, it will use this one without prompting you. +If you have more than one template in `orb-templates`, you will be prompted for the key of the template you want to use (`r` in the example above). If you only have one template, it will use this one without prompting you. See [Modifying templates](#modifying-templates) for more info. -#### `org-roam-bibtex-preformat-keywords` +#### `orb-preformat-keywords` -The template prompt wildcards for preformatting. Only relevant when `org-roam-bibtex-preformat-templates` is set to `t` (default). This can be a string, a list of strings or a cons-cell alist, where each element is `(STRING . STRING)`. +The template prompt wildcards for preformatting. Only relevant when `orb-preformat-templates` is set to `t` (default). This can be a string, a list of strings or a cons-cell alist, where each element is `(STRING . STRING)`. -Use only alphanumerical characters, dash and underscore. See `org-roam-bibtex-edit-notes` for implementation details. +Use only alphanumerical characters, dash and underscore. See `orb-edit-notes` for implementation details. 1. If the value is a string, a single keyword, it is treated as a BibTeX field name, such as `=key=`. In the following example all the prompts with the `=key=` keyword will be preformatted, as well as the corresponding match group `%\1`. ```el -(setq org-roam-bibtex-preformat-keywords "=key=") +(setq orb-preformat-keywords "=key=") (setq org-roam-capture-templates ’(("r" "reference" plain (function org-roam-capture--get-point) "#+ROAM_KEY: %^{=key=}%? fullcite: %\1" @@ -158,7 +162,7 @@ Use only alphanumerical characters, dash and underscore. See `org-roam-bibtex-ed 2. If the value is a list of strings they are also treated as BibTeX field names. The respective prompts will be preformatted. ```el -(setq org-roam-bibtex-preformat-keywords ’("=key=" "title")) +(setq orb-preformat-keywords ’("=key=" "title")) (setq org-roam-capture-templates ’(("r" "reference" plain (function org-roam-capture--get-point) "#+ROAM_KEY: %^{=key=}%? fullcite: %\1" @@ -170,7 +174,7 @@ Use only alphanumerical characters, dash and underscore. See `org-roam-bibtex-ed 3. If the value is a list of cons cells, then the car of the cons cell is treated as a prompt keyword and the cdr as a BibTeX field-name, and the latter will be used to retrieve the relevant value from the BibTeX entry. If cdr is omitted, then the car is treated as the field-name. ```el -(setq org-roam-bibtex-preformat-keywords +(setq orb-preformat-keywords '(("citekey" . "=key=") ("type" . "=type=") "title")) @@ -214,17 +218,17 @@ fullcite:%\1 You can also use a function to generate the the template if you need something more advanced. -#### `%(org-roam-bibtex-process-file-field \"${=key=}\")` +#### `%(orb-process-file-field \"${=key=}\")` -The convenience-function `org-roam-bibtex-process-file-field` has been added to find documents associated with the BibTeX entry. It is intended to be used inside your template via a `%`-escapes form for sexp (`%(sexp)`). See `org-capture-templates` for details. +The convenience-function `orb-process-file-field` has been added to find documents associated with the BibTeX entry. It is intended to be used inside your template via a `%`-escapes form for sexp (`%(sexp)`). See `org-capture-templates` for details. Below shows how this can be used to integrate with [org-noter](https://github.com/weirdNox/org-noter) or [interleave](https://github.com/rudolfochrist/interleave): ```el -(setq org-roam-bibtex-preformat-keywords +(setq orb-preformat-keywords '("=key=" "title" "url" "file" "author-or-editor" "keywords")) -(setq org-roam-bibtex-templates +(setq orb-templates '(("r" "ref" plain (function org-roam-capture--get-point) "" :file-name "${slug}" @@ -238,7 +242,7 @@ Below shows how this can be used to integrate with [org-noter](https://github.co :Custom_ID: ${=key=} :URL: ${url} :AUTHOR: ${author-or-editor} -:NOTER_DOCUMENT: %(org-roam-bibtex-process-file-field \"${=key=}\") +:NOTER_DOCUMENT: %(orb-process-file-field \"${=key=}\") :NOTER_PAGE: :END:"))) ``` diff --git a/orb-compat.el b/orb-compat.el new file mode 100644 index 0000000..f682a04 --- /dev/null +++ b/orb-compat.el @@ -0,0 +1,60 @@ +;;; org-roam-bibtex-compat.el --- Connector between Org-roam, BibTeX-completion, and Org-ref -*- coding: utf-8; lexical-binding: t -*- + +;; Copyright © 2020 Mykhailo Shevchuk +;; Copyright © 2020 Leo Vivier + +;; Author: Leo Vivier +;; Mykhailo Shevchuk +;; URL: https://github.com/zaeph/org-roam-bibtex +;; Keywords: org-mode, roam, convenience, bibtex, helm-bibtex, ivy-bibtex, org-ref +;; Version: 0.2 + +;; This file is NOT part of GNU Emacs. + +;; This program is free software; you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation; either version 3, or (at your option) +;; any later version. +;; +;; This program is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. +;; +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs; see the file COPYING. If not, write to the +;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +;; Boston, MA 02110-1301, USA. + +;;; Commentary: +;; +;; Obsolete definitions live here. For a while. + +;;; Code: + +;; * org-roam-bibtex.el +(define-obsolete-variable-alias "org-roam-bibtex-preformat-templates" "orb-preformat-templates" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-templates" "orb-templates" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-include-citekey-in-titles" "orb-include-citekey-in-titles" "0.2" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-preformat-keywords" "orb-preformat-keywords" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-citekey-format" "orb-citekey-format" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-persp-project" "orb-persp-project" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-switch-persp" "orb-switch-persp" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-mode-map" "orb-mode-map" "0.2") + +(define-obsolete-function-alias "org-roam-bibtex-notes-fn" "orb-notes-fn" "0.2") +(define-obsolete-function-alias "org-roam-bibtex-edit-notes-ad" "orb-edit-notes-ad" "0.2") +(define-obsolete-function-alias "org-roam-bibtex-process-file-field" "orb-process-file-field" "0.2") +(define-obsolete-function-alias "org-roam-bibtex-mode" "orb-mode" "0.2") +(define-obsolete-function-alias "org-roam-bibtex-edit-notes" "orb-edit-notes" "0.2") +(define-obsolete-function-alias "org-roam-bibtex-find-non-ref-file" "orb-find-non-ref-file" "0.2") +(define-obsolete-function-alias "org-roam-bibtex-insert-non-ref" "orb-insert-non-ref" "0.2") + +;; * org-roam-bibtex-note-actions.el + +(define-obsolete-variable-alias "org-roam-bibtex-note-actions-frontend" "orb-note-actions-frontend" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-note-actions-extra" "orb-note-actions-extra" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-note-actions-user" "orb-note-actions-user" "0.2") +(define-obsolete-variable-alias "org-roam-bibtex-note-actions-default" "orb-note-actions-default" "0.2") + +(define-obsolete-function-alias "org-roam-bibtex-note-actions" "orb-note-actions" "0.2") diff --git a/org-roam-bibtex-note-actions.el b/orb-note-actions.el similarity index 66% rename from org-roam-bibtex-note-actions.el rename to orb-note-actions.el index 9399d21..84fc1d9 100644 --- a/org-roam-bibtex-note-actions.el +++ b/orb-note-actions.el @@ -1,13 +1,13 @@ -;;; org-roam-bibtex-note-actions.el --- Connector between Org-roam, BibTeX-completion, and Org-ref -*- coding: utf-8; lexical-binding: t -*- +;;; orb-note-actions.el --- Connector between Org-roam, BibTeX-completion, and Org-ref -*- coding: utf-8; lexical-binding: t -*- ;; Copyright © 2020 Mykhailo Shevchuk -;; Copyright © 2020 Leo Vivier +;; Copyright © 2020 Leo Vivier -;; Author: Leo Vivier +;; Author: Leo Vivier ;; Mykhailo Shevchuk ;; URL: https://github.com/zaeph/org-roam-bibtex ;; Keywords: org-mode, roam, convenience, bibtex, helm-bibtex, ivy-bibtex, org-ref -;; Version: 0.1 +;; Version: 0.2 ;; This file is NOT part of GNU Emacs. @@ -49,15 +49,15 @@ ;; TODO: get rid of after we have our own format function (require 'org-ref) -(declare-function ido-completing-read "ido" (prompt choices &optional predicate require-match initial-input hist def inherit-input-method)) +(declare-function ido-completing-read "ido") (declare-function helm "helm") (declare-function ivy-read "ivy") (declare-function defhydra "hydra") ;; * Customize definitions -(defcustom org-roam-bibtex-note-actions-frontend 'default - "Interface frontend for `org-roam-bibtex-note actions'." +(defcustom orb-note-actions-frontend 'default + "Interface frontend for `orb-note-actions'." :type '(radio (const :tag "Default" default) (const :tag "Ido" ido) @@ -67,21 +67,21 @@ (function :tag "Custom function")) :group 'org-roam-bibtex) -(defcustom org-roam-bibtex-note-actions-extra +(defcustom orb-note-actions-extra '(("Show record in the bibtex file" . bibtex-completion-show-entry)) - "Extra actions for `org-roam-bibtex-note-actions'. + "Extra actions for `orb-note-actions'. Each action is a cons cell DESCRIPTION . FUNCTION." :type '(alist - :tag "Extra actions for `org-roam-bibtex-note-actions'" + :tag "Extra actions for `orb-note-actions'" :key-type (string :tag "Prompt") :value-type (symbol :tag "Function name (unquoted)")) :group 'org-roam-bibtex) -(defcustom org-roam-bibtex-note-actions-user nil - "User actions for `org-roam-bibtex-note-actions'. +(defcustom orb-note-actions-user nil + "User actions for `orb-note-actions'. Each action is a cons cell DESCRIPTION . FUNCTION." :type '(alist - :tag "User actions for `org-roam-bibtex-note-actions'" + :tag "User actions for `orb-note-actions'" :key-type (string :tag "Prompt") :value-type (symbol :tag "Function name (unquoted)")) :group 'org-roam-bibtex) @@ -89,25 +89,25 @@ Each action is a cons cell DESCRIPTION . FUNCTION." ;; * Helper functions -(defvar org-roam-bibtex-note-actions-default +(defvar orb-note-actions-default '(("Open PDF file(s)" . bibtex-completion-open-pdf) ("Add PDF to library" . bibtex-completion-add-pdf-to-library) ("Open URL or DOI in browser" . bibtex-completion-open-url-or-doi)) - "Default actions for `org-roam-bibtex-note-actions'. + "Default actions for `orb-note-actions'. Each action is a cons cell DESCRIPTION . FUNCTION.") -(defmacro org-roam-bibtex-note-actions--frontend! (frontend &rest body) +(defmacro orb-note-actions--frontend! (frontend &rest body) "Return a function definition for FRONTEND. -Function name takes a form of org-roam-bibtex-note-action--FRONTEND. +Function name takes a form of orb-note-actions--FRONTEND. A simple docstring is constructed and BODY is injected into a `let' form, which has two variables bound, NAME and CANDIDATES. NAME is a string formatted with `org-ref-format-entry' and CANDIDATES is a cons cell alist -constructed from `org-roam-bibtex-note-actions-default', -`org-roam-bibtex-note-actions-extra', and `org-roam-bibtex-note-actions-user." +constructed from `orb-note-actions-default', +`orb-note-actions-extra', and `orb-note-actions-user." (declare (indent 1) (debug (symbolp &rest form))) (let* ((frontend-name (symbol-name (eval frontend))) - (fun-name (intern (concat "org-roam-bibtex-note-actions--" frontend-name)))) + (fun-name (intern (concat "orb-note-actions--" frontend-name)))) `(defun ,fun-name (citekey) ,(format "Provide note actions using %s interface. CITEKEY is the citekey." (capitalize frontend-name)) @@ -118,26 +118,26 @@ CITEKEY is the citekey." (capitalize frontend-name)) ;; (window-body-width))) (candidates ,(unless (string= frontend-name "hydra") - '(append org-roam-bibtex-note-actions-default - org-roam-bibtex-note-actions-extra - org-roam-bibtex-note-actions-user)))) + '(append orb-note-actions-default + orb-note-actions-extra + orb-note-actions-user)))) ,@body)))) -(org-roam-bibtex-note-actions--frontend! 'default +(orb-note-actions--frontend! 'default (let ((f (cdr (assoc (completing-read name candidates) candidates)))) (funcall f (list citekey)))) -(org-roam-bibtex-note-actions--frontend! 'ido +(orb-note-actions--frontend! 'ido (let* ((c (cl-map 'list 'car candidates)) (f (cdr (assoc (ido-completing-read name c) candidates)))) (funcall f (list citekey)))) -(declare-function org-roam-bibtex-note-actions-hydra/body "org-roam-bibtex-note-actions" nil t) -(org-roam-bibtex-note-actions--frontend! 'hydra +(declare-function orb-note-actions-hydra/body "orb-note-actions" nil t) +(orb-note-actions--frontend! 'hydra (let ((n ?a) actions) (dolist (type (list "Default" "Extra" "User")) - (let ((actions-var (intern (concat "org-roam-bibtex-note-actions-" (downcase type))))) + (let ((actions-var (intern (concat "orb-note-actions-" (downcase type))))) (dolist (action (symbol-value actions-var)) (cl-pushnew `(,(format "%c" n) (,(cdr action) 'key) ,(car action) :column ,(concat type " actions")) @@ -145,23 +145,23 @@ CITEKEY is the citekey." (capitalize frontend-name)) (setq n (1+ n))))) ; TODO: figure out a way to supply mnemonic keys (setq actions (nreverse actions)) (eval - `(defhydra org-roam-bibtex-note-actions-hydra (:color blue :hint nil) + `(defhydra orb-note-actions-hydra (:color blue :hint nil) ,(format "^\n %s \n\n^" (s-word-wrap (- (window-body-width) 2) name)) ,@actions))) - (org-roam-bibtex-note-actions-hydra/body)) + (orb-note-actions-hydra/body)) -(org-roam-bibtex-note-actions--frontend! 'ivy +(orb-note-actions--frontend! 'ivy (if (fboundp 'ivy-read) (ivy-read name candidates :require-match t - :caller #'org-roam-bibtex-note-actions + :caller #'orb-note-actions :action (lambda (c) (funcall (cdr c) (list citekey)))) (display-warning :warning "You must have Ivy installed to use it! Falling back to default.") - (org-roam-bibtex-note-actions--default citekey))) + (orb-note-actions--default citekey))) -(org-roam-bibtex-note-actions--frontend! 'helm +(orb-note-actions--frontend! 'helm (if (fboundp 'helm) (helm :sources `(((name . ,name) @@ -169,52 +169,52 @@ CITEKEY is the citekey." (capitalize frontend-name)) (action . (lambda (f) (funcall f (list ,citekey))))))) (display-warning :warning "You must have Helm installed to use it! Falling back to default.") - (org-roam-bibtex-note-actions--default citekey))) + (orb-note-actions--default citekey))) -(defun org-roam-bibtex-note-actions--run (frontend citekey ) +(defun orb-note-actions--run (frontend citekey ) "Run note actions on CITEKEY with FRONTEND." - (let ((fun (intern (concat "org-roam-bibtex-note-actions--" (symbol-name frontend))))) + (let ((fun (intern (concat "orb-note-actions--" (symbol-name frontend))))) (funcall fun citekey))) ;; * Main functions ;;;###autoload -(defun org-roam-bibtex-note-actions () +(defun orb-note-actions () "Run an interactive prompt to offer note-related actions. The prompt frontend can be set in -`org-roam-bibtex-note-actions-frontend'. In addition to default +`orb-note-actions-frontend'. In addition to default actions, which are not supposed to be modified, there is a number -of prefined extra actions `org-roam-bibtex-note-actions-extra' +of prefined extra actions `orb-note-actions-extra' that can be customized. Additionally, user actions can be set in -`org-roam-bibtex-note-actions-user'." +`orb-note-actions-user'." (interactive) (let ((non-default-frontends (list 'hydra 'ido 'ivy 'helm)) (citekey (cdr (assoc "ROAM_KEY" (org-roam--extract-global-props '("ROAM_KEY")))))) ;; remove format from citekey - (when org-roam-bibtex-citekey-format - (setq citekey (org-roam-bibtex--unformat-citekey citekey))) + (when orb-citekey-format + (setq citekey (orb--unformat-citekey citekey))) (if citekey (cond ((member - org-roam-bibtex-note-actions-frontend + orb-note-actions-frontend non-default-frontends) - (org-roam-bibtex-note-actions--run - org-roam-bibtex-note-actions-frontend + (orb-note-actions--run + orb-note-actions-frontend citekey)) ((functionp - org-roam-bibtex-note-actions-frontend) + orb-note-actions-frontend) (funcall - org-roam-bibtex-note-actions-frontend + orb-note-actions-frontend citekey)) (t - (org-roam-bibtex-note-actions--run + (orb-note-actions--run 'default citekey))) (message "#+ROAM_KEY is not found in this buffer.")))) -(provide 'org-roam-bibtex-note-actions) -;;; org-roam-bibtex-note-actions.el ends here +(provide 'orb-note-actions) +;;; orb-note-actions.el ends here ;; Local Variables: ;; fill-column: 70 ;; End: diff --git a/org-roam-bibtex.el b/org-roam-bibtex.el index 8d49a05..2b46498 100644 --- a/org-roam-bibtex.el +++ b/org-roam-bibtex.el @@ -9,7 +9,7 @@ ;; Jethro Kuan ;; URL: https://github.com/zaeph/org-roam-bibtex ;; Keywords: org-mode, roam, convenience, bibtex, helm-bibtex, ivy-bibtex, org-ref -;; Version: 0.1 +;; Version: 0.2 ;; Package-Requires: ((emacs "26.1") (f "0.20.0") (s "1.12.0") (org "9.3") (org-roam "1.0.0") (bibtex-completion "2.0.0")) ;; This file is NOT part of GNU Emacs. @@ -39,15 +39,15 @@ ;; ;; To use it: ;; -;; call interactively `org-roam-bibtex-mode' or -;; call (org-roam-bibtex-mode +1) from Lisp. +;; call interactively `orb-minor-mode' or +;; call (orb-minor-mode +1) from Lisp. ;; -;; After enabling `org-roam-bibtex-mode', the function -;; `org-roam-bibtex-edit-notes' will shadow +;; After enabling `orb-minor-mode', the function +;; `orb-edit-notes' will shadow ;; `bibtex-completion-edit-notes' in Helm-bibtex, Ivy-bibtex. ;; -;; Additionally, `org-roam-bibtex-notes-fn', which is a simple wrapper -;; around `org-roam-bibtex-edit-notes', is installed as Org-ref's +;; Additionally, `orb-notes-fn', which is a simple wrapper +;; around `orb-edit-notes', is installed as Org-ref's ;; `org-ref-notes-function'. See Org-ref's documentation for how to ;; setup many-files notes. Take a notice that because of its size, ;; Org-ref is not a dependency of Org-roam-bibtex, so it will not be @@ -56,11 +56,11 @@ ;; ;; As a user option, `org-roam-capture-templates' can be dynamically ;; preformatted with bibtex field values. See -;; `org-roam-bibtex-preformat-keywords' for more details. +;; `orb-preformat-keywords' for more details. ;; ;; Optionally, automatic switching to the perspective (Persp-mode) ;; with the notes project (Projectile) is possible. See -;; `org-roam-bibtex-edit-notes' for more details. +;; `orb-edit-notes' for more details. ;; ;;; Code: @@ -68,7 +68,7 @@ ;; We do not require `org-ref' here, because it is too expensive to be ;; loaded unconditionally and the user might not even need -;; it. Instead, we require it in the body of `org-roam-bibtex-notes-fn'. +;; it. Instead, we require it in the body of `orb-notes-fn'. (require 'org-roam) (require 'bibtex-completion) (eval-when-compile @@ -90,17 +90,17 @@ :group 'org-roam :group 'org-ref :group 'bibtex-completion - :prefix "org-roam-bibtex-") + :prefix "orb-") -(defcustom org-roam-bibtex-preformat-templates t +(defcustom orb-preformat-templates t "Non-nil to enable template preformatting. -See `org-roam-bibtex-edit-notes' for details." +See `orb-edit-notes' for details." :type '(choice (const :tag "Yes" t) (const :tag "No" nil)) :group 'org-roam-bibtex) -(defcustom org-roam-bibtex-templates +(defcustom orb-templates '(("r" "ref" plain (function org-roam-capture--get-point) "" @@ -108,33 +108,33 @@ See `org-roam-bibtex-edit-notes' for details." :head "#+TITLE: ${title}\n#+ROAM_KEY: ${ref}\n" :unnarrowed t)) "Template to use when creating a new note. -See `org-roam-bibtex-edit-notes' for details." +See `orb-edit-notes' for details." :type '(list) :group 'org-roam-bibtex) -(defcustom org-roam-bibtex-include-citekey-in-titles nil +(defcustom orb-include-citekey-in-titles nil "Non-nil to include the citekey in titles. -See `org-roam-bibtex-edit-notes' for details." +See `orb-edit-notes' for details." :type '(choice (const :tag "Yes" t) (const :tag "No" nil)) :group 'org-roam-bibtex) -(defcustom org-roam-bibtex-preformat-keywords '(("citekey" . "=key=")) +(defcustom orb-preformat-keywords '(("citekey" . "=key=")) "The template prompt wildcards for preformatting. -Only relevant when `org-roam-bibtex-preformat-templates' is set +Only relevant when `orb-preformat-templates' is set to t (default). This can be a string, a list of strings or a cons-cell alist, where each element is (STRING . STRING). Use only alphanumerical characters, dash and underscore. See -`org-roam-bibtex-edit-notes' for implementation details. +`orb-edit-notes' for implementation details. 1. If the value is a string, a single keyword, it is treated as a BibTeX field-name, such as =key=. In the following example all the prompts with the '=key=' keyword will be preformatted, as well as the corresponding match group %\\1. -\(setq org-roam-bibtex-preformat-keywords \"=key=\") +\(setq orb-preformat-keywords \"=key=\") \(setq org-roam-capture-templates '((\"r\" \"reference\" plain (function org-roam-capture--get-point) \"#+ROAM_KEY: %^{=key=}%? fullcite: %\\1\" @@ -145,7 +145,7 @@ well as the corresponding match group %\\1. 2. If the value is a list of strings they are also treated as BibTeX field-names. The respective prompts will be preformatted. -\(setq org-roam-bibtex-preformat-keywords '(\"=key=\" \"title\")) +\(setq orb-preformat-keywords '(\"=key=\" \"title\")) \(setq org-roam-capture-templates '((\"r\" \"reference\" plain (function org-roam-capture--get-point) \"#+ROAM_KEY: %^{=key=}%? fullcite: %\\1\" @@ -159,7 +159,7 @@ name, and the latter will be used to retrieve the relevant value from the BibTeX entry. If cdr is omitted, then the car is treated as the field name. -\(setq org-roam-bibtex-preformat-keywords +\(setq orb-preformat-keywords '((\"citekey\" . \"=key=\") (\"type\" . \"=type=\") \"title\")) @@ -183,35 +183,35 @@ about BibTeX field names." :value-type (string :tag "Field"))) :group 'org-roam-bibtex) -(defcustom org-roam-bibtex-citekey-format "cite:%s" +(defcustom orb-citekey-format "cite:%s" "Format string for the citekey. The citekey obtained from Helm-bibtex/Ivy-bibtex/Org-ref will be formatted as specified here." :type 'string :group 'org-roam-bibtex) -(defcustom org-roam-bibtex-persp-project `("notes" . ,org-roam-directory) +(defcustom orb-persp-project `("notes" . ,org-roam-directory) "Perspective name and path to the project with bibliography notes. A cons cell (PERSP-NAME . PROJECT-PATH). Only relevant when -`org-roam-bibtex-switch-persp' is set to t. +`orb-switch-persp' is set to t. Requires command `persp-mode' and command `projectile-mode'. PERSP-NAME should be a valid Perspective name, PROJECT-PATH should be an open Projectile project. -See `org-roam-bibtex-edit-notes' for details" +See `orb-edit-notes' for details" :type '(cons (string :tag "Perspective name") (directory :tag "Projectile directory")) :group 'org-roam-bibtex) -(defcustom org-roam-bibtex-switch-persp nil +(defcustom orb-switch-persp nil "Non-nil to enable switching to the notes perspective. Set the name of the perspective and the path to the notes project -in `org-roam-bibtex-persp-project' for this to take effect. +in `orb-persp-project' for this to take effect. Requires command `persp-mode' and command `projectile-mode'. -See `org-roam-bibtex-edit-notes' for details." +See `orb-edit-notes' for details." :type '(choice (const :tag "Yes" t) (const :tag "No" nil)) @@ -221,27 +221,27 @@ See `org-roam-bibtex-edit-notes' for details." ;; * Interface functions ;;;###autoload -(defun org-roam-bibtex-notes-fn (citekey) +(defun orb-notes-fn (citekey) "Open an Org-roam note associated with the CITEKEY or create a new one. Set `org-ref-notes-function' to this function if your bibliography notes are managed by Org-roam and you want some extra integration between the two packages. -This is a wrapper function around `org-roam-bibtex-edit-notes' +This is a wrapper function around `orb-edit-notes' intended for use with Org-ref." (when (require 'org-ref nil t) (let ((bibtex-completion-bibliography (org-ref-find-bibliography))) - (org-roam-bibtex-edit-notes citekey)))) + (orb-edit-notes citekey)))) ;;;###autoload -(defun org-roam-bibtex-edit-notes-ad (keys) +(defun orb-edit-notes-ad (keys) "Open an Org-roam note associated with the first key from KEYS. This function replaces `bibtex-completion-edit-notes'. Only the first key from KEYS will actually be used." - (org-roam-bibtex-edit-notes (car keys))) + (orb-edit-notes (car keys))) ;;;###autoload -(defun org-roam-bibtex-process-file-field (citekey) +(defun orb-process-file-field (citekey) "Process the 'file' BibTeX field and resolve if there are multiples. Search the disk for the document associated with this BibTeX entry. The disk matching is based on looking in the @@ -260,11 +260,11 @@ to enter" ;; * Helper functions -(defun org-roam-bibtex--switch-perspective () - "Helper function for `org-roam-bibtex-edit-notes'." +(defun orb--switch-perspective () + "Helper function for `orb-edit-notes'." (when (and (require 'projectile nil t) (require 'persp-mode nil t)) - (let ((notes-project (cdr org-roam-bibtex-persp-project)) + (let ((notes-project (cdr orb-persp-project)) (projects (projectile-relevant-open-projects)) openp) (dolist (project projects openp) @@ -272,17 +272,17 @@ to enter" (when openp (let ((p-names (cdr (persp-names)))) (dolist (p-name p-names) - (when (s-equals? p-name (car org-roam-bibtex-persp-project)) + (when (s-equals? p-name (car orb-persp-project)) (persp-switch p-name)))))))) -(defun org-roam-bibtex--preformat-template (template entry) - "Helper function for `org-roam-bibtex--preformat-templates'. +(defun orb--preformat-template (template entry) + "Helper function for `orb--preformat-templates'. TEMPLATE is an element of `org-roam-capture-templates' and ENTRY is a BibTeX entry as returned by `bibtex-completion-get-entry'." ;; Handle org-roam-capture part - (let* ((kwds (if (listp org-roam-bibtex-preformat-keywords) ; normalize org-roam-bibtex-preformat-keywords - org-roam-bibtex-preformat-keywords - (list org-roam-bibtex-preformat-keywords))) + (let* ((kwds (if (listp orb-preformat-keywords) ; normalize orb-preformat-keywords + orb-preformat-keywords + (list orb-preformat-keywords))) ;; Org-capture templates: ;; handle different types of org-capture-templates: string, file and function; ;; this is a stripped down version of `org-capture-get-template' @@ -341,7 +341,7 @@ is a BibTeX entry as returned by `bibtex-completion-get-entry'." (setf (nth 4 template) tp)) template)) -(defun org-roam-bibtex--get-non-ref-path-completions (&optional candidates) +(defun orb--get-non-ref-path-completions (&optional candidates) "Return a list of cons for titles of non-ref notes to absolute path. CANDIDATES is a an alist of candidates to consider. Defaults to `org-roam--get-title-path-completions' otherwise." @@ -356,63 +356,63 @@ CANDIDATES is a an alist of candidates to consider. Defaults to (setq completions (nconc completions (list candidate)))))))) -(defun org-roam-bibtex--unformat-citekey (citekey) +(defun orb--unformat-citekey (citekey) "Remove format from CITEKEY. -Format is `org-roam-bibtex-citekey-format'." - (string-match "\\(.*\\)%s\\(.*\\)" org-roam-bibtex-citekey-format) +Format is `orb-citekey-format'." + (string-match "\\(.*\\)%s\\(.*\\)" orb-citekey-format) (let ((beg (match-end 1)) (end (+ (length citekey) (- (match-beginning 2) - (length org-roam-bibtex-citekey-format))))) + (length orb-citekey-format))))) (substring citekey beg end))) ;; * Main functions -(defvar org-roam-bibtex-mode-map +(defvar orb-minor-mode-map (make-sparse-keymap) - "Keymap for function `org-roam-bibtex-mode'.") + "Keymap for function `orb-minor-mode'.") -(defun org-roam-bibtex-find-note-file (citekey) +(defun orb-find-note-file (citekey) "Find note file associated from BibTeX’s CITEKEY. Returns the path to the note file, or nil if it doesn’t exist." - (let* ((citekey-formatted (format (or org-roam-bibtex-citekey-format "%s") citekey)) + (let* ((citekey-formatted (format (or orb-citekey-format "%s") citekey)) (completions (org-roam--get-ref-path-completions))) (cdr (assoc citekey-formatted completions)))) ;;;###autoload -(define-minor-mode org-roam-bibtex-mode - "Sets `org-roam-bibtex-edit-notes' as a function for editing bibliography notes. +(define-minor-mode orb-minor-mode + "Sets `orb-edit-notes' as a function for editing bibliography notes. Affects Org-ref and Helm-bibtex/Ivy-bibtex. -When called interactively, toggle `org-roam-bibtex-mode'. with prefix -ARG, enable `org-roam-bibtex-mode' if ARG is positive, otherwise disable +When called interactively, toggle `orb-minor-mode'. with prefix +ARG, enable `orb-minor-mode' if ARG is positive, otherwise disable it. When called from Lisp, enable `org-roam-mode' if ARG is omitted, nil, or positive. If ARG is `toggle', toggle `org-roam-mode'. Otherwise, behave as if called interactively." :lighter " orb" - :keymap org-roam-bibtex-mode-map + :keymap orb-minor-mode-map :group 'org-roam-bibtex - :require 'org-roam-bibtex + :require 'orb :global t - (cond (org-roam-bibtex-mode - (setq org-ref-notes-function 'org-roam-bibtex-notes-fn) + (cond (orb-minor-mode + (setq org-ref-notes-function 'orb-notes-fn) (add-to-list 'bibtex-completion-find-note-functions - #'org-roam-bibtex-find-note-file) + #'orb-find-note-file) (advice-add 'bibtex-completion-edit-notes - :override #'org-roam-bibtex-edit-notes-ad)) + :override #'orb-edit-notes-ad)) (t (setq org-ref-notes-function 'org-ref-notes-function-one-file) (setq bibtex-completion-find-note-functions - (delq #'org-roam-bibtex-find-note-file + (delq #'orb-find-note-file bibtex-completion-find-note-functions)) (advice-remove 'bibtex-completion-edit-notes - #'org-roam-bibtex-edit-notes-ad)))) + #'orb-edit-notes-ad)))) ;;;###autoload -(defun org-roam-bibtex-edit-notes (citekey) +(defun orb-edit-notes (citekey) "Open an Org-roam note associated with the CITEKEY or create a new one. This function allows to use Org-roam as a backend for managing @@ -432,22 +432,22 @@ The prompt presented by `org-roam-find-file' will thus be pre-populated with the record title. 3. The template used to create the note is stored in -`org-roam-bibtex-templates'. If the variable is not defined, +`orb-templates'. If the variable is not defined, revert to using `org-roam-capture-templates'. In the former case, a new file will be created and filled according to the template, possibly preformatted (see below) without additional user interaction. In the latter case, an interactive `org-capture' process will be run. -4. Optionally, when `org-roam-bibtex-preformat-templates' is -non-nil, any prompt wildcards in `org-roam-bibtex-templates' or +4. Optionally, when `orb-preformat-templates' is +non-nil, any prompt wildcards in `orb-templates' or `org-roam-capture-templates' associated with the bibtex record -fields as specified in `org-roam-bibtex-preformat-templates' will +fields as specified in `orb-preformat-templates' will be preformatted. Both `org-capture-templates' (%^{}) and `org-roam-capture-templates' (`s-format', ${}) prompt syntaxes are supported. -See `org-roam-bibtex-preformat-keywords' for more details on how +See `orb-preformat-keywords' for more details on how to properly specify prompts for replacement. Please pay attention when using this feature that by setting @@ -459,30 +459,30 @@ wildcards will be replace with the BibTeX field value. 5. Optionally, if you are using Projectile and Persp-mode and have a dedicated workspace to work with your Org-roam collection, you may want to set the perspective name and project path in -`org-roam-bibtex-persp-project' and -`org-roam-bibtex-switch-persp' to t. In this case, the +`orb-persp-project' and +`orb-switch-persp' to t. In this case, the perspective will be switched to the Org-roam notes project before calling any Org-roam functions." (unless org-roam-mode (org-roam-mode +1)) - (let* ((citekey-formatted (format (or org-roam-bibtex-citekey-format "%s") citekey)) + (let* ((citekey-formatted (format (or orb-citekey-format "%s") citekey)) (note-info (list (cons 'ref citekey-formatted)))) ;; Optionally switch to the notes perspective - (when org-roam-bibtex-switch-persp - (org-roam-bibtex--switch-perspective)) + (when orb-switch-persp + (orb--switch-perspective)) ;; Find org-roam reference with the CITEKEY (unless (ignore-errors (org-roam-find-ref note-info)) ;; Check if the requested entry actually exists and fail gracefully (if-let* ((entry (bibtex-completion-get-entry citekey)) ;; Depending on the templates used, run org-roam--capture or call org-roam-find-file - (templates (or org-roam-bibtex-templates + (templates (or orb-templates org-roam-capture-templates (and (display-warning :warning "Could not find the requested templates.") nil))) (org-roam-capture-templates ;; Optionally preformat keywords (or - (when org-roam-bibtex-preformat-templates + (when orb-preformat-templates (let* ((tmpls (copy-tree templates)) result) ;; HACK: Currently, there is no easy way to inject ourselves into @@ -490,13 +490,13 @@ calling any Org-roam functions." ;; all the templates beforehand, although only one will be used eventually. ;; This is a waste of resources and may be slow with many templates. (dolist (tmpl tmpls result) - (cl-pushnew (org-roam-bibtex--preformat-template tmpl entry) result)))) + (cl-pushnew (orb--preformat-template tmpl entry) result)))) templates)) (title (or (bibtex-completion-apa-get-value "title" entry) "Title not found for this entry (Check your BibTeX file)"))) ;; Check if a custom template has been set - (if org-roam-bibtex-templates + (if orb-templates (let ((org-roam-capture--context 'ref) (org-roam-capture--info (list (cons 'title title) (cons 'ref citekey-formatted) @@ -507,23 +507,23 @@ calling any Org-roam functions." (message "Something went wrong. Check the *Warnings* buffer."))))) ;;;###autoload -(defun org-roam-bibtex-find-non-ref-file (&optional initial-prompt) +(defun orb-find-non-ref-file (&optional initial-prompt) "Find and open an Org-roam, non-ref file. INITIAL-PROMPT is the initial title prompt. See `org-roam-find-files' and -`org-roam-bibtex--get-non-ref-path-completions' for details." +`orb--get-non-ref-path-completions' for details." (interactive) (org-roam-find-file initial-prompt - #'org-roam-bibtex--get-non-ref-path-completions)) + #'orb--get-non-ref-path-completions)) ;;;###autoload -(defun org-roam-bibtex-insert-non-ref (prefix) +(defun orb-insert-non-ref (prefix) "Find a non-ref Org-roam file, and insert a relative org link to it at point. If PREFIX, downcase the title before insertion. See `org-roam-insert' and -`org-roam-bibtex--get-non-ref-path-completions' for details." +`orb--get-non-ref-path-completions' for details." (interactive "P") - (org-roam-insert prefix #'org-roam-bibtex--get-non-ref-path-completions)) + (org-roam-insert prefix #'orb--get-non-ref-path-completions)) (provide 'org-roam-bibtex) ;;; org-roam-bibtex.el ends here