+# -*- org-edit-src-content-indentation: 0; -*-
#+TITLE: Org-ref - The best reference handling for org-mode
#+AUTHOR: John Kitchin
#+DATE: April 29, 2014
** Header
#+BEGIN_SRC emacs-lisp :tangle org-ref.el
-;;; org-ref.el --- setup bibliography, cite, ref and label org-mode links.
+;;; org-ref.el --- cite and cross-reference in org-mode
;; Copyright(C) 2014 John Kitchin
;; Author: John Kitchin <jkitchin@andrew.cmu.edu>
+;; URL: https://github.com/jkitchin/org-ref
+;; Version: 0.1
+;; Keywords: org-mode, cite, ref, label
+;; Package-Requires: ((dash) (helm) (helm-bibtex))
+
;; This file is not currently part of GNU Emacs.
;; This program is free software; you can redistribute it and/or
;;; Commentary:
;;
-;; Lisp code to setup bibliography cite, ref and label org-mode links. also
-;; sets up reftex and helm for org-mode citations. The links are clickable and
-;; do things that are useful. You should really read org-ref.org for details.
+;; Lisp code to setup bibliography cite, ref and label org-mode links.
+;; also sets up reftex and helm for org-mode citations. The links are
+;; clickable and do things that are useful. You should really read
+;; org-ref.org for details.
;;
-;; Package-Requires: ((dash) (helm) (helm-bibtex))
+
+;;; Code:
#+END_SRC
** requires
(require 'helm)
(require 'helm-config)
(require 'helm-bibtex)
+(require 'org)
#+END_SRC
** Custom variables
point to get a comma, or the end of the link, and then backwards
to get a comma, or the beginning of the link. that delimits the
keyword we clicked on. We also strip the text properties."
- (interactive)
(let* ((object (org-element-context))
(link-string (org-element-property :path object)))
;; you may click on the part before the citations. here we make
falling back to what the user has set in org-ref-default-bibliography
"
- (interactive)
(catch 'result
(save-excursion
(goto-char (point-min))
#+BEGIN_SRC emacs-lisp :tangle org-ref.el
(defun org-ref-get-bibtex-key-and-file (&optional key)
"returns the bibtex key and file that it is in. If no key is provided, get one under point"
- (interactive)
(let ((org-ref-bibliography-files (org-ref-find-bibliography))
(file))
(unless key
(defun org-ref-get-doi-at-point ()
"Get doi for key at point."
- (interactive)
(let* ((results (org-ref-get-bibtex-key-and-file))
(key (car results))
(bibfile (cdr results))
#+BEGIN_SRC emacs-lisp :tangle org-ref.el
(defun org-ref-format-citation-description (desc)
- "return formatted citation description. if the cite link has a description, it is optional text for the citation command. You can specify pre and post text by separating these with ::."
- (interactive)
+ "Return formatted citation description. If the cite link has a
+description, it is optional text for the citation command. You
+can specify pre and post text by separating these with ::, for
+example [[cite:key][pre text::post text]]."
(cond
((string-match "::" desc)
(format "[%s][%s]" (car (setq results (split-string desc "::"))) (cadr results)))
(t (format "[%s]" desc))))
(defun org-ref-define-citation-link (type &optional key)
- "add a citation link for org-ref. With optional key, set the reftex binding. For example:
+ "Add a citation link of TYPE for org-ref.
+With optional KEY, set the reftex binding. For example:
(org-ref-define-citation-link \"citez\" ?z) will create a new citez link, with reftex key of z,
and the completion function."
(interactive "sCitation Type: \ncKey: ")
(mapcar 'org-ref-define-citation-link org-ref-cite-types)
#+END_SRC
+#+RESULTS:
+
*** org-ref-insert-cite-link
We need a convenient method to insert links. In reftex you use the keystroke C-c ], which gives you a minibuffer to search the bibtex files from. This function is bound to that same keystroke here [[*org-mode%20/%20reftex%20setup][org-mode / reftex setup]]. This function will append to a cite link if you call it while on a link.
(mapconcat 'identity (reftex-citation t) ",")))))
;; you pressed a C-u so we run this code
- (reftex-citation)))
- )
+ (reftex-citation))))
#+END_SRC
cite:zhou-2004-first-lda-u,paier-2006-errat,boes-2015-estim-bulk
(when (-contains? org-ref-cite-types (plist-get plist :type))
(dolist (key (org-ref-split-and-strip-string (plist-get plist :path)))
(when (not (index key bibtex-keys))
- (message-box "%s" link)
(setq
bad-citations
(append
Now, we have a functions for candidates, we can make helm sources for each one, and then run a helm command to view them.
#+BEGIN_SRC emacs-lisp :tangle org-ref.el
+;;;###autoload
(defun org-ref ()
"Opens a helm interface to actions for org-ref.
Shows bad citations, ref links and labels"
#+BEGIN_SRC emacs-lisp :tangle org-ref.el
(defun org-ref-get-citation-year (key)
"get the year of an entry with key. Returns year as a string."
- (interactive)
(let* ((results (org-ref-get-bibtex-key-and-file key))
(bibfile (cdr results)))
(with-temp-buffer
))))
(defun org-ref-sort-citation-link ()
- "replace link at point with sorted link by year"
+ "Replace link at point with sorted link by year."
(interactive)
(let* ((object (org-element-context))
(type (org-element-property :type object))
Sometimes it may be helpful to manually change the order of citations. These functions define shift-arrow functions.
#+BEGIN_SRC emacs-lisp :tangle org-ref.el
(defun org-ref-swap-keys (i j keys)
- "swap the keys in a list with index i and j"
+ "Swap the KEYS in a list with index I and J."
(let ((tempi (nth i keys)))
(setf (nth i keys) (nth j keys))
(setf (nth j keys) tempi))
keys)
+
(defun org-ref-swap-citation-link (direction)
"move citation at point in direction +1 is to the right, -1 to the left"
(interactive)
(org-ref-swap-keys i (- i 1) keys))
(setq keys (mapconcat 'identity keys ","))
;; and replace the link with the sorted keys
- (cl--set-buffer-substring begin end (concat type ":" keys " "))
+ (cl--set-buffer-substring
+ begin end
+ (concat
+ type ":" keys
+ ;; It seems the space at the end can get consumed, so we see if there
+ ;; is a space, and add it if so. Sometimes there is a comma or period,
+ ;; then we do not want a space.
+ (when
+ (save-excursion
+ (goto-char end)
+ (looking-back " ")) " ")))
;; now go forward to key so we can move with the key
(re-search-forward key)
(goto-char (match-beginning 0)))))
[[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] is a very cool interface to bibtex files. Out of the box though, it is not super convenient for org-ref. Here, we modify it to make it fit our workflow and extend it where needed.
Let us add keywords as a searchable field.
-#+BEGIN_SRC emacs-lisp
+#+BEGIN_SRC emacs-lisp :tangle org-ref.el
(setq helm-bibtex-additional-search-fields '(keywords))
#+END_SRC
-Next, we are going to add keywords to the helm interface.
-#+BEGIN_SRC emacs-lisp
+Next, we are going to add keywords to the helm interface. This modifies the helm-bibtex function to add our keywords.
+#+BEGIN_SRC emacs-lisp :tangle org-ref.el
(defun helm-bibtex-candidates-formatter (candidates source)
"Formats BibTeX entries for display in results list."
(cl-loop
(-zip-with (lambda (f w) (truncate-string-to-width f w 0 ?\s))
fields (list 36 (- width 85) 4 1 1 7 7)))
entry-key)))
-
#+END_SRC
-1. Make the default action to insert selected keys.
-2. Make open entry second action
-#+BEGIN_SRC emacs-lisp :tangle org-ref.el
-(defun org-ref-tag-entries (candidates)
- "Set tags on selected entries."
+Next, we add some functions to add keywords to a bibtex entry using a helm interface, and a new action to add keywords to entries from helm-bibtex.
+#+BEGIN_SRC emacs-lisp :tangle org-ref.el
+;; adapted from bibtex-utils.el
+;; these are candidates for selecting keywords/tags
+(defun org-ref-bibtex-keywords ()
+ "Get keywords defined in current bibtex file.
+These are in the keywords field, and are comma or semicolon separated."
+ (save-excursion
+ (goto-char (point-min))
+ (let (keywords kstring)
+ (while (re-search-forward "^\\s-*keywords.*{\\([^}]+\\)}" nil t)
+ ;; TWS - remove newlines/multiple spaces:
+ (setq kstring (replace-regexp-in-string "[ \t\n]+" " " (match-string 1)))
+ (mapc
+ (lambda (v)
+ (add-to-list 'keywords v t))
+ (split-string kstring "\\(,\\|;\\)[ \n]*\\|{\\|}" t)))
+ keywords)))
+
+
+(defun org-ref-set-bibtex-keywords (keywords &optional arg)
+ "Add KEYWORDS to a bibtex entry.
+If KEYWORDS is a list, it is converted to a comma-separated string. The KEYWORDS are added to the beginning of the field. Otherwise KEYWORDS should be a string of comma-separate keywords."
+ (interactive "sKeywords: \nP")
+ (bibtex-set-field
+ "keywords"
+ (if arg
+ ;; replace with arg
+ (if (listp keywords)
+ (mapconcat 'identity keywords ", ")
+ keywords)
+ ;; else concatentate
+ (concat
+ (if (listp keywords)
+ (mapconcat 'identity keywords ", ")
+ keywords)
+ (when (not (string= "" (bibtex-autokey-get-field "keywords")))
+ (concat ", " (bibtex-autokey-get-field "keywords"))))))
+ (save-buffer))
+
+
+(defun helm-tag-bibtex-entry ()
+ "Helm interface to add keywords to a bibtex entry.
+Run this with the point in a bibtex entry."
+ (interactive)
+ (let ((keyword-source `((name . "Existing keywords")
+ (candidates . ,(org-ref-bibtex-keywords))
+ (action . (lambda (candidate)
+ (org-ref-set-bibtex-keywords
+ (mapconcat
+ 'identity
+ (helm-marked-candidates)
+ ", "))))))
+ (fallback-source `((name . "Add new keywords")
+ (dummy)
+ (action . (lambda (candidate)
+ (org-ref-set-bibtex-keywords helm-pattern)
+ )))))
+ (helm :sources '(keyword-source fallback-source))))
+
+(defun helm-bibtex-show-entry (key)
+ "Show the entry in the BibTeX file.
+The original function in helm-bibtex has a bug where it finds the
+first key that partially matches. This version avoids that."
+ (catch 'break
+ (dolist (bibtex-file (if (listp helm-bibtex-bibliography)
+ helm-bibtex-bibliography
+ (list helm-bibtex-bibliography)))
+ (let ((buf (helm-bibtex-buffer-visiting bibtex-file))
+ (entries '()))
+ (find-file bibtex-file)
+ (bibtex-map-entries
+ (lambda (key start end)
+ (add-to-list 'entries (cons key start))))
+ (if (assoc key entries)
+ (progn
+ (goto-char (cdr (assoc key entries)))
+ (throw 'break t))
+ (unless buf
+ (kill-buffer)))))))
+
+(defun org-ref-helm-tag-entries (candidates)
+ "Set tags on selected bibtex entries from helm-bibtex.
+User is prompted for tags. This function is called from `helm-bibtex'."
+ (message "")
(let ((keywords (read-input "Keywords (comma separated): ")))
(loop for key in (helm-marked-candidates)
do
"keywords"
(concat
keywords
- "," (bibtex-autokey-get-field "keywords")))
+ ", " (bibtex-autokey-get-field "keywords")))
(save-buffer)))))
+#+END_SRC
+Next, adapt the helm-bibtex source with these features:
+
+1. Make the default action to insert selected keys.
+2. Make open entry second action
+3. Add some features for adding keywords to bibtex entries.
+
+#+BEGIN_SRC emacs-lisp :tangle org-ref.el
(setq helm-source-bibtex
'((name . "BibTeX entries")
(init . helm-bibtex-init)
("Insert BibTeX entry" . helm-bibtex-insert-bibtex)
("Attach PDF to email" . helm-bibtex-add-PDF-attachment)
("Edit notes" . helm-bibtex-edit-notes)
- ("Tag entries" . org-ref-tag-entries)
+ ("Add keywords to entries" . org-ref-helm-tag-entries)
))))
#+END_SRC
(setq helm-bibtex-format-citation-functions
'((org-mode . helm-bibtex-format-org-ref)))
+;;;###autoload
(defun org-ref-helm-insert-cite-link (arg)
"org-ref function to use helm-bibtex to insert a citation link.
With one prefix arg, insert a ref link.
((equal arg '(16))
(org-ref-helm-insert-label-link))))
-(require 'helm-bibtex)
;; add our own fallback entries where we want them. These appear in reverse order of adding in the menu
(setq helm-bibtex-fallback-options
#+BEGIN_SRC emacs-lisp :tangle org-ref.el
(defun org-ref-get-citation-string-at-point ()
"Get a string of a formatted citation"
- (interactive)
(let* ((results (org-ref-get-bibtex-key-and-file))
(key (car results))
(bibfile (cdr results)))
(defun org-ref-cite-candidates ()
"Generate the list of possible candidates for click actions on a cite link.
Checks for pdf and doi, and add appropriate functions."
- (interactive)
(let* ((results (org-ref-get-bibtex-key-and-file))
(key (car results))
(pdf-file (format (concat org-ref-pdf-directory "%s.pdf") key))
'("Example" . (lambda () (message-box "You did it!")))
t)
+;;;###autoload
(defun org-ref-cite-click-helm (key)
- "subtle points.
+ "Open helm for actions on a cite link.
+subtle points.
1. get name and candidates before entering helm because we need the org-buffer.
2. switch back to the org buffer before evaluating the action. most of them need the point and buffer."
(interactive)
* End of code
#+BEGIN_SRC emacs-lisp :tangle org-ref.el
(provide 'org-ref)
+
+;;; org-ref.el ends here
#+END_SRC
* Build :noexport: