make double prefix replace ref link
[org-ref.git] / org-ref.org
1 #+TITLE: Org-ref - The best reference handling for org-mode
2 #+AUTHOR: John Kitchin
3 #+DATE: April 29, 2014
4
5 * Introduction
6
7 This document is an experiment at creating a literate program to provide similar features as reftex for org-mode referencing. These features include:
8
9 1. using completion to create links
10 2. storing links to places,
11 3. Clickable links that do useful things
12 4. Exportable links to LaTeX
13 5. Utility functions for dealing with bibtex files and org-files
14
15 ** Header
16 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
17 ;;; org-ref.el --- setup bibliography, cite, ref and label org-mode links.
18
19 ;; Copyright(C) 2014 John Kitchin
20
21 ;; Author: John Kitchin <jkitchin@andrew.cmu.edu>
22 ;; This file is not currently part of GNU Emacs.
23
24 ;; This program is free software; you can redistribute it and/or
25 ;; modify it under the terms of the GNU General Public License as
26 ;; published by the Free Software Foundation; either version 2, or (at
27 ;; your option) any later version.
28
29 ;; This program is distributed in the hope that it will be useful, but
30 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
31 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
32 ;; General Public License for more details.
33
34 ;; You should have received a copy of the GNU General Public License
35 ;; along with this program ; see the file COPYING.  If not, write to
36 ;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
37 ;; Boston, MA 02111-1307, USA.
38
39 ;;; Commentary:
40 ;;
41 ;; Lisp code to setup bibliography cite, ref and label org-mode links.  also
42 ;; sets up reftex and helm for org-mode citations. The links are clickable and
43 ;; do things that are useful. You should really read org-ref.org for details.
44 ;;
45 ;; Package-Requires: ((dash) (helm) (helm-bibtex))
46 #+END_SRC
47
48 ** requires
49 The only external require is reftex-cite
50
51 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
52 (require 'reftex-cite)
53 (require 'dash)
54 (require 'helm)
55 (require 'helm-bibtex)
56 #+END_SRC
57
58 ** Custom variables
59 There are some variables needed later to tell this library where you store your pdf files, where your notes file is, and your default bibliography. This variable is similar to the reftex-default-bibliography. I do not remember why I made it separate.
60
61 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
62 (defgroup org-ref nil
63   "customization group for org-ref")
64
65 (defcustom org-ref-bibliography-notes
66   nil
67   "filename to where you will put all your notes about an entry in
68   the default bibliography."
69   :type 'file
70   :group 'org-ref)
71
72 (defcustom org-ref-default-bibliography
73   nil
74   "list of bibtex files to search for. You should use full-paths for each file."
75   :type '(repeat :tag "List of bibtex files" file)
76   :group 'org-ref)
77
78 (defcustom org-ref-pdf-directory
79   nil
80   "directory where pdfs are stored by key. put a trailing / in"
81   :type 'directory
82   :group 'org-ref)
83
84 (defcustom org-ref-default-citation-link
85   "cite"
86   "The default type of citation link to use"
87   :type 'string
88   :group 'org-ref)
89
90 (defcustom org-ref-insert-cite-key
91   "C-c ]"
92   "Keyboard shortcut to insert a citation."
93   :type 'string
94   :group 'org-ref)
95
96 (defcustom org-ref-bibliography-entry-format
97   '(("article" . "%a, %t, <i>%j</i>, <b>%v(%n)</b>, %p (%y). <a href=\"%U\">link</a>. <a href=\"http://dx.doi.org/%D\">doi</a>.")
98
99     ("book" . "%a, %t, %u (%y).")
100
101     ("proceedings" . "%e, %t in %S, %u (%y).")
102
103     ("inproceedings" . "%a, %t, %p, in %b, edited by %e, %u (%y)"))
104
105   "string to format an entry. Just the reference, no numbering at the beginning, etc... see the `org-ref-reftex-format-citation' docstring for the escape codes."
106   :type 'string
107   :group 'org-ref)
108
109 (defcustom org-ref-open-notes-function
110   (lambda ()
111     (org-show-entry)
112     (show-branches)
113     (show-children)
114     (org-cycle '(64))
115     ;;(org-tree-to-indirect-buffer)
116     (outline-previous-visible-heading 1)
117     (recenter-top-bottom 0))
118   "User-defined way to open a notes entry. This is excecuted after the entry is found, with the cursor at the beginning of the headline. The default setting fully expands the notes, and moves the headline to the top of the buffer"
119 :type 'function
120 :group 'org-ref)
121
122
123 (defcustom org-ref-open-pdf-function
124    'org-ref-open-pdf-at-point
125 "User-defined function to open a pdf from a link. The function must get the key at point, and derive a path to the pdf file, then open it. The default function is `org-ref-open-pdf-at-point'."
126   :type 'function
127   :group 'org-ref)
128
129
130 (defcustom org-ref-insert-cite-function
131   'org-ref-helm-insert-cite-link
132   "Function to call to insert citation links. The default is `org-ref-helm-insert-cite-link' which uses `helm-bibtex'. org-ref modifies helm-bibtex a little bit to give org-mode citations, and to reorder default actions. You may use `org-ref-insert-cite-link' if you like the reftex interface."
133  :type 'function
134  :group 'org-ref)
135
136
137 (defcustom org-ref-cite-onclick-function
138   'org-ref-cite-click-helm
139   "Function that runs when you click on a cite link. The function must take no arguments. You may also use `org-ref-cite-onclick-minibuffer-menu' if you do not like helm."
140  :type 'function
141  :group 'org-ref)
142
143 (defcustom org-ref-show-citation-on-enter t
144   "If non-nil add a hook function to show the citation summary in
145   the minibuffer just by putting the cursor in a link"
146  :group 'org-ref)
147
148 #+END_SRC
149
150 This next variable determines the citation types that are available in org-ref. Links for each one are automatically generated, and completion functions are automatically generated. Users may add to this list in their own init files.
151
152 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
153 (defcustom org-ref-cite-types
154   '("cite" "nocite" ;; the default latex cite commands
155     ;; natbib cite commands, http://ctan.unixbrain.com/macros/latex/contrib/natbib/natnotes.pdf
156     "citet" "citet*" "citep" "citep*"
157     "citealt" "citealt*" "citealp" "citealp*"
158     "citenum" "citetext"
159     "citeauthor" "citeauthor*"
160     "citeyear" "citeyear*"
161     "Citet" "Citep" "Citealt" "Citealp" "Citeauthor"
162     ;; biblatex commands
163     ;; http://ctan.mirrorcatalogs.com/macros/latex/contrib/biblatex/doc/biblatex.pdf
164     "Cite"
165     "parencite" "Parencite"
166     "footcite" "footcitetext"
167     "textcite" "Textcite"
168     "smartcite" "Smartcite"
169     "cite*" "parencite*" "supercite"
170     "autocite" "Autocite" "autocite*" "Autocite*"
171     "Citeauthor*"
172     "citetitle" "citetitle*"
173     "citedate" "citedate*"
174     "citeurl"
175     "fullcite" "footfullcite"
176     ;; "volcite" "Volcite" cannot support the syntax
177     "notecite" "Notecite"
178     "pnotecite" "Pnotecite"
179     "fnotecite"
180     ;; multicites. Very limited support for these.
181     "cites" "Cites" "parencites" "Parencites"
182     "footcites" "footcitetexts"
183     "smartcites" "Smartcites" "textcites" "Textcites"
184     "supercites" "autocites" "Autocites"
185     ;; for the bibentry package
186     "bibentry"
187     )
188   "List of citation types known in org-ref"
189   :type '(repeat :tag "List of citation types" string)
190   :group 'org-ref)
191 #+END_SRC
192
193 We need a hook variable to store user-defined bibtex entry cleaning functions
194 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
195 (defcustom org-ref-clean-bibtex-entry-hook nil
196   "Hook that is run in org-ref-clean-bibtex-entry. The functions should take no arguments, and operate on the bibtex entry at point."
197   :group 'org-ref
198   :type 'hook)
199 #+END_SRC
200
201 ** Program variables
202 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
203 (defvar org-ref-bibliography-files
204   nil
205   "variable to hold bibliography files to be searched")
206 #+END_SRC
207
208 ** org-mode / reftex setup
209
210 We setup reftex here. We use a custom insert cite link function defined here: [[*org-ref-insert-cite-link][org-ref-insert-cite-link]]. We setup reftex to use our org citation format.
211
212 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
213 (require 'reftex)
214 (defun org-mode-reftex-setup ()
215     (and (buffer-file-name)
216          (file-exists-p (buffer-file-name))
217          (global-auto-revert-mode t)
218          ;; I do not remember why I put this next line in. It doesn't
219          ;; work for org-files. Nothing very bad happens, but it gives
220          ;; an annoying error. Commenting it out for now.
221          ;(reftex-parse-all
222          )
223     (make-local-variable 'reftex-cite-format)
224     (setq reftex-cite-format 'org))
225
226 ;; define key for inserting citations
227 (define-key org-mode-map
228   (kbd org-ref-insert-cite-key)
229   org-ref-insert-cite-function)
230
231 (when org-ref-show-citation-on-enter
232  (setq org-ref-message-timer
233        (run-with-idle-timer 0.5 t 'org-ref-link-message)))
234
235 (defun org-ref-show-link-messages ()
236   "Turn on link messages. You will see a message in the
237 minibuffer when on a cite, ref or label link."
238   (interactive)
239   (setq org-ref-message-timer
240         (run-with-idle-timer 0.5 t 'org-ref-link-message))
241   )
242 (defun org-ref-cancel-link-messages ()
243   "Stop showing messages in minibuffer when on a link."
244   (interactive)
245   (cancel-timer org-ref-message-timer))
246
247 ;; this approach caused the selected region to not be highlighted any more.
248 ; (add-hook 'post-command-hook 'org-ref-link-message))
249 ; (remove-hook 'post-command-hook 'org-ref-link-message))
250
251 (add-hook 'org-mode-hook 'org-mode-reftex-setup)
252
253 (eval-after-load 'reftex-vars
254   '(progn
255       (add-to-list 'reftex-cite-format-builtin
256                    '(org "Org-mode citation"
257                          ((?\C-m . "cite:%l")     ; default
258                           (?d . ",%l")            ; for appending
259                           (?a . "autocite:%l")
260                           (?t . "citet:%l")
261                           (?T . "citet*:%l")
262                           (?p . "citep:%l")
263                           (?P . "citep*:%l")
264                           (?h . "citeauthor:%l")
265                           (?H . "citeauthor*:%l")
266                           (?y . "citeyear:%l")
267                           (?x . "citetext:%l")
268                           (?n . "nocite:%l")
269                           )))))
270 #+END_SRC
271
272 You may want to add new formats to the reftex-cite-format-builtin variable. Here is an example of adding two new formats. Note that this does not create the links.
273
274 #+BEGIN_SRC emacs-lisp :tangle no
275 ;; add new format
276 (setf (nth 2 (assoc 'org reftex-cite-format-builtin))
277       (append (nth 2 (assoc 'org reftex-cite-format-builtin)) '((?W  . "textcite:%l")
278             (?z  . "newcite:%l"))))
279 #+END_SRC
280
281 You can define a new citation link like this:
282 #+BEGIN_SRC emacs-lisp :tangle no
283 (org-ref-define-citation-link "citez" ?z)
284 #+END_SRC
285
286 * Links
287 Most of this library is the creation of functional links to help with references and citations.
288 ** General utilities
289 We need several general utilities for this module. They are organized here. We frequently need to remove white space from the front and back of a string. Here we do that for a string.
290
291 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
292 (defun org-ref-strip-string (string)
293   "strip leading and trailing whitespace from the string"
294   (replace-regexp-in-string
295    (concat search-whitespace-regexp "$" ) ""
296    (replace-regexp-in-string
297     (concat "^" search-whitespace-regexp ) "" string)))
298 #+END_SRC
299
300 It is helpful to make the previous function operate on a list of strings here.
301
302 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
303 (defun org-ref-split-and-strip-string (string)
304   "split key-string and strip keys. Assumes the key-string is comma delimited"
305   (mapcar 'org-ref-strip-string (split-string string ",")))
306 #+END_SRC
307
308 ** bibliography and bibliographystyle
309 *** An html bibliography
310
311 Reftex is no longer being developed. I want a url and doi option for formatting, so I am modifying this [[file:emacs-24.3/lisp/textmodes/reftex-cite.el::(defun%20reftex-format-citation%20(entry%20format)][function]] from reftex-cite to provide that. We need to modify the reftex-get-bib-field code a bit to remove enclosing braces and quotes so we can make nice looking links.
312
313 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
314 (defun org-ref-reftex-get-bib-field (field entry &optional format)
315   "similar to reftex-get-bib-field, but removes enclosing braces and quotes"
316   (let ((result))
317     (setq result (reftex-get-bib-field field entry format))
318     (when (and (not (string= result "")) (string= "{" (substring result 0 1)))
319       (setq result (substring result 1 -1)))
320     (when (and (not (string= result "")) (string= "\"" (substring result 0 1)))
321       (setq result (substring result 1 -1)))
322       result))
323
324 (defun org-ref-reftex-format-citation (entry format)
325   "return a formatted string for the bibtex entry (from bibtex-parse-entry) according
326 to the format argument. The format is a string with these percent escapes.
327
328 In the format, the following percent escapes will be expanded.
329
330 %l   The BibTeX label of the citation.
331 %a   List of author names, see also `reftex-cite-punctuation'.
332 %2a  Like %a, but abbreviate more than 2 authors like Jones et al.
333 %A   First author name only.
334 %e   Works like %a, but on list of editor names. (%2e and %E work a well)
335
336 It is also possible to access all other BibTeX database fields:
337 %b booktitle     %c chapter        %d edition    %h howpublished
338 %i institution   %j journal        %k key        %m month
339 %n number        %o organization   %p pages      %P first page
340 %r address       %s school         %u publisher  %t title
341 %v volume        %y year
342 %B booktitle, abbreviated          %T title, abbreviated
343 %U url
344 %D doi
345 %S series
346
347 Usually, only %l is needed.  The other stuff is mainly for the echo area
348 display, and for (setq reftex-comment-citations t).
349
350 %< as a special operator kills punctuation and space around it after the
351 string has been formatted.
352
353 A pair of square brackets indicates an optional argument, and RefTeX
354 will prompt for the values of these arguments.
355
356 Beware that all this only works with BibTeX database files.  When
357 citations are made from the \bibitems in an explicit thebibliography
358 environment, only %l is available."
359   ;; Format a citation from the info in the BibTeX ENTRY
360
361   (unless (stringp format) (setq format "\\cite{%l}"))
362
363   (if (and reftex-comment-citations
364            (string-match "%l" reftex-cite-comment-format))
365       (error "reftex-cite-comment-format contains invalid %%l"))
366
367   (while (string-match
368           "\\(\\`\\|[^%]\\)\\(\\(%\\([0-9]*\\)\\([a-zA-Z]\\)\\)[.,;: ]*\\)"
369           format)
370     (let ((n (string-to-number (match-string 4 format)))
371           (l (string-to-char (match-string 5 format)))
372           rpl b e)
373       (save-match-data
374         (setq rpl
375               (cond
376                ((= l ?l) (concat
377                           (org-ref-reftex-get-bib-field "&key" entry)
378                           (if reftex-comment-citations
379                               reftex-cite-comment-format
380                             "")))
381                ((= l ?a) (reftex-format-names
382                           (reftex-get-bib-names "author" entry)
383                           (or n 2)))
384                ((= l ?A) (car (reftex-get-bib-names "author" entry)))
385                ((= l ?b) (org-ref-reftex-get-bib-field "booktitle" entry "in: %s"))
386                ((= l ?B) (reftex-abbreviate-title
387                           (org-ref-reftex-get-bib-field "booktitle" entry "in: %s")))
388                ((= l ?c) (org-ref-reftex-get-bib-field "chapter" entry))
389                ((= l ?d) (org-ref-reftex-get-bib-field "edition" entry))
390                ((= l ?D) (org-ref-reftex-get-bib-field "doi" entry))
391                ((= l ?e) (reftex-format-names
392                           (reftex-get-bib-names "editor" entry)
393                           (or n 2)))
394                ((= l ?E) (car (reftex-get-bib-names "editor" entry)))
395                ((= l ?h) (org-ref-reftex-get-bib-field "howpublished" entry))
396                ((= l ?i) (org-ref-reftex-get-bib-field "institution" entry))
397                ((= l ?j) (org-ref-reftex-get-bib-field "journal" entry))
398                ((= l ?k) (org-ref-reftex-get-bib-field "key" entry))
399                ((= l ?m) (org-ref-reftex-get-bib-field "month" entry))
400                ((= l ?n) (org-ref-reftex-get-bib-field "number" entry))
401                ((= l ?o) (org-ref-reftex-get-bib-field "organization" entry))
402                ((= l ?p) (org-ref-reftex-get-bib-field "pages" entry))
403                ((= l ?P) (car (split-string
404                                (org-ref-reftex-get-bib-field "pages" entry)
405                                "[- .]+")))
406                ((= l ?s) (org-ref-reftex-get-bib-field "school" entry))
407                ((= l ?S) (org-ref-reftex-get-bib-field "series" entry))
408                ((= l ?u) (org-ref-reftex-get-bib-field "publisher" entry))
409                ((= l ?U) (org-ref-reftex-get-bib-field "url" entry))
410                ((= l ?r) (org-ref-reftex-get-bib-field "address" entry))
411                ;; strip enclosing brackets from title if they are there
412                ((= l ?t) (org-ref-reftex-get-bib-field "title" entry))
413                ((= l ?T) (reftex-abbreviate-title
414                           (org-ref-reftex-get-bib-field "title" entry)))
415                ((= l ?v) (org-ref-reftex-get-bib-field "volume" entry))
416                ((= l ?y) (org-ref-reftex-get-bib-field "year" entry)))))
417
418       (if (string= rpl "")
419           (setq b (match-beginning 2) e (match-end 2))
420         (setq b (match-beginning 3) e (match-end 3)))
421       (setq format (concat (substring format 0 b) rpl (substring format e)))))
422   (while (string-match "%%" format)
423     (setq format (replace-match "%" t t format)))
424   (while (string-match "[ ,.;:]*%<" format)
425     (setq format (replace-match "" t t format)))
426   ;; also replace carriage returns, tabs, and multiple whitespaces
427   (setq format (replace-regexp-in-string "\n\\|\t\\|\s+" " " format))
428   format)
429
430 (defun org-ref-get-bibtex-entry-citation (key)
431   "returns a string for the bibliography entry corresponding to key, and formatted according to the type in `org-ref-bibliography-entry-format'"
432
433   (let ((org-ref-bibliography-files (org-ref-find-bibliography))
434         (file) (entry) (bibtex-entry) (entry-type) (format))
435
436     (setq file (catch 'result
437                  (loop for file in org-ref-bibliography-files do
438                        (if (org-ref-key-in-file-p key (file-truename file))
439                            (throw 'result file)
440                          (message "%s not found in %s" key (file-truename file))))))
441
442     (with-temp-buffer
443       (insert-file-contents file)
444       (bibtex-search-entry key nil 0)
445       (setq bibtex-entry (bibtex-parse-entry))
446       (setq entry-type (downcase (cdr (assoc "=type=" bibtex-entry))))
447       (setq format (cdr (assoc entry-type org-ref-bibliography-entry-format)))
448       (if format
449           (setq entry  (org-ref-reftex-format-citation bibtex-entry format))
450         (save-restriction
451           (bibtex-narrow-to-entry)
452           (setq entry (buffer-string)))))
453     entry))
454 #+END_SRC
455
456 #+RESULTS:
457 : org-ref-reftex-format-citation
458
459 Here is how to use the function. You call it with point in an entry in a bibtex file.
460
461 #+BEGIN_SRC emacs-lisp :tangle no
462 (let((org-ref-bibliography-entry-format   "%a, %t, <i>%j</i>, <b>%v(%n)</b>, %p (%y). <a href=\"%U\">link</a>. <a href=\"http://dx.doi.org/%D\">doi</a>."))
463   (org-ref-get-bibtex-entry-citation  "armiento-2014-high"))
464 #+END_SRC
465 #+RESULTS:
466 : Armiento, Kozinsky, Hautier, , Fornari \& Ceder, High-throughput screening of perovskite alloys for  piezoelectric performance and thermodynamic  stability, <i>Phys. Rev. B</i>, <b>89()</b>, 134103 (2014). <a href="http://link.aps.org/doi/10.1103/PhysRevB.89.134103">link</a>. <a href="http://dx.doi.org/10.1103/PhysRevB.89.134103">doi</a>.
467
468 I am not sure why full author names are not used.
469
470 This code provides some functions to generate a simple sorted bibliography in html. First we get all the keys in the buffer.
471
472 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
473 (defun org-ref-get-bibtex-keys ()
474   "return a list of unique keys in the buffer."
475   (let ((keys '()))
476     (org-element-map (org-element-parse-buffer) 'link
477       (lambda (link)
478         (let ((plist (nth 1 link)))
479           (when (-contains? org-ref-cite-types (plist-get plist ':type))
480             (dolist
481                 (key
482                  (org-ref-split-and-strip-string (plist-get plist ':path)))
483               (when (not (-contains? keys key))
484                 (setq keys (append keys (list key)))))))))
485     ;; Sort keys alphabetically
486     (setq keys (cl-sort keys 'string-lessp :key 'downcase))
487     keys))
488 #+END_SRC
489
490 This function gets the html for one entry.
491
492 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
493 (defun org-ref-get-bibtex-entry-html (key)
494   "returns an html string for the bibliography entry corresponding to key"
495
496   (format "<li><a id=\"%s\">[%s] %s</a></li>" key key (org-ref-get-bibtex-entry-citation key)))
497 #+END_SRC
498
499 Now, we map over the whole list of keys, and the whole bibliography, formatted as an unordered list.
500
501 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
502 (defun org-ref-get-html-bibliography ()
503   "Create an html bibliography when there are keys"
504   (let ((keys (org-ref-get-bibtex-keys)))
505     (when keys
506       (concat "<h1>Bibliography</h1>
507 <ul>"
508               (mapconcat (lambda (x) (org-ref-get-bibtex-entry-html x)) keys "\n")
509               "\n</ul>"))))
510 #+END_SRC
511
512 I do not have plans to make a numbered bibliography with numbered citations anytime soon. This will require changing the way the citation links are exported, and keeping track of the numbers.
513
514 *** An org bibliography
515 You can export an org-file to an org-file or org-buffer (org-org-epxort-as-org). In this case, it would be useful convert the cite links to links to custom_ids, and the bibliography link to a first-level heading Bibliography with org-bibtex like headings for each entry. This code should enable this. Right now, it does not appear to work for org export though.
516
517 First, we get the string for a single entry.
518 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
519 (defun org-ref-get-bibtex-entry-org (key)
520   "returns an org string for the bibliography entry corresponding to key"
521   (let ((org-ref-bibliography-files (org-ref-find-bibliography))
522         (file) (entry) (bibtex-entry) (entry-type) (format))
523
524     (setq file (catch 'result
525                  (loop for file in org-ref-bibliography-files do
526                        (if (org-ref-key-in-file-p key (file-truename file))
527                            (throw 'result file)
528                          (message "%s not found in %s" key (file-truename file))))))
529
530     (with-temp-buffer
531       (insert-file-contents file)
532       (bibtex-search-entry key nil 0)
533       (setq entry (bibtex-parse-entry))
534       (format "** %s - %s
535   :PROPERTIES:
536   %s
537   :END:
538 " (org-ref-reftex-get-bib-field "author" entry)
539 (org-ref-reftex-get-bib-field "title" entry)
540 (concat "   :CUSTOM_ID: " (org-ref-reftex-get-bib-field "=key=" entry) "\n"
541         (mapconcat (lambda (element) (format "   :%s: %s"
542                                              (upcase (car element))
543                                              (cdr element)))
544                    entry
545                    "\n"))))))
546 #+END_SRC
547
548 Now, we loop over the keys, and combine all the entries into a bibliography.
549 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
550 (defun org-ref-get-org-bibliography ()
551   "Create an org bibliography when there are keys"
552   (let ((keys (org-ref-get-bibtex-keys)))
553     (when keys
554       (concat "* Bibliography
555 "
556               (mapconcat (lambda (x) (org-ref-get-bibtex-entry-org x)) keys "\n")
557               "\n"))))
558 #+END_SRC
559
560 *** An ascii bibliography
561
562 This function gets the html for one entry.
563
564 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
565 (defun org-ref-get-bibtex-entry-ascii (key)
566   "returns an ascii string for the bibliography entry corresponding to key"
567
568   (format "[%s] %s" key (org-ref-get-bibtex-entry-citation key)))
569 #+END_SRC
570
571 Now, we map over the whole list of keys, and the whole bibliography, formatted as an unordered list.
572
573 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
574 (defun org-ref-get-ascii-bibliography ()
575   "Create an html bibliography when there are keys"
576   (let ((keys (org-ref-get-bibtex-keys)))
577     (when keys
578       (concat
579 "Bibliography
580 =============
581 "
582               (mapconcat (lambda (x) (org-ref-get-bibtex-entry-ascii x)) keys "\n")
583               "\n"))))
584 #+END_SRC
585
586
587 *** the links
588 We use a link for the bibliography so that we can click on it to open the bibliography file. The link may have more than one bibliography file in it, separated by commas. Clicking opens the file under the cursor. The bibliographies should be full filenames with the bib extension. Clicking on this link makes reftex-default-bibliography local and sets it to the list of files in the link. We need this to use reftex's searching capability.
589
590 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
591 (org-add-link-type "bibliography"
592                    ;; this code is run on clicking. The bibliography
593                    ;; may contain multiple files. this code finds the
594                    ;; one you clicked on and opens it.
595                    (lambda (link-string)
596                        ;; get link-string boundaries
597                        ;; we have to go to the beginning of the line, and then search forward
598
599                      (let* ((bibfile)
600                             ;; object is the link you clicked on
601                             (object (org-element-context))
602                             (link-string-beginning)
603                             (link-string-end))
604
605                      (save-excursion
606                        (goto-char (org-element-property :begin object))
607                        (search-forward link-string nil nil 1)
608                        (setq link-string-beginning (match-beginning 0))
609                        (setq link-string-end (match-end 0)))
610
611                        ;; We set the reftex-default-bibliography
612                        ;; here. it should be a local variable only in
613                        ;; the current buffer. We need this for using
614                        ;; reftex to do citations.
615                        (set (make-local-variable 'reftex-default-bibliography)
616                             (split-string (org-element-property :path object) ","))
617
618                        ;; now if we have comma separated bibliographies
619                        ;; we find the one clicked on. we want to
620                        ;; search forward to next comma from point
621                        (save-excursion
622                          (if (search-forward "," link-string-end 1 1)
623                              (setq key-end (- (match-end 0) 1)) ; we found a match
624                            (setq key-end (point)))) ; no comma found so take the point
625                        ;; and backward to previous comma from point
626                        (save-excursion
627                          (if (search-backward "," link-string-beginning 1 1)
628                              (setq key-beginning (+ (match-beginning 0) 1)) ; we found a match
629                            (setq key-beginning (point)))) ; no match found
630                        ;; save the key we clicked on.
631                        (setq bibfile (org-ref-strip-string (buffer-substring key-beginning key-end)))
632                        (find-file bibfile))) ; open file on click
633
634                      ;; formatting code
635                    (lambda (keyword desc format)
636                      (cond
637                       ((eq format 'org) (org-ref-get-org-bibliography))
638                       ((eq format 'ascii) (org-ref-get-ascii-bibliography))
639                       ((eq format 'html) (org-ref-get-html-bibliography))
640                       ((eq format 'latex)
641                        ;; write out the latex bibliography command
642                        (format "\\bibliography{%s}" (replace-regexp-in-string  "\\.bib" "" (mapconcat 'identity
643                                                                                                       (mapcar 'expand-file-name
644                                                                                                               (split-string keyword ","))
645                                                                                                       ",")))))))
646
647 #+END_SRC
648
649 Believe it or not, sometimes it makes sense /not/ to include the bibliography in a document (e.g. when you are required to submit references as a separate file). To generate the references,  in another file, you must make a little tex file with these contents, and then compile it.
650
651 #+BEGIN_LaTeX
652   \input{project-description.bbl}
653 #+END_LaTeX
654
655 Here, we make a =nobibliography= link that acts like the bibliography, enables creation of the bbl file, but does not put an actual bibliography in the file.
656
657 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
658 (org-add-link-type "nobibliography"
659                    ;; this code is run on clicking. The bibliography
660                    ;; may contain multiple files. this code finds the
661                    ;; one you clicked on and opens it.
662                    (lambda (link-string)
663                        ;; get link-string boundaries
664                        ;; we have to go to the beginning of the line, and then search forward
665
666                      (let* ((bibfile)
667                             ;; object is the link you clicked on
668                             (object (org-element-context))
669
670                             (link-string-beginning)
671                             (link-string-end))
672
673                      (save-excursion
674                        (goto-char (org-element-property :begin object))
675                        (search-forward link-string nil nil 1)
676                        (setq link-string-beginning (match-beginning 0))
677                        (setq link-string-end (match-end 0)))
678
679                        ;; We set the reftex-default-bibliography
680                        ;; here. it should be a local variable only in
681                        ;; the current buffer. We need this for using
682                        ;; reftex to do citations.
683                        (set (make-local-variable 'reftex-default-bibliography)
684                             (split-string (org-element-property :path object) ","))
685
686                        ;; now if we have comma separated bibliographies
687                        ;; we find the one clicked on. we want to
688                        ;; search forward to next comma from point
689                        (save-excursion
690                          (if (search-forward "," link-string-end 1 1)
691                              (setq key-end (- (match-end 0) 1)) ; we found a match
692                            (setq key-end (point)))) ; no comma found so take the point
693                        ;; and backward to previous comma from point
694                        (save-excursion
695                          (if (search-backward "," link-string-beginning 1 1)
696                              (setq key-beginning (+ (match-beginning 0) 1)) ; we found a match
697                            (setq key-beginning (point)))) ; no match found
698                        ;; save the key we clicked on.
699                        (setq bibfile (org-ref-strip-string (buffer-substring key-beginning key-end)))
700                        (find-file bibfile))) ; open file on click
701
702                      ;; formatting code
703                    (lambda (keyword desc format)
704                      (cond
705                       ((eq format 'org) (org-ref-get-org-bibliography))
706                       ((eq format 'ascii) (org-ref-get-ascii-bibliography))
707                       ((eq format 'html) (org-ref-get-html-bibliography))
708                       ((eq format 'latex)
709                        ;; write out the latex bibliography command
710
711 ;                      (format "{\\setbox0\\vbox{\\bibliography{%s}}}"
712 ;                              (replace-regexp-in-string  "\\.bib" "" (mapconcat 'identity
713 ;                                                                                (mapcar 'expand-file-name
714 ;                                                                                        (split-string keyword ","))
715 ;                                                                                ",")))
716
717                        (format "\\nobibliography{%s}"
718                                (replace-regexp-in-string  "\\.bib" "" (mapconcat 'identity
719                                                                                  (mapcar 'expand-file-name
720                                                                                          (split-string keyword ","))
721                                                                                  ",")))
722
723                        ))))
724 #+END_SRC
725
726 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
727 (org-add-link-type "printbibliography"
728                    (lambda (arg) (message "Nothing implemented for clicking here."))
729                    (lambda (keyword desc format)
730                      (cond
731                       ((eq format 'org) (org-ref-get-org-bibliography))
732                       ((eq format 'html) (org-ref-get-html-bibliography))
733                       ((eq format 'latex)
734                        ;; write out the biblatex bibliography command
735                        "\\printbibliography"))
736 ))
737 #+END_SRC
738
739 We also create a bibliographystyle link. There is nothing to do on clicking here, and we create it for consistency. This sets the style for latex export, so use something appropriate there, e.g. unsrt, plain, plainnat, ...
740
741 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
742 (org-add-link-type "bibliographystyle"
743                    (lambda (arg) (message "Nothing implemented for clicking here."))
744                    (lambda (keyword desc format)
745                      (cond
746                       ((eq format 'latex)
747                        ;; write out the latex bibliography command
748                        (format "\\bibliographystyle{%s}" keyword)))))
749 #+END_SRC
750
751 *** Completion for bibliography link
752 It would be nice
753
754 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
755 (defun org-bibliography-complete-link (&optional arg)
756  (format "bibliography:%s" (read-file-name "enter file: " nil nil t)))
757
758 (defun org-ref-insert-bibliography-link ()
759   "insert a bibliography with completion"
760   (interactive)
761   (insert (org-bibliography-complete-link)))
762 #+END_SRC
763
764 ** addbibresource
765 This is apparently used for biblatex.
766 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
767 (org-add-link-type "addbibresource"
768                    ;; this code is run on clicking. The addbibresource
769                    ;; may contain multiple files. this code finds the
770                    ;; one you clicked on and opens it.
771                    (lambda (link-string)
772                        ;; get link-string boundaries
773                        ;; we have to go to the beginning of the line, and then search forward
774
775                      (let* ((bibfile)
776                             ;; object is the link you clicked on
777                             (object (org-element-context))
778
779                             (link-string-beginning)
780                             (link-string-end))
781
782                      (save-excursion
783                        (goto-char (org-element-property :begin object))
784                        (search-forward link-string nil nil 1)
785                        (setq link-string-beginning (match-beginning 0))
786                        (setq link-string-end (match-end 0)))
787
788                        ;; We set the reftex-default-addbibresource
789                        ;; here. it should be a local variable only in
790                        ;; the current buffer. We need this for using
791                        ;; reftex to do citations.
792                        (set (make-local-variable 'reftex-default-addbibresource)
793                             (split-string (org-element-property :path object) ","))
794
795                        ;; now if we have comma separated bibliographies
796                        ;; we find the one clicked on. we want to
797                        ;; search forward to next comma from point
798                        (save-excursion
799                          (if (search-forward "," link-string-end 1 1)
800                              (setq key-end (- (match-end 0) 1)) ; we found a match
801                            (setq key-end (point)))) ; no comma found so take the point
802                        ;; and backward to previous comma from point
803                        (save-excursion
804                          (if (search-backward "," link-string-beginning 1 1)
805                              (setq key-beginning (+ (match-beginning 0) 1)) ; we found a match
806                            (setq key-beginning (point)))) ; no match found
807                        ;; save the key we clicked on.
808                        (setq bibfile (org-ref-strip-string (buffer-substring key-beginning key-end)))
809                        (find-file bibfile))) ; open file on click
810
811                      ;; formatting code
812                    (lambda (keyword desc format)
813                      (cond
814                       ((eq format 'html) (format "")); no output for html
815                       ((eq format 'latex)
816                          ;; write out the latex addbibresource command
817                        (format "\\addbibresource{%s}" keyword)))))
818 #+END_SRC
819
820 ** List of Figures
821
822 In long documents, a list of figures is not uncommon. Here we create a clickable link that generates a temporary buffer containing a list of figures in the document, and their captions. We make a function that can be called interactively, and define a link type that is rendered in LaTeX to create the list of figures.
823
824 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
825 (defun org-ref-list-of-figures (&optional arg)
826   "Generate buffer with list of figures in them"
827   (interactive)
828   (save-excursion (widen)
829   (let* ((c-b (buffer-name))
830          (counter 0)
831          (list-of-figures
832           (org-element-map (org-element-parse-buffer) 'link
833             (lambda (link)
834               "create a link for to the figure"
835               (when
836                   (and (string= (org-element-property :type link) "file")
837                        (string-match-p
838                         "[^.]*\\.\\(png\\|jpg\\|eps\\|pdf\\)$"
839                         (org-element-property :path link)))
840                 (incf counter)
841
842                 (let* ((start (org-element-property :begin link))
843                        (parent (car (cdr (org-element-property :parent link))))
844                        (caption (caaar (plist-get parent :caption)))
845                        (name (plist-get parent :name)))
846                   (if caption
847                       (format
848                        "[[elisp:(progn (switch-to-buffer \"%s\")(widen)(goto-char %s))][figure %s: %s]] %s\n"
849                        c-b start counter (or name "") caption)
850                     (format
851                      "[[elisp:(progn (switch-to-buffer \"%s\")(widen)(goto-char %s))][figure %s: %s]]\n"
852                      c-b start counter (or name "")))))))))
853     (switch-to-buffer "*List of Figures*")
854     (setq buffer-read-only nil)
855     (org-mode)
856     (erase-buffer)
857     (insert (mapconcat 'identity list-of-figures ""))
858     (setq buffer-read-only t)
859     (use-local-map (copy-keymap org-mode-map))
860     (local-set-key "q" #'(lambda () (interactive) (kill-buffer))))))
861
862 (org-add-link-type
863  "list-of-figures"
864  'org-ref-list-of-figures ; on click
865  (lambda (keyword desc format)
866    (cond
867     ((eq format 'latex)
868      (format "\\listoffigures")))))
869 #+END_SRC
870
871 ** List of Tables
872
873 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
874 (defun org-ref-list-of-tables (&optional arg)
875   "Generate a buffer with a list of tables"
876   (interactive)
877   (save-excursion
878   (widen)
879   (let* ((c-b (buffer-name))
880          (counter 0)
881          (list-of-tables
882           (org-element-map (org-element-parse-buffer 'element) 'table
883             (lambda (table)
884               "create a link for to the table"
885               (incf counter)
886               (let ((start (org-element-property :begin table))
887                     (name  (org-element-property :name table))
888                     (caption (caaar (org-element-property :caption table))))
889                 (if caption
890                     (format
891                      "[[elisp:(progn (switch-to-buffer \"%s\")(widen)(goto-char %s))][table %s: %s]] %s\n"
892                      c-b start counter (or name "") caption)
893                   (format
894                    "[[elisp:(progn (switch-to-buffer \"%s\")(widen)(goto-char %s))][table %s: %s]]\n"
895                    c-b start counter (or name ""))))))))
896     (switch-to-buffer "*List of Tables*")
897     (setq buffer-read-only nil)
898     (org-mode)
899     (erase-buffer)
900     (insert (mapconcat 'identity list-of-tables ""))
901     (setq buffer-read-only t)
902     (use-local-map (copy-keymap org-mode-map))
903     (local-set-key "q" #'(lambda () (interactive) (kill-buffer))))))
904
905 (org-add-link-type
906  "list-of-tables"
907  'org-ref-list-of-tables
908  (lambda (keyword desc format)
909    (cond
910     ((eq format 'latex)
911      (format "\\listoftables")))))
912 #+END_SRC
913 ** label
914
915 The label link provides a way to create labels in org-mode. We make it clickable because we want to make sure labels are unique. This code will tell you how many instances of a label are found.  We search for label links, LaTeX labels, and org-mode format for labels, tblnames too.
916
917 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
918 (defun org-ref-count-labels (label)
919   "Counts number of matches for label in the document"
920   (+ (count-matches (format "label:%s\\b[^-:]" label) (point-min) (point-max) t)
921      ;; for tblname, it is not enough to get word boundary
922      ;; tab-little and tab-little-2 match then.
923      (count-matches (format "^#\\+tblname:\\s-*%s\\b[^-:]" label) (point-min) (point-max) t)
924      (count-matches (format "\\label{%s}\\b" label) (point-min) (point-max) t)
925      ;; this is the org-format #+label:
926      (count-matches (format "^#\\+label:\\s-*%s\\b[^-:]" label) (point-min) (point-max) t)
927      (let ((custom-id-count 0))
928        (org-map-entries
929         (lambda ()
930           (when (string= label  (org-entry-get (point) "CUSTOM_ID"))
931             (setq custom-id-count (+ 1 custom-id-count)))))
932        custom-id-count)))
933
934 (org-add-link-type
935  "label"
936  (lambda (label)
937    "on clicking count the number of label tags used in the buffer. A number greater than one means multiple labels!"
938    (message (format "%s occurences" (org-ref-count-labels label))))
939  (lambda (keyword desc format)
940    (cond
941     ((eq format 'html) (format "(<label>%s</label>)" path))
942     ((eq format 'latex)
943      (format "\\label{%s}" keyword)))))
944 #+END_SRC
945
946 We want to store links on labels, so you can put the cursor on the label, press C-c l, and later use C-c C-l to insert a link to the label. We also want to store links to tables with a table name, and for sections with CUSTOM_ID.
947
948 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
949 (defun org-label-store-link ()
950   "store a link to a label. The output will be a ref to that label"
951   ;; First we have to make sure we are on a label link.
952   (let* ((object (org-element-context)))
953     (when (and (equal (org-element-type object) 'link)
954                (equal (org-element-property :type object) "label"))
955       (org-store-link-props
956        :type "ref"
957        :link (concat "ref:" (org-element-property :path object))))
958
959     ;; Store link on table
960     (when (equal (org-element-type object) 'table)
961       (org-store-link-props
962        :type "ref"
963        :link (concat "ref:" (org-element-property :name object))))
964
965 ;; it turns out this does not work. you can already store a link to a heading with a CUSTOM_ID
966     ;; store link on heading with custom_id
967 ;    (when (and (equal (org-element-type object) 'headline)
968 ;              (org-entry-get (point) "CUSTOM_ID"))
969 ;      (org-store-link-props
970 ;       :type "ref"
971 ;       :link (concat "ref:" (org-entry-get (point) "CUSTOM_ID"))))
972
973     ;; and to #+label: lines
974     (when (and (equal (org-element-type object) 'paragraph)
975                (org-element-property :name object))
976       (org-store-link-props
977        :type "ref"
978        :link (concat "ref:" (org-element-property :name object))))
979 ))
980
981 (add-hook 'org-store-link-functions 'org-label-store-link)
982 #+END_SRC
983 ** ref
984
985 The ref link allows you make links to labels. Clicking on the link takes you to the label, and provides a mark to go back to.
986
987 At the moment, ref links are not usable for section links. You need [[#CUSTOM_ID]] type links.
988
989 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
990 (org-add-link-type
991  "ref"
992  (lambda (label)
993    "on clicking goto the label. Navigate back with C-c &"
994    (org-mark-ring-push)
995    ;; next search from beginning of the buffer
996
997    ;; it is possible you would not find the label if narrowing is in effect
998    (widen)
999
1000    (unless
1001        (or
1002         ;; our label links
1003         (progn
1004           (goto-char (point-min))
1005           (re-search-forward (format "label:%s\\b" label) nil t))
1006
1007         ;; a latex label
1008         (progn
1009           (goto-char (point-min))
1010           (re-search-forward (format "\\label{%s}" label) nil t))
1011
1012         ;; #+label: name  org-definition
1013         (progn
1014           (goto-char (point-min))
1015           (re-search-forward (format "^#\\+label:\\s-*\\(%s\\)\\b" label) nil t))
1016
1017         ;; org tblname
1018         (progn
1019           (goto-char (point-min))
1020           (re-search-forward (format "^#\\+tblname:\\s-*\\(%s\\)\\b" label) nil t))
1021
1022 ;; Commented out because these ref links do not actually translate correctly in LaTeX.
1023 ;; you need [[#label]] links.
1024         ;; CUSTOM_ID
1025 ;       (progn
1026 ;         (goto-char (point-min))
1027 ;         (re-search-forward (format ":CUSTOM_ID:\s-*\\(%s\\)" label) nil t))
1028         )
1029      ;; we did not find anything, so go back to where we came
1030      (org-mark-ring-goto)
1031      (error "%s not found" label))
1032    (org-show-entry)
1033    (message "go back with (org-mark-ring-goto) `C-c &`"))
1034  ;formatting
1035  (lambda (keyword desc format)
1036    (cond
1037     ((eq format 'html) (format "(<ref>%s</ref>)" path))
1038     ((eq format 'latex)
1039      (format "\\ref{%s}" keyword)))))
1040 #+END_SRC
1041
1042 It would be nice to use completion to enter a ref link, where a list of labels is provided. The following code searches the buffer for org and latex labels, custom_ids, and table names as potential items to make a ref link to.
1043
1044 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1045 (defun org-ref-get-org-labels ()
1046  "find #+LABEL: labels"
1047   (save-excursion
1048     (goto-char (point-min))
1049     (let ((matches '()))
1050       (while (re-search-forward "^#\\+label:\\s-+\\(.*\\)\\b" (point-max) t)
1051         (add-to-list 'matches (match-string-no-properties 1) t))
1052 matches)))
1053 #+END_SRC
1054
1055 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1056 (defun org-ref-get-custom-ids ()
1057  "return a list of custom_id properties in the buffer"
1058  (let ((results '()) custom_id)
1059    (org-map-entries
1060     (lambda ()
1061       (let ((custom_id (org-entry-get (point) "CUSTOM_ID")))
1062         (when (not (null custom_id))
1063           (setq results (append results (list custom_id)))))))
1064 results))
1065 #+END_SRC
1066
1067 Here we get a list of the labels defined as raw latex labels, e.g. \label{eqtre}.
1068 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1069 (defun org-ref-get-latex-labels ()
1070   (save-excursion
1071     (goto-char (point-min))
1072     (let ((matches '()))
1073       (while (re-search-forward "\\\\label{\\([a-zA-z0-9:-]*\\)}" (point-max) t)
1074         (add-to-list 'matches (match-string-no-properties 1) t))
1075 matches)))
1076 #+END_SRC
1077
1078 Finally, we get the table names.
1079
1080 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1081 (defun org-ref-get-tblnames ()
1082   (org-element-map (org-element-parse-buffer 'element) 'table
1083     (lambda (table)
1084       (org-element-property :name table))))
1085 #+END_SRC
1086
1087 Now, we can put all the labels together which will give us a list of candidates.
1088
1089 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1090 (defun org-ref-get-labels ()
1091   "returns a list of labels in the buffer that you can make a ref link to. this is used to auto-complete ref links."
1092   (save-excursion
1093     (save-restriction
1094       (widen)
1095       (goto-char (point-min))
1096       (let ((matches '()))
1097         (while (re-search-forward "label:\\([a-zA-z0-9:-]*\\)" (point-max) t)
1098           (add-to-list 'matches (match-string-no-properties 1) t))
1099         (append matches (org-ref-get-org-labels) (org-ref-get-latex-labels) (org-ref-get-tblnames) (org-ref-get-custom-ids))))))
1100 #+END_SRC
1101
1102 Let us make a helm function to insert a label link. This will help you enter unique labels.
1103 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1104 (defun org-ref-helm-insert-label-link ()
1105   "Insert a label link. helm just shows you what labels already exist."
1106   (interactive)
1107   (let* ((labels (org-ref-get-labels))
1108          (cb (current-buffer)))
1109     (helm :sources `(((name . "Existing labels")
1110                       (candidates . ,labels)
1111                       (action . (lambda (label)
1112                                   ;; unfortunately I do not have markers here
1113                                   (org-open-link-from-string (format "ref:%s" label)))))
1114                      ((name . "Create new label")
1115                       (dummy)
1116                       (action .  (lambda (label)
1117                                    (switch-to-buffer ,cb)
1118                                    (insert
1119                                     (concat
1120                                      "label:"
1121                                      (or label
1122                                          helm-pattern))))))))))
1123 #+END_SRC
1124
1125 Now we create the completion function. This works from the org-machinery, e.g. if you type C-c C-l to insert a link, and use completion by pressing tab.
1126
1127 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1128 (defun org-ref-complete-link (&optional arg)
1129   "Completion function for ref links"
1130   (let ((label))
1131     (setq label (completing-read "label: " (org-ref-get-labels)))
1132     (format "ref:%s" label)))
1133 #+END_SRC
1134
1135 Alternatively, you may want to just call a function that inserts a link with completion:
1136
1137 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1138 (defun org-ref-insert-ref-link ()
1139  (interactive)
1140  (insert (org-ref-complete-link)))
1141 #+END_SRC
1142
1143 Another alternative ref insertion is to use helm.
1144
1145 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1146 (defun org-ref-helm-insert-ref-link ()
1147   "Helm menu to insert ref links to labels in the document.
1148 Use C-u to insert a different kind of ref link.
1149 C-u C-u to replace the current ref with selection"
1150   (interactive)
1151   (let* ((labels (org-ref-get-labels))
1152          (contexts (mapcar 'org-ref-get-label-context labels))
1153          (cb (current-buffer)))
1154
1155     (helm :sources `(((name . "Available labels to ref")
1156                       (candidates . ,(loop for label in labels
1157                                            for context in contexts
1158 ;; we do some kludgy adding spaces and bars to make it "easier" to see in helm.
1159                                            collect (cons (concat
1160                                                           label "\n"
1161                                                           (mapconcat
1162                                                            (lambda (x)
1163                                                              (concat "   |" x))
1164                                                            (split-string context "\n")
1165                                                            "\n"
1166                                                            ) "\n\n") label)))
1167                       (action . (lambda (label)
1168                                   (switch-to-buffer ,cb)
1169
1170                                   (cond
1171                                    ;;  no prefix
1172                                    ((equal helm-current-prefix-arg nil)
1173                                      (insert
1174                                       (concat
1175                                        "ref:" label)))
1176                                    ;; one prefix, alternate ref link
1177                                    ((equal helm-current-prefix-arg '(4))
1178                                     (insert
1179                                      (concat
1180                                       (helm :sources '((name . "Ref link types")
1181                                                        (candidates . ("ref" "eqref" "pageref" "nameref"))
1182                                                        (action . (lambda (x) x))))
1183                                       ":" label)))
1184                                    ;; two prefixes, replace current label
1185                                    ((equal helm-current-prefix-arg '(16))
1186                                     ;; get link
1187                                     (let* ((object (org-element-context))
1188                                            (last-char (save-excursion
1189                                                         (goto-char (org-element-property :end object))
1190                                                         (backward-char)
1191                                                         (if (looking-at " ")
1192                                                             " "
1193                                                           ""))))
1194                                       (setf
1195                                        (buffer-substring
1196                                         (org-element-property :begin object)
1197                                         (org-element-property :end object))
1198                                        (concat
1199                                         (replace-regexp-in-string
1200                                          (org-element-property :path object)
1201                                          label
1202                                          (org-element-property :raw-link object))
1203                                         last-char))))))))))))
1204
1205
1206
1207 #+END_SRC
1208
1209 #+RESULTS:
1210 : org-ref-helm-insert-ref-link
1211
1212 ** pageref
1213
1214 This refers to the page of a label in LaTeX.
1215
1216 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1217 (org-add-link-type
1218  "pageref"
1219  (lambda (label)
1220    "on clicking goto the label. Navigate back with C-c &"
1221    (org-mark-ring-push)
1222    ;; next search from beginning of the buffer
1223    (widen)
1224    (unless
1225        (or
1226         ;; our label links
1227         (progn
1228           (goto-char (point-min))
1229           (re-search-forward (format "label:%s\\b" label) nil t))
1230
1231         ;; a latex label
1232         (progn
1233           (goto-char (point-min))
1234           (re-search-forward (format "\\label{%s}" label) nil t))
1235
1236         ;; #+label: name  org-definition
1237         (progn
1238           (goto-char (point-min))
1239           (re-search-forward (format "^#\\+label:\\s-*\\(%s\\)\\b" label) nil t))
1240
1241         ;; org tblname
1242         (progn
1243           (goto-char (point-min))
1244           (re-search-forward (format "^#\\+tblname:\\s-*\\(%s\\)\\b" label) nil t))
1245
1246 ;; Commented out because these ref links do not actually translate correctly in LaTeX.
1247 ;; you need [[#label]] links.
1248         ;; CUSTOM_ID
1249 ;       (progn
1250 ;         (goto-char (point-min))
1251 ;         (re-search-forward (format ":CUSTOM_ID:\s-*\\(%s\\)" label) nil t))
1252         )
1253      ;; we did not find anything, so go back to where we came
1254      (org-mark-ring-goto)
1255      (error "%s not found" label))
1256    (message "go back with (org-mark-ring-goto) `C-c &`"))
1257  ;formatting
1258  (lambda (keyword desc format)
1259    (cond
1260     ((eq format 'html) (format "(<pageref>%s</pageref>)" path))
1261     ((eq format 'latex)
1262      (format "\\pageref{%s}" keyword)))))
1263 #+END_SRC
1264
1265 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1266 (defun org-pageref-complete-link (&optional arg)
1267   "Completion function for ref links"
1268   (let ((label))
1269     (setq label (completing-read "label: " (org-ref-get-labels)))
1270     (format "ref:%s" label)))
1271 #+END_SRC
1272
1273 Alternatively, you may want to just call a function that inserts a link with completion:
1274
1275 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1276 (defun org-pageref-insert-ref-link ()
1277  (interactive)
1278  (insert (org-pageref-complete-link)))
1279 #+END_SRC
1280
1281 ** nameref
1282
1283 The nameref link allows you make links to the text of a section with a label. Clicking on the link takes you to the label, and provides a mark to go back to. This only works if you put a raw latex label in the headline.
1284
1285 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1286 (org-add-link-type
1287  "nameref"
1288  (lambda (label)
1289    "on clicking goto the label. Navigate back with C-c &"
1290    (org-mark-ring-push)
1291    ;; next search from beginning of the buffer
1292    (widen)
1293    (unless
1294        (or
1295         ;; a latex label
1296         (progn
1297           (goto-char (point-min))
1298           (re-search-forward (format "\\label{%s}" label) nil t))
1299         )
1300      ;; we did not find anything, so go back to where we came
1301      (org-mark-ring-goto)
1302      (error "%s not found" label))
1303    (message "go back with (org-mark-ring-goto) `C-c &`"))
1304  ;formatting
1305  (lambda (keyword desc format)
1306    (cond
1307     ((eq format 'html) (format "(<nameref>%s</nameref>)" path))
1308     ((eq format 'latex)
1309      (format "\\nameref{%s}" keyword)))))
1310 #+END_SRC
1311
1312 ** eqref
1313 This is just the LaTeX ref for equations. On export, the reference is enclosed in parentheses.
1314
1315 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1316 (org-add-link-type
1317  "eqref"
1318  (lambda (label)
1319    "on clicking goto the label. Navigate back with C-c &"
1320    (org-mark-ring-push)
1321    ;; next search from beginning of the buffer
1322    (widen)
1323    (goto-char (point-min))
1324    (unless
1325        (or
1326         ;; search forward for the first match
1327         ;; our label links
1328         (re-search-forward (format "label:%s" label) nil t)
1329         ;; a latex label
1330         (re-search-forward (format "\\label{%s}" label) nil t)
1331         ;; #+label: name  org-definition
1332         (re-search-forward (format "^#\\+label:\\s-*\\(%s\\)\\b" label) nil t))
1333      (org-mark-ring-goto)
1334      (error "%s not found" label))
1335    (message "go back with (org-mark-ring-goto) `C-c &`"))
1336  ;formatting
1337  (lambda (keyword desc format)
1338    (cond
1339     ((eq format 'html) (format "(<eqref>%s</eqref>)" path))
1340     ((eq format 'latex)
1341      (format "\\eqref{%s}" keyword)))))
1342 #+END_SRC
1343
1344 ** cite
1345 This is the main reason this library exists. We want the following behavior. A cite link should be able to contain multiple bibtex keys. You should be able to click on the link, and get a brief citation of the entry for that key, and a menu of options to open the bibtex file, open a pdf if you have it, open your notes on the entry, or open a url if it exists. You should be able to insert new references onto an existing cite link, or create new ones easily. The following code implements these features.
1346
1347 *** Implementing the click actions of cite
1348
1349 **** Getting the key we clicked on
1350 The first thing we need is to get the bibtex key we clicked on.
1351
1352 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1353 (defun org-ref-get-bibtex-key-under-cursor ()
1354   "returns key under the bibtex cursor. We search forward from
1355 point to get a comma, or the end of the link, and then backwards
1356 to get a comma, or the beginning of the link. that delimits the
1357 keyword we clicked on. We also strip the text properties."
1358   (interactive)
1359   (let* ((object (org-element-context))
1360          (link-string (org-element-property :path object)))
1361     ;; you may click on the part before the citations. here we make
1362     ;; sure to move to the beginning so you get the first citation.
1363     (let ((cp (point)))
1364       (goto-char (org-element-property :begin object))
1365       (search-forward link-string (org-element-property :end object))
1366       (goto-char (match-beginning 0))
1367       ;; check if we clicked before the path and move as needed.
1368       (unless (< cp (point))
1369         (goto-char cp)))
1370
1371     (if (not (org-element-property :contents-begin object))
1372         ;; this means no description in the link
1373         (progn
1374           ;; we need the link path start and end
1375           (save-excursion
1376             (goto-char (org-element-property :begin object))
1377             (search-forward link-string nil nil 1)
1378             (setq link-string-beginning (match-beginning 0))
1379             (setq link-string-end (match-end 0)))
1380
1381           ;; The key is the text between commas, or the link boundaries
1382           (save-excursion
1383             (if (search-forward "," link-string-end t 1)
1384                 (setq key-end (- (match-end 0) 1)) ; we found a match
1385               (setq key-end link-string-end))) ; no comma found so take the end
1386           ;; and backward to previous comma from point which defines the start character
1387           (save-excursion
1388             (if (search-backward "," link-string-beginning 1 1)
1389                 (setq key-beginning (+ (match-beginning 0) 1)) ; we found a match
1390               (setq key-beginning link-string-beginning))) ; no match found
1391           ;; save the key we clicked on.
1392           (setq bibtex-key (org-ref-strip-string (buffer-substring key-beginning key-end)))
1393           (set-text-properties 0 (length bibtex-key) nil bibtex-key)
1394           bibtex-key)
1395       ;; link with description. assume only one key
1396       link-string)))
1397 #+END_SRC
1398
1399 We also need to find which bibliography file that key is in. For that, we need to know which bibliography files are referred to in the file. If none are specified with a bibliography link, we use the default bibliography. This function searches for a bibliography link, and then the LaTeX bibliography link. We also consider the addbibresource link which is used with biblatex.
1400
1401 **** Getting the bibliographies
1402 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1403 (defun org-ref-find-bibliography ()
1404   "find the bibliography in the buffer.
1405 This function sets and returns cite-bibliography-files, which is a list of files
1406 either from bibliography:f1.bib,f2.bib
1407 \bibliography{f1,f2}
1408 internal bibliographies
1409
1410 falling back to what the user has set in org-ref-default-bibliography
1411 "
1412   (interactive)
1413   (catch 'result
1414     (save-excursion
1415       (goto-char (point-min))
1416       ;;  look for a bibliography link
1417       (when (re-search-forward "\\<bibliography:\\([^\]\|\n]+\\)" nil t)
1418         (setq org-ref-bibliography-files
1419               (mapcar 'org-ref-strip-string (split-string (match-string 1) ",")))
1420         (throw 'result org-ref-bibliography-files))
1421
1422
1423       ;; we did not find a bibliography link. now look for \bibliography
1424       (goto-char (point-min))
1425       (when (re-search-forward "\\\\bibliography{\\([^}]+\\)}" nil t)
1426         ;; split, and add .bib to each file
1427         (setq org-ref-bibliography-files
1428               (mapcar (lambda (x) (concat x ".bib"))
1429                       (mapcar 'org-ref-strip-string
1430                               (split-string (match-string 1) ","))))
1431         (throw 'result org-ref-bibliography-files))
1432
1433       ;; no bibliography found. maybe we need a biblatex addbibresource
1434       (goto-char (point-min))
1435       ;;  look for a bibliography link
1436       (when (re-search-forward "addbibresource:\\([^\]\|\n]+\\)" nil t)
1437         (setq org-ref-bibliography-files
1438               (mapcar 'org-ref-strip-string (split-string (match-string 1) ",")))
1439         (throw 'result org-ref-bibliography-files))
1440
1441       ;; we did not find anything. use defaults
1442       (setq org-ref-bibliography-files org-ref-default-bibliography)))
1443
1444     ;; set reftex-default-bibliography so we can search
1445     (set (make-local-variable 'reftex-default-bibliography) org-ref-bibliography-files)
1446     org-ref-bibliography-files)
1447 #+END_SRC
1448
1449 **** Finding the bibliography file a key is in
1450 Now, we can see if an entry is in a file.
1451
1452 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1453 (defun org-ref-key-in-file-p (key filename)
1454   "determine if the key is in the file"
1455   (interactive "skey: \nsFile: ")
1456   (save-current-buffer
1457     (let ((bibtex-files (list filename)))
1458       (bibtex-search-entry key t))))
1459 #+END_SRC
1460
1461 Finally, we want to know which file the key is in.
1462
1463 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1464 (defun org-ref-get-bibtex-key-and-file (&optional key)
1465   "returns the bibtex key and file that it is in. If no key is provided, get one under point"
1466  (interactive)
1467  (let ((org-ref-bibliography-files (org-ref-find-bibliography))
1468        (file))
1469    (unless key
1470      (setq key (org-ref-get-bibtex-key-under-cursor)))
1471    (setq file     (catch 'result
1472                     (loop for file in org-ref-bibliography-files do
1473                           (if (org-ref-key-in-file-p key (file-truename file))
1474                               (throw 'result file)))))
1475    (cons key file)))
1476 #+END_SRC
1477
1478 **** convenience functions to act on citation at point
1479      :PROPERTIES:
1480      :ID:       af0b2a82-a7c9-4c08-9dac-09f93abc4a92
1481      :END:
1482 We need some convenience functions to open act on the citation at point. These will get the pdf, open the url, or open the notes.
1483
1484 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1485 (defun org-ref-open-pdf-at-point ()
1486   "open the pdf for bibtex key under point if it exists"
1487   (interactive)
1488   (let* ((results (org-ref-get-bibtex-key-and-file))
1489          (key (car results))
1490          (pdf-file (format (concat org-ref-pdf-directory "%s.pdf") key)))
1491     (if (file-exists-p pdf-file)
1492         (org-open-file pdf-file)
1493 (message "no pdf found for %s" key))))
1494
1495
1496 (defun org-ref-open-url-at-point ()
1497   "open the url for bibtex key under point."
1498   (interactive)
1499   (let* ((results (org-ref-get-bibtex-key-and-file))
1500          (key (car results))
1501          (bibfile (cdr results)))
1502     (save-excursion
1503       (with-temp-buffer
1504         (insert-file-contents bibfile)
1505         (bibtex-search-entry key)
1506         ;; I like this better than bibtex-url which does not always find
1507         ;; the urls
1508         (catch 'done
1509           (let ((url (bibtex-autokey-get-field "url")))
1510             (when  url
1511               (browse-url url)
1512               (throw 'done nil)))
1513
1514           (let ((doi (bibtex-autokey-get-field "doi")))
1515             (when doi
1516               (if (string-match "^http" doi)
1517                   (browse-url doi)
1518                 (browse-url (format "http://dx.doi.org/%s" doi)))
1519               (throw 'done nil))))))))
1520
1521
1522 (defun org-ref-open-notes-at-point ()
1523   "open the notes for bibtex key under point."
1524   (interactive)
1525   (let* ((results (org-ref-get-bibtex-key-and-file))
1526          (key (car results))
1527          (bibfile (cdr results)))
1528     (save-excursion
1529       (with-temp-buffer
1530         (insert-file-contents bibfile)
1531         (bibtex-search-entry key)
1532         (org-ref-open-bibtex-notes)))))
1533
1534
1535 (defun org-ref-citation-at-point ()
1536   "give message of current citation at point"
1537   (interactive)
1538   (let* ((cb (current-buffer))
1539         (results (org-ref-get-bibtex-key-and-file))
1540         (key (car results))
1541         (bibfile (cdr results)))
1542     (message "%s" (progn
1543                     (with-temp-buffer
1544                       (insert-file-contents bibfile)
1545                       (bibtex-search-entry key)
1546                       (org-ref-bib-citation))))))
1547
1548
1549 (defun org-ref-open-citation-at-point ()
1550   "open bibtex file to key at point"
1551   (interactive)
1552   (let* ((cb (current-buffer))
1553         (results (org-ref-get-bibtex-key-and-file))
1554         (key (car results))
1555         (bibfile (cdr results)))
1556     (find-file bibfile)
1557     (bibtex-search-entry key)))
1558 #+END_SRC
1559
1560 **** the actual minibuffer menu
1561 Now, we create the menu. This is a rewrite of the cite action. This makes the function extendable by users.
1562
1563 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1564 (defvar org-ref-cite-menu-funcs '()
1565  "Functions to run on cite click menu. Each entry is a list of (key menu-name function).
1566 The function must take no arguments and work on the key at point. Do not modify this variable, it is set to empty in the menu click function, and functions are conditionally added to it.")
1567
1568
1569 (defvar org-ref-user-cite-menu-funcs
1570   '(("C" "rossref" org-ref-crossref-at-point)
1571     ("y" "Copy entry to file" org-ref-copy-entry-at-point-to-file)
1572     ("s" "Copy summary" org-ref-copy-entry-as-summary))
1573   "user-defined functions to run on bibtex key at point.")
1574
1575
1576 (defun org-ref-copy-entry-as-summary ()
1577   "Copy the bibtex entry for the citation at point as a summary."
1578   (interactive)
1579     (save-window-excursion
1580       (org-ref-open-citation-at-point)
1581       (kill-new (org-ref-bib-citation))))
1582
1583
1584 (defun org-ref-copy-entry-at-point-to-file ()
1585   "Copy the bibtex entry for the citation at point to NEW-FILE.
1586 Prompt for NEW-FILE includes bib files in org-ref-default-bibliography, and bib files in current working directory. You can also specify a new file."
1587   (interactive)
1588   (let ((new-file (ido-completing-read
1589                    "Copy to bibfile: "
1590                    (append org-ref-default-bibliography
1591                            (f-entries "." (lambda (f) (f-ext? f "bib"))))))
1592         (key (org-ref-get-bibtex-key-under-cursor)))
1593     (save-window-excursion
1594       (org-ref-open-citation-at-point)
1595       (bibtex-copy-entry-as-kill))
1596
1597     (let ((bibtex-files (list (file-truename new-file))))
1598       (if (assoc key (bibtex-global-key-alist))
1599           (message "That key already exists in %s" new-file)
1600         ;; add to file
1601         (save-window-excursion
1602           (find-file new-file)
1603           (goto-char (point-max))
1604           ;; make sure we are at the beginning of a line.
1605           (unless (looking-at "^") (insert "\n\n"))
1606           (bibtex-yank)
1607           (save-buffer))))))
1608
1609
1610 (defun org-ref-get-doi-at-point ()
1611   "Get doi for key at point."
1612   (interactive)
1613   (let* ((results (org-ref-get-bibtex-key-and-file))
1614          (key (car results))
1615          (bibfile (cdr results))
1616          doi)
1617     (save-excursion
1618       (with-temp-buffer
1619         (insert-file-contents bibfile)
1620         (bibtex-search-entry key)
1621         (setq doi (bibtex-autokey-get-field "doi"))
1622         ;; in case doi is a url, remove the url part.
1623         (replace-regexp-in-string "^http://dx.doi.org/" "" doi)))))
1624
1625
1626 ;; functions that operate on key at point for click menu
1627 (defun org-ref-wos-at-point ()
1628   "open the doi in wos for bibtex key under point."
1629   (interactive)
1630   (doi-utils-wos (org-ref-get-doi-at-point)))
1631
1632
1633 (defun org-ref-wos-citing-at-point ()
1634   "open the doi in wos citing articles for bibtex key under point."
1635   (interactive)
1636   (doi-utils-wos-citing (org-ref-get-doi-at-point)))
1637
1638
1639 (defun org-ref-wos-related-at-point ()
1640   "open the doi in wos related articles for bibtex key under point."
1641   (interactive)
1642   (doi-utils-wos-related (org-ref-get-doi-at-point)))
1643
1644
1645 (defun org-ref-google-scholar-at-point ()
1646   "open the doi in google scholar for bibtex key under point."
1647   (interactive)
1648   (doi-utils-google-scholar (org-ref-get-doi-at-point)))
1649
1650
1651 (defun org-ref-pubmed-at-point ()
1652   "open the doi in pubmed for bibtex key under point."
1653   (interactive)
1654   (doi-utils-pubmed (org-ref-get-doi-at-point)))
1655
1656
1657 (defun org-ref-crossref-at-point ()
1658   "open the doi in crossref for bibtex key under point."
1659   (interactive)
1660   (doi-utils-crossref (org-ref-get-doi-at-point)))
1661
1662
1663 (defun org-ref-cite-onclick-minibuffer-menu (&optional link-string)
1664   "action when a cite link is clicked on.
1665 Provides a menu of context sensitive actions. If the bibtex entry has a pdf, you get an option to open it. If there is a doi, you get a lot of options."
1666   (interactive)
1667   (let* ((results (org-ref-get-bibtex-key-and-file))
1668          (key (car results))
1669          (pdf-file (format (concat org-ref-pdf-directory "%s.pdf") key))
1670          (bibfile (cdr results))
1671          (url (save-excursion
1672                 (with-temp-buffer
1673                   (insert-file-contents bibfile)
1674                   (bibtex-search-entry key)
1675                   (bibtex-autokey-get-field "url"))))
1676          (doi (save-excursion
1677                 (with-temp-buffer
1678                   (insert-file-contents bibfile)
1679                   (bibtex-search-entry key)
1680                   ;; I like this better than bibtex-url which does not always find
1681                   ;; the urls
1682                   (bibtex-autokey-get-field "doi")))))
1683
1684     (when (string= "" doi) (setq doi nil))
1685     (when (string= "" url) (setq url nil))
1686     (setq org-ref-cite-menu-funcs '())
1687
1688     ;; open action
1689     (when
1690         bibfile
1691       (add-to-list
1692        'org-ref-cite-menu-funcs
1693        '("o" "pen" org-ref-open-citation-at-point)))
1694
1695     ;; pdf
1696     (when (file-exists-p pdf-file)
1697       (add-to-list
1698        'org-ref-cite-menu-funcs
1699        `("p" "df" ,org-ref-open-pdf-function) t))
1700
1701     ;; notes
1702     (add-to-list
1703      'org-ref-cite-menu-funcs
1704      '("n" "otes" org-ref-open-notes-at-point) t)
1705
1706     ;; url
1707     (when (or url doi)
1708       (add-to-list
1709        'org-ref-cite-menu-funcs
1710        '("u" "rl" org-ref-open-url-at-point) t))
1711
1712     ;; doi funcs
1713     (when doi
1714       (add-to-list
1715        'org-ref-cite-menu-funcs
1716        '("w" "os" org-ref-wos-at-point) t)
1717
1718       (add-to-list
1719        'org-ref-cite-menu-funcs
1720        '("c" "iting" org-ref-wos-citing-at-point) t)
1721
1722       (add-to-list
1723        'org-ref-cite-menu-funcs
1724        '("r" "elated" org-ref-wos-related-at-point) t)
1725
1726       (add-to-list
1727        'org-ref-cite-menu-funcs
1728        '("g" "oogle scholar" org-ref-google-scholar-at-point) t)
1729
1730       (add-to-list
1731        'org-ref-cite-menu-funcs
1732        '("P" "ubmed" org-ref-pubmed-at-point) t))
1733
1734     ;; add user functions
1735     (dolist (tup org-ref-user-cite-menu-funcs)
1736       (add-to-list
1737        'org-ref-cite-menu-funcs
1738        tup t))
1739
1740     ;; finally quit
1741     (add-to-list
1742      'org-ref-cite-menu-funcs
1743      '("q" "uit" (lambda ())) t)
1744
1745     ;; now we make a menu
1746     ;; construct menu string as a message
1747     (message
1748      (concat
1749       (let* ((results (org-ref-get-bibtex-key-and-file))
1750              (key (car results))
1751              (bibfile (cdr results)))
1752         (save-excursion
1753           (with-temp-buffer
1754             (insert-file-contents bibfile)
1755             (bibtex-search-entry key)
1756             (org-ref-bib-citation))))
1757       "\n"
1758       (mapconcat
1759        (lambda (tup)
1760          (concat "[" (elt tup 0) "]"
1761                  (elt tup 1) " "))
1762        org-ref-cite-menu-funcs "")))
1763     ;; get the input
1764     (let* ((input (read-char-exclusive))
1765            (choice (assoc
1766                     (char-to-string input) org-ref-cite-menu-funcs)))
1767       ;; now run the function (2nd element in choice)
1768       (when choice
1769         (funcall
1770          (elt
1771           choice
1772           2))))))
1773 #+END_SRC
1774
1775 #+RESULTS:
1776 : org-ref-cite-onclick-minibuffer-menu
1777
1778 *** A function to format a cite link
1779
1780 Next, we define a formatting function for the cite link. This is done so that the cite link definition is very short, and easy to change. You just need to specify the functions in the definition. This function is deprecated. The formatting is defined later automatically.
1781
1782 #+BEGIN_SRC emacs-lisp  :tangle no
1783 ;(defun org-ref-cite-link-format (keyword desc format)
1784 ;   (cond
1785 ;    ((eq format 'html) (mapconcat (lambda (key) (format "<a name=\"#%s\">%s</a>" key key) (org-ref-split-and-strip-string keyword) ",")))
1786 ;    ((eq format 'latex)
1787 ;     (concat "\\cite" (when desc (format "[%s]" desc)) "{"
1788 ;            (mapconcat (lambda (key) key) (org-ref-split-and-strip-string keyword) ",")
1789 ;            "}"))))
1790 #+END_SRC
1791
1792 *** The actual cite link
1793 Finally, we define the cite link. This is deprecated; the links are autogenerated later. This is here for memory.
1794
1795 #+BEGIN_SRC emacs-lisp :tangle no
1796 ;(org-add-link-type
1797 ; "cite"
1798 ; 'org-ref-cite-onclick-minibuffer-menu
1799 ; 'org-ref-cite-link-format)
1800 #+END_SRC
1801
1802 *** Automatic definition of the cite links
1803 There are many different kinds of citations in LaTeX, but they are all variants of a basic syntax of \citetype[optional text]{label1,label2}. Here we use lisp to generate the link definitions. We define a function that creates the code to create the link, and then we evaluate it. We also create the completion function for the new link, and add it to the list of known links.
1804
1805 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1806 (defmacro org-ref-make-completion-function (type)
1807   `(defun ,(intern (format "org-%s-complete-link" type)) (&optional arg)
1808      (interactive)
1809      (format "%s:%s"
1810              ,type
1811              (completing-read
1812               "bibtex key: "
1813               (let ((bibtex-files (org-ref-find-bibliography)))
1814                 (bibtex-global-key-alist))))))
1815 #+END_SRC
1816
1817 We will want to generate formatting functions for each citation type. The reason for doing this is so we can on the fly change the formatting later.
1818
1819 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1820 (defmacro org-ref-make-format-function (type)
1821   `(defun ,(intern (format "org-ref-format-%s" type)) (keyword desc format)
1822      (cond
1823       ((eq format 'org)
1824        (mapconcat
1825         (lambda (key)
1826           (format "[[#%s][%s]]" key key))
1827         (org-ref-split-and-strip-string keyword) ","))
1828
1829       ((eq format 'ascii)
1830        (concat "["
1831                (mapconcat
1832                 (lambda (key)
1833                   (format "%s" key))
1834                 (org-ref-split-and-strip-string keyword) ",") "]"))
1835
1836       ((eq format 'html)
1837        (mapconcat
1838         (lambda (key)
1839           (format "<a href=\"#%s\">%s</a>" key key))
1840         (org-ref-split-and-strip-string keyword) ","))
1841
1842       ((eq format 'latex)
1843        (if (string= (substring type -1) "s")
1844            ;; biblatex format for multicite commands, which all end in s. These are formated as \cites{key1}{key2}...
1845            (concat "\\" ,type (mapconcat (lambda (key) (format "{%s}"  key))
1846                                          (org-ref-split-and-strip-string keyword) ""))
1847          ;; bibtex format
1848        (concat "\\" ,type (when desc (org-ref-format-citation-description desc)) "{"
1849                (mapconcat (lambda (key) key) (org-ref-split-and-strip-string keyword) ",")
1850                "}"))))))
1851 #+END_SRC
1852
1853
1854
1855 We create the links by mapping the function onto the list of defined link types.
1856
1857 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1858 (defun org-ref-format-citation-description (desc)
1859   "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 ::."
1860   (interactive)
1861   (cond
1862    ((string-match "::" desc)
1863     (format "[%s][%s]" (car (setq results (split-string desc "::"))) (cadr results)))
1864    (t (format "[%s]" desc))))
1865
1866 (defun org-ref-define-citation-link (type &optional key)
1867   "add a citation link for org-ref. With optional key, set the reftex binding. For example:
1868 (org-ref-define-citation-link \"citez\" ?z) will create a new citez link, with reftex key of z,
1869 and the completion function."
1870   (interactive "sCitation Type: \ncKey: ")
1871
1872   ;; create the formatting function
1873   (eval `(org-ref-make-format-function ,type))
1874
1875   (eval-expression
1876    `(org-add-link-type
1877      ,type
1878      org-ref-cite-onclick-function
1879      (quote ,(intern (format "org-ref-format-%s" type)))))
1880
1881   ;; create the completion function
1882   (eval `(org-ref-make-completion-function ,type))
1883
1884   ;; store new type so it works with adding citations, which checks
1885   ;; for existence in this list
1886   (add-to-list 'org-ref-cite-types type)
1887
1888   ;; and finally if a key is specified, we modify the reftex menu
1889   (when key
1890     (setf (nth 2 (assoc 'org reftex-cite-format-builtin))
1891           (append (nth 2 (assoc 'org reftex-cite-format-builtin))
1892                   `((,key  . ,(concat type ":%l")))))))
1893
1894 ;; create all the link types and their completion functions
1895 (mapcar 'org-ref-define-citation-link org-ref-cite-types)
1896 #+END_SRC
1897
1898 *** org-ref-insert-cite-link
1899 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.
1900
1901 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
1902 (defun org-ref-insert-cite-link (alternative-cite)
1903   "Insert a default citation link using reftex. If you are on a link, it
1904 appends to the end of the link, otherwise, a new link is
1905 inserted. Use a prefix arg to get a menu of citation types."
1906   (interactive "P")
1907   (org-ref-find-bibliography)
1908   (let* ((object (org-element-context))
1909          (link-string-beginning (org-element-property :begin object))
1910          (link-string-end (org-element-property :end object))
1911          (path (org-element-property :path object)))
1912
1913     (if (not alternative-cite)
1914
1915         (cond
1916          ;; case where we are in a link
1917          ((and (equal (org-element-type object) 'link)
1918                (-contains? org-ref-cite-types (org-element-property :type object)))
1919           (goto-char link-string-end)
1920           ;; sometimes there are spaces at the end of the link
1921           ;; this code moves point pack until no spaces are there
1922           (while (looking-back " ") (backward-char))
1923           (insert (concat "," (mapconcat 'identity (reftex-citation t ?a) ","))))
1924
1925          ;; We are next to a link, and we want to append
1926          ((save-excursion
1927             (backward-char)
1928             (and (equal (org-element-type (org-element-context)) 'link)
1929                  (-contains? org-ref-cite-types (org-element-property :type (org-element-context)))))
1930           (while (looking-back " ") (backward-char))
1931           (insert (concat "," (mapconcat 'identity (reftex-citation t ?a) ","))))
1932
1933          ;; insert fresh link
1934          (t
1935           (insert
1936            (concat org-ref-default-citation-link
1937                    ":"
1938                    (mapconcat 'identity (reftex-citation t) ",")))))
1939
1940       ;; you pressed a C-u so we run this code
1941       (reftex-citation)))
1942   )
1943 #+END_SRC
1944 cite:zhou-2004-first-lda-u,paier-2006-errat,boes-2015-estim-bulk
1945
1946
1947 #+RESULTS:
1948 : org-ref-insert-cite-link
1949
1950 *** Completion in cite links
1951 If you know the specific bibtex key, you may like to use completion directly. You use this with the org-mode machinery and tab completion. Here is the prototypical completion function. These are now all created when the links are created.
1952
1953 #+BEGIN_SRC emacs-lisp  :tangle no
1954 (defun org-cite-complete-link (&optional arg)
1955   "Completion function for cite links"
1956   (format "%s:%s"
1957           org-ref-default-citation-link
1958           (completing-read
1959            "bibtex key: "
1960            (let ((bibtex-files (org-ref-find-bibliography)))
1961              (bibtex-global-key-alist)))))
1962 #+END_SRC
1963
1964 Alternatively, you may shortcut the org-machinery with this command. You will be prompted for a citation type, and then offered key completion.
1965
1966 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1967 (defun org-ref-insert-cite-with-completion (type)
1968   "Insert a cite link with completion"
1969   (interactive (list (ido-completing-read "Type: " org-ref-cite-types)))
1970   (insert (funcall (intern (format "org-%s-complete-link" type)))))
1971 #+END_SRC
1972
1973 ** Storing links to a bibtex entry
1974 org-mode already defines a store link function for bibtex entries. It does not store the link I want though, it only stores a brief citation of the entry. I want a citation link. Here is a function to do that.
1975
1976 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
1977 (defun org-ref-store-bibtex-entry-link ()
1978   "Save a citation link to the current bibtex entry. Saves in the default link type."
1979   (interactive)
1980   (let ((link (concat org-ref-default-citation-link
1981                  ":"
1982                  (save-excursion
1983                    (bibtex-beginning-of-entry)
1984                    (reftex-get-bib-field "=key=" (bibtex-parse-entry))))))
1985     (message "saved %s" link)
1986     (push (list link) org-stored-links)
1987     (car org-stored-links)))
1988 #+END_SRC
1989
1990 ** Index entries
1991 org-ref minimally supports index entries. To make an index in a file, you should put in the LaTeX header these lines
1992
1993
1994 #+LATEX_HEADER: \usepackage{makeidx}
1995 #+LATEX_HEADER: \makeindex
1996
1997
1998 Finally, put \makeindex at the end of the document where you want the index to appear. You will need to run the makeindex program at an appropriate point in your LaTeX to pdf, or use ox-manuscript, which will do it for you.
1999
2000
2001 Use index links to create entries (see http://en.wikibooks.org/wiki/LaTeX/Indexing). Clicking on an index link runs occur on the buffer for the entry. The link exports to LaTeX. Some links may need to be enclosed in double brackets if they have spaces in them.
2002
2003
2004 index:hello
2005 index:hello!Peter
2006 [[index:hello!Sam@\textsl{Sam}]]
2007 [[index:Lin@\textbf{Lin}]]
2008 [[index:Joe|textit]]
2009 [[index:Lin@\textbf{Lin}]]
2010 [[index:Peter|see {hello}]]
2011 [[index:Jen|seealso{Jenny}]]
2012
2013 index:encodings!input!cp850
2014
2015 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2016 (org-add-link-type
2017  "index"
2018  (lambda (path)
2019    (occur path))
2020
2021  (lambda (path desc format)
2022    (cond
2023     ((eq format 'latex)
2024       (format "\\index{%s}" path)))))
2025
2026 ;; this will generate a temporary index of entries in the file.
2027 (org-add-link-type
2028  "printindex"
2029  (lambda (path)
2030    (let ((*index-links* '())
2031          (*initial-letters* '()))
2032
2033      ;; get links
2034      (org-element-map (org-element-parse-buffer) 'link
2035        (lambda (link)
2036          (let ((type (nth 0 link))
2037                (plist (nth 1 link)))
2038
2039            (when (equal (plist-get plist ':type) "index")
2040              (add-to-list
2041               '*index-links*
2042               (cons (plist-get plist :path)
2043                     (format
2044                      "[[elisp:(progn (switch-to-buffer \"%s\") (goto-char %s))][%s]]"
2045 (current-buffer)
2046                      (plist-get plist :begin)  ;; position of link
2047                      ;; grab a description
2048                      (save-excursion
2049                        (goto-char (plist-get plist :begin))
2050                        (if (thing-at-point 'sentence)
2051                            ;; get a sentence
2052                            (replace-regexp-in-string
2053                             "\n" "" (thing-at-point 'sentence))
2054                          ;; or call it a link
2055                          "link")))))))))
2056
2057      ;; sort the links
2058      (setq *index-links*  (cl-sort *index-links* 'string-lessp :key 'car))
2059
2060      ;; now first letters
2061      (dolist (link *index-links*)
2062        (add-to-list '*initial-letters* (substring (car link) 0 1) t))
2063
2064      ;; now create the index
2065      (switch-to-buffer (get-buffer-create "*index*"))
2066      (org-mode)
2067      (erase-buffer)
2068      (insert "#+TITLE: Index\n\n")
2069      (dolist (letter *initial-letters*)
2070        (insert (format "* %s\n" (upcase letter)))
2071        ;; now process the links
2072        (while (and
2073                ,*index-links*
2074                (string= letter (substring (car (car *index-links*)) 0 1)))
2075          (let ((link (pop *index-links*)))
2076            (insert (format "%s %s\n\n" (car link) (cdr link))))))
2077      (switch-to-buffer "*index*")))
2078  ;; formatting
2079  (lambda (path desc format)
2080    (cond
2081     ((eq format 'latex)
2082       (format "\\printindex")))))
2083 #+END_SRC
2084
2085 #+RESULTS:
2086 | lambda | (path)             | (let ((*index-links* (quote nil)) (*initial-letters* (quote nil))) (org-element-map (org-element-parse-buffer) (quote link) (lambda (link) (let ((type (nth 0 link)) (plist (nth 1 link))) (when (equal (plist-get plist (quote :type)) index) (add-to-list (quote *index-links*) (cons (plist-get plist :path) (format [[elisp:(progn (switch-to-buffer "%s") (goto-char %s))][%s]] (current-buffer) (plist-get plist :begin) (save-excursion (goto-char (plist-get plist :begin)) (if (thing-at-point (quote sentence)) (replace-regexp-in-string \n  (thing-at-point (quote sentence))) link))))))))) (setq *index-links* (cl-sort *index-links* (quote string-lessp) :key (quote car))) (dolist (link *index-links*) (add-to-list (quote *initial-letters*) (substring (car link) 0 1) t)) (switch-to-buffer (get-buffer-create *index*)) (org-mode) (erase-buffer) (insert #+TITLE: Index\n\n) (dolist (letter *initial-letters*) (insert (format * %s\n (upcase letter))) (while (and *index-links* (string= letter (substring (car (car *index-links*)) 0 1))) (let ((link (pop *index-links*))) (insert (format %s %s\n\n (car link) (cdr link)))))) (switch-to-buffer *index*)) |
2087 | lambda | (path desc format) | (cond ((eq format (quote latex)) (format \printindex)))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
2088
2089 ** Glossary
2090 org-ref provides some minimal support for a glossary. See http://en.wikibooks.org/wiki/LaTeX/Glossary for details. You need to put these lines in the header.
2091
2092 #+LATEX_HEADER: \usepackage{glossaries}
2093 #+LATEX_HEADER: \makeglossaries
2094
2095 And at the end of the document put \makeglossaries.
2096
2097 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2098 (org-add-link-type
2099  "newglossaryentry"
2100  nil ;; no follow action
2101  (lambda (path desc format)
2102    (cond
2103     ((eq format 'latex)
2104      (format "\\newglossaryentry{%s}{%s}" path desc)))))
2105
2106
2107 ;; link to entry
2108 (org-add-link-type
2109  "gls"
2110   nil ;; no follow action
2111  (lambda (path desc format)
2112    (cond
2113     ((eq format 'latex)
2114      (format "\\gls{%s}" path)))))
2115
2116 ;; plural
2117 (org-add-link-type
2118  "glspl"
2119   nil ;; no follow action
2120  (lambda (path desc format)
2121    (cond
2122     ((eq format 'latex)
2123      (format "\\glspl{%s}" path)))))
2124
2125 ;; capitalized link
2126 (org-add-link-type
2127  "Gls"
2128   nil ;; no follow action
2129  (lambda (path desc format)
2130    (cond
2131     ((eq format 'latex)
2132      (format "\\Gls{%s}" path)))))
2133
2134 ;; capitalized link
2135 (org-add-link-type
2136  "Glspl"
2137   nil ;; no follow action
2138  (lambda (path desc format)
2139    (cond
2140     ((eq format 'latex)
2141      (format "\\Glspl{%s}" path)))))
2142 #+END_SRC
2143
2144 * Utilities
2145 ** create simple text citation from bibtex entry
2146
2147 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2148 (defun org-ref-bib-citation ()
2149   "From a bibtex entry, create and return a simple citation string.
2150 This assumes you are in an article."
2151
2152   (bibtex-beginning-of-entry)
2153   (let* ((cb (current-buffer))
2154          (bibtex-expand-strings t)
2155          (entry (loop for (key . value) in (bibtex-parse-entry t)
2156                       collect (cons (downcase key) value)))
2157          (title (replace-regexp-in-string "\n\\|\t\\|\s+" " " (reftex-get-bib-field "title" entry)))
2158          (year  (reftex-get-bib-field "year" entry))
2159          (author (replace-regexp-in-string "\n\\|\t\\|\s+" " " (reftex-get-bib-field "author" entry)))
2160          (key (reftex-get-bib-field "=key=" entry))
2161          (journal (reftex-get-bib-field "journal" entry))
2162          (volume (reftex-get-bib-field "volume" entry))
2163          (pages (reftex-get-bib-field "pages" entry))
2164          (doi (reftex-get-bib-field "doi" entry))
2165          (url (reftex-get-bib-field "url" entry))
2166          )
2167     ;;authors, "title", Journal, vol(iss):pages (year).
2168     (format "%s, \"%s\", %s, %s:%s (%s)"
2169             author title journal  volume pages year)))
2170 #+END_SRC
2171
2172 #+RESULTS:
2173 : org-ref-bib-citation
2174
2175
2176 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2177 (defun org-ref-bib-html-citation ()
2178   "from a bibtex entry, create and return a simple citation with html links."
2179
2180   (bibtex-beginning-of-entry)
2181   (let* ((cb (current-buffer))
2182          (bibtex-expand-strings t)
2183          (entry (loop for (key . value) in (bibtex-parse-entry t)
2184                       collect (cons (downcase key) value)))
2185          (title (replace-regexp-in-string "\n\\|\t\\|\s+" " " (reftex-get-bib-field "title" entry)))
2186          (year  (reftex-get-bib-field "year" entry))
2187          (author (replace-regexp-in-string "\n\\|\t\\|\s+" " " (reftex-get-bib-field "author" entry)))
2188          (key (reftex-get-bib-field "=key=" entry))
2189          (journal (reftex-get-bib-field "journal" entry))
2190          (volume (reftex-get-bib-field "volume" entry))
2191          (pages (reftex-get-bib-field "pages" entry))
2192          (doi (reftex-get-bib-field "doi" entry))
2193          (url (reftex-get-bib-field "url" entry))
2194          )
2195     ;;authors, "title", Journal, vol(iss):pages (year).
2196     (concat (format "%s, \"%s\", %s, %s:%s (%s)."
2197                     author title journal  volume pages year)
2198             (when url (format " <a href=\"%s\">link</a>" url))
2199             (when doi (format " <a href=\"http://dx.doi.org/%s\">doi</a>" doi)))
2200     ))
2201 #+END_SRC
2202
2203 ** open pdf from bibtex
2204 We bind this to a key here: [[*key%20bindings%20for%20utilities][key bindings for utilities]].
2205 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2206 (defun org-ref-open-bibtex-pdf ()
2207   "open pdf for a bibtex entry, if it exists. assumes point is in
2208 the entry of interest in the bibfile. but does not check that."
2209   (interactive)
2210   (save-excursion
2211     (bibtex-beginning-of-entry)
2212     (let* ((bibtex-expand-strings t)
2213            (entry (bibtex-parse-entry t))
2214            (key (reftex-get-bib-field "=key=" entry))
2215            (pdf (format (concat org-ref-pdf-directory "%s.pdf") key)))
2216       (message "%s" pdf)
2217       (if (file-exists-p pdf)
2218           (org-open-link-from-string (format "[[file:%s]]" pdf))
2219         (ding)))))
2220 #+END_SRC
2221
2222 ** open notes from bibtex
2223 We bind this to a key here [[*key%20bindings%20for%20utilities][key bindings for utilities]].
2224
2225 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2226 (defun org-ref-open-bibtex-notes ()
2227   "from a bibtex entry, open the notes if they exist, and create a heading if they do not.
2228
2229 I never did figure out how to use reftex to make this happen
2230 non-interactively. the reftex-format-citation function did not
2231 work perfectly; there were carriage returns in the strings, and
2232 it did not put the key where it needed to be. so, below I replace
2233 the carriage returns and extra spaces with a single space and
2234 construct the heading by hand."
2235   (interactive)
2236
2237   (bibtex-beginning-of-entry)
2238   (let* ((cb (current-buffer))
2239          (bibtex-expand-strings t)
2240          (entry (loop for (key . value) in (bibtex-parse-entry t)
2241                       collect (cons (downcase key) value)))
2242          (title (replace-regexp-in-string "\n\\|\t\\|\s+" " " (reftex-get-bib-field "title" entry)))
2243          (year  (reftex-get-bib-field "year" entry))
2244          (author (replace-regexp-in-string "\n\\|\t\\|\s+" " " (reftex-get-bib-field "author" entry)))
2245          (key (reftex-get-bib-field "=key=" entry))
2246          (journal (reftex-get-bib-field "journal" entry))
2247          (volume (reftex-get-bib-field "volume" entry))
2248          (pages (reftex-get-bib-field "pages" entry))
2249          (doi (reftex-get-bib-field "doi" entry))
2250          (url (reftex-get-bib-field "url" entry))
2251          )
2252
2253     ;; save key to clipboard to make saving pdf later easier by pasting.
2254     (with-temp-buffer
2255       (insert key)
2256       (kill-ring-save (point-min) (point-max)))
2257
2258     ;; now look for entry in the notes file
2259     (if  org-ref-bibliography-notes
2260         (find-file-other-window org-ref-bibliography-notes)
2261       (error "org-ref-bib-bibliography-notes is not set to anything"))
2262
2263     (goto-char (point-min))
2264     ;; put new entry in notes if we don't find it.
2265     (if (re-search-forward (format ":Custom_ID: %s$" key) nil 'end)
2266         (funcall org-ref-open-notes-function)
2267       ;; no entry found, so add one
2268       (insert (format "\n** TODO %s - %s" year title))
2269       (insert (format"
2270  :PROPERTIES:
2271   :Custom_ID: %s
2272   :AUTHOR: %s
2273   :JOURNAL: %s
2274   :YEAR: %s
2275   :VOLUME: %s
2276   :PAGES: %s
2277   :DOI: %s
2278   :URL: %s
2279  :END:
2280 [[cite:%s]] [[file:%s/%s.pdf][pdf]]\n\n"
2281 key author journal year volume pages doi url key org-ref-pdf-directory key))
2282 (save-buffer))))
2283 #+END_SRC
2284
2285 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2286 (defun org-ref-open-notes-from-reftex ()
2287   "Call reftex, and open notes for selected entry."
2288   (interactive)
2289   (let ((bibtex-key )))
2290
2291     ;; now look for entry in the notes file
2292     (if  org-ref-bibliography-notes
2293         (find-file-other-window org-ref-bibliography-notes)
2294       (error "org-ref-bib-bibliography-notes is not set to anything"))
2295
2296     (goto-char (point-min))
2297
2298     (re-search-forward (format
2299                         ":Custom_ID: %s$"
2300                         (first (reftex-citation t)) nil 'end))
2301     (funcall org-ref-open-notes-function))
2302 #+END_SRC
2303
2304 ** open url in browser from bibtex
2305
2306 We bind this to a key here [[*key%20bindings%20for%20utilities][key bindings for utilities]].
2307
2308 + This function may be duplicative of bibtex-url. But I think my function is better unless you do some complicated customization of bibtex-generate-url-list.
2309
2310 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2311 (defun org-ref-open-in-browser ()
2312   "Open the bibtex entry at point in a browser using the url field or doi field"
2313 (interactive)
2314 (save-excursion
2315   (bibtex-beginning-of-entry)
2316   (catch 'done
2317     (let ((url (bibtex-autokey-get-field "url")))
2318       (when  url
2319         (browse-url url)
2320         (throw 'done nil)))
2321
2322     (let ((doi (bibtex-autokey-get-field "doi")))
2323       (when doi
2324         (if (string-match "^http" doi)
2325             (browse-url doi)
2326           (browse-url (format "http://dx.doi.org/%s" doi)))
2327         (throw 'done nil)))
2328     (message "No url or doi found"))))
2329 #+END_SRC
2330
2331 ** citeulike
2332    I discovered you could upload a bibtex entry to citeulike using http requests. The upload is actually done by a [[*The%20upload%20script][python script]], because it was easy to write. Here is the emacs command to do this. It is not a fast operation, and  do not use it frequently.
2333
2334 *** function to upload bibtex to citeulike
2335
2336 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2337 (defun org-ref-upload-bibtex-entry-to-citeulike ()
2338   "with point in  a bibtex entry get bibtex string and submit to citeulike.
2339
2340 Relies on the python script /upload_bibtex_citeulike.py being in the user directory."
2341   (interactive)
2342   (message "uploading to citeulike")
2343   (save-restriction
2344     (bibtex-narrow-to-entry)
2345     (let ((startpos (point-min))
2346           (endpos (point-max))
2347           (bibtex-string (buffer-string))
2348           (script (concat "python " starter-kit-dir "/upload_bibtex_citeulike.py&")))
2349       (with-temp-buffer (insert bibtex-string)
2350                         (shell-command-on-region (point-min) (point-max) script t nil nil t)))))
2351 #+END_SRC
2352
2353 *** The upload script
2354 Here is the python script for uploading.
2355
2356 *************** TODO document how to get the cookies
2357 *************** END
2358
2359
2360 #+BEGIN_SRC python :tangle upload_bibtex_citeulike.py
2361 #!python
2362 import pickle, requests, sys
2363
2364 # reload cookies
2365 with open('c:/Users/jkitchin/Dropbox/blogofile-jkitchin.github.com/_blog/cookies.pckl', 'rb') as f:
2366     cookies = pickle.load(f)
2367
2368 url = 'http://www.citeulike.org/profile/jkitchin/import_do'
2369
2370 bibtex = sys.stdin.read()
2371
2372 data = {'pasted':bibtex,
2373         'to_read':2,
2374         'tag_parsing':'simple',
2375         'strip_brackets':'no',
2376         'update_id':'bib-key',
2377         'btn_bibtex':'Import BibTeX file ...'}
2378
2379 headers = {'content-type': 'multipart/form-data',
2380            'User-Agent':'jkitchin/johnrkitchin@gmail.com bibtexupload'}
2381
2382 r = requests.post(url, headers=headers, data=data, cookies=cookies, files={})
2383 print r
2384 #+END_SRC
2385
2386 ** Build a pdf from a bibtex file
2387    It is useful to have a pdf version of an entire bibliography to check it for formatting, spelling, or to share it. This function creates a pdf from a bibtex file. I only include the packages  I commonly use in my bitex files.
2388
2389 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2390 (defun org-ref-build-full-bibliography ()
2391   "build pdf of all bibtex entries, and open it."
2392   (interactive)
2393   (let* ((bibfile (file-name-nondirectory (buffer-file-name)))
2394         (bib-base (file-name-sans-extension bibfile))
2395         (texfile (concat bib-base ".tex"))
2396         (pdffile (concat bib-base ".pdf")))
2397     (find-file texfile)
2398     (erase-buffer)
2399     (insert (format "\\documentclass[12pt]{article}
2400 \\usepackage[version=3]{mhchem}
2401 \\usepackage{url}
2402 \\usepackage[numbers]{natbib}
2403 \\usepackage[colorlinks=true, linkcolor=blue, urlcolor=blue, pdfstartview=FitH]{hyperref}
2404 \\usepackage{doi}
2405 \\begin{document}
2406 \\nocite{*}
2407 \\bibliographystyle{unsrtnat}
2408 \\bibliography{%s}
2409 \\end{document}" bib-base))
2410     (save-buffer)
2411     (shell-command (concat "pdflatex " bib-base))
2412     (shell-command (concat "bibtex " bib-base))
2413     (shell-command (concat "pdflatex " bib-base))
2414     (shell-command (concat "pdflatex " bib-base))
2415     (kill-buffer texfile)
2416     (org-open-file pdffile)
2417     ))
2418 #+END_SRC
2419
2420 ** Extract bibtex entries cited in an org-file
2421 When you use your default bibliography file, and you want to send an org-file to a collaborator, you may need to include bibtex entries so the other person can see them. This function does that and puts the entries in a section at the end of the document that can be tangled to a bib-file.
2422
2423 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
2424 (defun org-ref-extract-bibtex-entries ()
2425   "extract the bibtex entries referred to by cite links in the current buffer into a src block at the bottom of the current buffer.
2426
2427 If no bibliography is in the buffer the `reftex-default-bibliography' is used."
2428   (interactive)
2429   (let* ((temporary-file-directory (file-name-directory (buffer-file-name)))
2430          (tempname (make-temp-file "extract-bib"))
2431          (contents (buffer-string))
2432          (cb (current-buffer))
2433          basename texfile bibfile results)
2434
2435     ;; open tempfile and insert org-buffer contents
2436     (find-file tempname)
2437     (insert contents)
2438     (setq basename (file-name-sans-extension
2439                     (file-name-nondirectory buffer-file-name))
2440           texfile (concat tempname ".tex")
2441           bibfile (concat tempname ".bib"))
2442
2443     ;; see if we have a bibliography, and insert the default one if not.
2444     (save-excursion
2445       (goto-char (point-min))
2446       (unless (re-search-forward "^bibliography:" (point-max) 'end)
2447         (insert (format "\nbibliography:%s"
2448                         (mapconcat 'identity reftex-default-bibliography ",")))))
2449     (save-buffer)
2450
2451     ;; get a latex file and extract the references
2452     (org-latex-export-to-latex)
2453     (find-file texfile)
2454     (reftex-parse-all)
2455     (reftex-create-bibtex-file bibfile)
2456     (save-buffer)
2457     ;; save results of the references
2458     (setq results (buffer-string))
2459
2460     ;; kill buffers. these are named by basename, not full path
2461     (kill-buffer (concat basename ".bib"))
2462     (kill-buffer (concat basename ".tex"))
2463     (kill-buffer basename)
2464
2465     (delete-file bibfile)
2466     (delete-file texfile)
2467     (delete-file tempname)
2468
2469     ;; Now back to the original org buffer and insert the results
2470     (switch-to-buffer cb)
2471     (when (not (string= "" results))
2472       (save-excursion
2473         (goto-char (point-max))
2474         (insert "\n\n")
2475         (org-insert-heading)
2476         (insert (format " Bibtex entries
2477
2478 ,#+BEGIN_SRC text :tangle %s
2479 %s
2480 ,#+END_SRC" (concat (file-name-sans-extension (file-name-nondirectory (buffer-file-name))) ".bib") results))))))
2481 #+END_SRC
2482
2483 ** Find bad cite links
2484    :PROPERTIES:
2485    :ID:       8515E800-EDA0-4B2A-85FD-55B6FF849203
2486    :END:
2487 Depending on how you enter citations, you may have citations with no corresponding bibtex entry. This function finds them and gives you a clickable table to navigate to them.
2488
2489 #+BEGIN_SRC emacs-lisp  :tangle org-ref.el
2490 (require 'cl)
2491
2492 (defun index (substring list)
2493   "return the index of string in a list of strings"
2494   (let ((i 0)
2495         (found nil))
2496     (dolist (arg list i)
2497       (if (string-match (concat "^" substring "$") arg)
2498           (progn
2499             (setq found t)
2500             (return i)))
2501       (setq i (+ i 1)))
2502     ;; return counter if found, otherwise return nil
2503     (if found i nil)))
2504
2505
2506 (defun org-ref-find-bad-citations ()
2507   "Create a list of citation keys in an org-file that do not have a bibtex entry in the known bibtex files.
2508
2509 Makes a new buffer with clickable links."
2510   (interactive)
2511   ;; generate the list of bibtex-keys and cited keys
2512   (let* ((bibtex-files (org-ref-find-bibliography))
2513          (bibtex-file-path (mapconcat (lambda (x) (file-name-directory (file-truename x))) bibtex-files ":"))
2514          (bibtex-keys (mapcar (lambda (x) (car x)) (bibtex-global-key-alist)))
2515          (bad-citations '()))
2516
2517     (org-element-map (org-element-parse-buffer) 'link
2518       (lambda (link)
2519         (let ((plist (nth 1 link)))
2520           (when (equal (plist-get plist ':type) "cite")
2521             (dolist (key (org-ref-split-and-strip-string (plist-get plist ':path)) )
2522               (when (not (index key bibtex-keys))
2523                 (setq bad-citations (append bad-citations
2524                                             `(,(format "%s [[elisp:(progn (switch-to-buffer-other-frame \"%s\")(goto-char %s))][not found here]]\n"
2525                                                        key (buffer-name)(plist-get plist ':begin)))))
2526                 ))))))
2527
2528     (if bad-citations
2529       (progn
2530         (switch-to-buffer-other-window "*Missing citations*")
2531         (org-mode)
2532         (erase-buffer)
2533         (insert "* List of bad cite links\n")
2534         (insert (mapconcat 'identity bad-citations ""))
2535                                         ;(setq buffer-read-only t)
2536         (use-local-map (copy-keymap org-mode-map))
2537         (local-set-key "q" #'(lambda () (interactive) (kill-buffer))))
2538
2539       (when (get-buffer "*Missing citations*")
2540           (kill-buffer "*Missing citations*"))
2541       (message "No bad cite links found"))))
2542 #+END_SRC
2543
2544 ** helm interface to org-ref
2545 In [[id:8515E800-EDA0-4B2A-85FD-55B6FF849203][Find bad cite links]] we wrote a function that finds bad links and creates a buffer of links to them.
2546
2547 Here we develop a similar idea, but instead of an org-buffer with links, we create helm sources for bad cite links, bad ref links, and multiple labels.
2548
2549 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2550 (defun org-ref-bad-cite-candidates ()
2551   "Returns a list of conses (key . marker) where key does not exist in the known bibliography files, and marker points to the key."
2552   (let* ((cp (point))                   ; save to return to later
2553          (bibtex-files (org-ref-find-bibliography))
2554          (bibtex-file-path (mapconcat
2555                             (lambda (x)
2556                               (file-name-directory (file-truename x)))
2557                             bibtex-files ":"))
2558          (bibtex-keys (mapcar (lambda (x) (car x))
2559                               (bibtex-global-key-alist)))
2560          (bad-citations '()))
2561
2562     (org-element-map (org-element-parse-buffer) 'link
2563       (lambda (link)
2564         (let ((plist (nth 1 link)))
2565           (when (-contains? org-ref-cite-types (plist-get plist ':type))
2566             (dolist (key (org-ref-split-and-strip-string (plist-get plist ':path)) )
2567               (when (not (index key bibtex-keys))
2568                 (goto-char (plist-get plist ':begin))
2569                 (re-search-forward key)
2570                 (push (cons key (point-marker)) bad-citations)))
2571               ))))
2572     (goto-char cp)
2573     bad-citations))
2574
2575 ;; It seems I forgot I already defined this earlier!
2576 ;; (defun org-ref-get-labels ()
2577 ;;   "Returns a list of known labels in the org document. These include label links, latex labels, label tags, and table names. The list contains all labels, not just unique ones.
2578 ;; "
2579 ;;   (let ((cp (point))
2580 ;;      (labels '()))
2581 ;;     (goto-char (point-min))
2582 ;;     (while (re-search-forward "[^#+]label:\\(.*\\)\\s-" nil t)
2583 ;;       (push  (match-string 1) labels))
2584
2585 ;;     (goto-char (point-min))
2586 ;;     (while (re-search-forward "\\label{\\(.*\\)}\\s-?" nil t)
2587 ;;       (push (match-string 1) labels))
2588
2589 ;;     (goto-char (point-min))
2590 ;;     (while (re-search-forward "^#\\+label:\\s-*\\(.*\\)" nil t)
2591 ;;       (push (match-string 1) labels))
2592
2593 ;;     (goto-char (point-min))
2594 ;;     (while (re-search-forward "^#\\+tblname:\\s-*\\(.*\\)" nil t)
2595 ;;       (push (match-string 1) labels))
2596 ;;     ;; check for CUSTOM_ID
2597 ;;     (org-map-entries
2598 ;;      (lambda ()
2599 ;;        (when (org-entry-get (point) "CUSTOM_ID")
2600 ;;       (push (org-entry-get (point) "CUSTOM_ID") labels))))
2601 ;;     ;; return to original place
2602 ;;     (goto-char cp)
2603 ;;     labels))
2604
2605
2606 (defun org-ref-bad-ref-candidates ()
2607   "Returns a list of conses (ref . marker) where ref is a ref link that does not point to anything (i.e. a label)."
2608   ;; first get a list of legitimate labels
2609   (let ((cp (point))
2610         (labels (org-ref-get-labels))
2611         (bad-refs '()))
2612     ;; now loop over ref links
2613     (goto-char (point-min))
2614     (org-element-map (org-element-parse-buffer) 'link
2615       (lambda (link)
2616         (let ((plist (nth 1 link)))
2617           (when (or  (equal (plist-get plist ':type) "ref")
2618                      (equal (plist-get plist ':type) "eqref")
2619                      (equal (plist-get plist ':type) "pageref")
2620                      (equal (plist-get plist ':type) "nameref"))
2621             (unless (-contains? labels (plist-get plist :path))
2622               (goto-char (plist-get plist :begin))
2623               (add-to-list
2624                'bad-refs
2625                (cons (plist-get plist :path)
2626                      (point-marker))))))))
2627     (goto-char cp)
2628     bad-refs))
2629
2630
2631 (defun org-ref-bad-label-candidates ()
2632   "Return a list of labels where label is multiply defined."
2633   (let ((labels (org-ref-get-labels))
2634         (multiple-labels '()))
2635     (when (not (= (length labels)
2636                   (length (-uniq labels))))
2637       (dolist (label labels)
2638         (when (> (-count (lambda (a)
2639                            (equal a label))
2640                          labels) 1)
2641           ;; this is a multiply defined label.
2642           (let ((cp (point)))
2643             (goto-char (point-min))
2644             (while (re-search-forward
2645                     (format  "[^#+]label:%s\\s-" label) nil t)
2646               (push (cons label (point-marker)) multiple-labels))
2647
2648             (goto-char (point-min))
2649             (while (re-search-forward
2650                     (format  "\\label{%s}\\s-?" label) nil t)
2651               (push (cons label (point-marker)) multiple-labels))
2652
2653             (goto-char (point-min))
2654             (while (re-search-forward
2655                     (format  "^#\\+label:\\s-*%s" label) nil t)
2656               (push (cons label (point-marker)) multiple-labels))
2657
2658             (goto-char (point-min))
2659             (while (re-search-forward
2660                     (format   "^#\\+tblname:\\s-*%s" label) nil t)
2661               (push (cons label (point-marker)) multiple-labels))
2662             (goto-char cp)))))
2663       multiple-labels))
2664 #+END_SRC
2665
2666 #+RESULTS:
2667 : org-ref-bad-label-candidates
2668
2669 Now, we have a functions for candidates, we can make helm sources for each one, and then run a helm command to view them.
2670
2671 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2672 (defun org-ref ()
2673   "Opens a helm interface to actions for org-ref.
2674 Shows bad citations, ref links and labels"
2675   (interactive)
2676   (let ((cb (current-buffer))
2677         (bad-citations (org-ref-bad-cite-candidates))
2678         (bad-refs (org-ref-bad-ref-candidates))
2679         (bad-labels (org-ref-bad-label-candidates)))
2680
2681     (helm :sources `(((name . "Bad citations")
2682                        (candidates . ,bad-citations)
2683                        (action . (lambda (marker)
2684                                    (switch-to-buffer (marker-buffer marker))
2685                                    (goto-char marker))))
2686                      ;;
2687                      ((name . "Bad Labels")
2688                       (candidates . ,bad-labels)
2689                       (action . (lambda (marker)
2690                                    (switch-to-buffer (marker-buffer marker))
2691                                    (goto-char marker))))
2692                      ;;
2693                      ((name . "Bad ref links")
2694                       (candidates . ,bad-refs)
2695                       (action . (lambda (marker)
2696                                           (switch-to-buffer (marker-buffer marker))
2697                                           (goto-char marker))))
2698                      ;;
2699                      ((name . "Utilities")
2700                       (candidates . (("Check buffer again" . org-ref)
2701                                      ("Insert citation" . helm-bibtex)
2702                                      ("Insert label link" . org-ref-helm-insert-label-link)
2703                                      ("Insert ref link" . org-ref-helm-insert-ref-link)
2704                                      ("List of figures" . org-ref-list-of-figures)
2705                                      ("List of tables" . org-ref-list-of-tables)
2706                                      ("Table of contents" . nil)
2707                                      ))
2708                       (action . (lambda (x)
2709                                   (switch-to-buffer ,cb)
2710                                   (funcall x))))
2711                      ;;
2712                      ((name . "Export functions")
2713                       (candidates . (("Extract cited entries" . org-ref-extract-bibtex-entries)
2714                                      ("Export to html and open" . (lambda () (org-open-file (org-html-export-to-html))))
2715                                      ("Export to pdf and open" . (lambda ()
2716                                                                    (org-open-file (org-latex-export-to-pdf))))
2717                                      ("Export to manuscript pdf and open" . ox-manuscript-export-and-build-and-open)
2718                                      ("Export submission manuscript pdf and open" . ox-manuscript-build-submission-manuscript-and-open)
2719
2720                                      ))
2721                       (action . (lambda (x)
2722                                   (switch-to-buffer ,cb)
2723                                   (funcall x))))
2724                       ))))
2725 #+END_SRC
2726
2727
2728 ** Finding non-ascii characters
2729 I like my bibtex files to be 100% ascii. This function finds the non-ascii characters so you can replace them.
2730
2731 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2732 (defun org-ref-find-non-ascii-characters ()
2733   "finds non-ascii characters in the buffer. Useful for cleaning up bibtex files"
2734   (interactive)
2735   (occur "[^[:ascii:]]"))
2736 #+END_SRC
2737
2738 ** Resort a bibtex entry
2739 I like neat and orderly bibtex entries.That means the fields are in a standard order that I like. This function reorders the fields in an entry for articles, and makes sure the fields are in lowercase.
2740
2741 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2742 (defun org-ref-sort-bibtex-entry ()
2743   "sort fields of entry in standard order and downcase them"
2744   (interactive)
2745   (bibtex-beginning-of-entry)
2746   (let* ((master '("author" "title" "journal" "volume" "number" "pages" "year" "doi" "url"))
2747          (entry (bibtex-parse-entry))
2748          (entry-fields)
2749          (other-fields)
2750          (type (cdr (assoc "=type=" entry)))
2751          (key (cdr (assoc "=key=" entry))))
2752
2753     ;; these are the fields we want to order that are in this entry
2754     (setq entry-fields (mapcar (lambda (x) (car x)) entry))
2755     ;; we do not want to reenter these fields
2756     (setq entry-fields (remove "=key=" entry-fields))
2757     (setq entry-fields (remove "=type=" entry-fields))
2758
2759     ;;these are the other fields in the entry
2760     (setq other-fields (remove-if-not (lambda(x) (not (member x master))) entry-fields))
2761
2762     (cond
2763      ;; right now we only resort articles
2764      ((string= (downcase type) "article")
2765       (bibtex-kill-entry)
2766       (insert
2767        (concat "@article{" key ",\n"
2768                (mapconcat
2769                 (lambda (field)
2770                   (when (member field entry-fields)
2771                     (format "%s = %s," (downcase field) (cdr (assoc field entry))))) master "\n")
2772                (mapconcat
2773                 (lambda (field)
2774                   (format "%s = %s," (downcase field) (cdr (assoc field entry)))) other-fields "\n")
2775                "\n}\n\n"))
2776       (bibtex-find-entry key)
2777       (bibtex-fill-entry)
2778       (bibtex-clean-entry)
2779        ))))
2780 #+END_SRC
2781
2782 ** Clean a bibtex entry
2783    I like neat and orderly bibtex entries. This code will eventually replace the key with my style key, clean the entry, and sort the fields in the order I like them.
2784 see [[file:emacs-24.3/lisp/textmodes/bibtex.el::bibtex-autokey-before-presentation-function]] for how to set a function that checks for uniqueness of the key.
2785 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2786 (defun org-ref-clean-bibtex-entry(&optional keep-key)
2787   "clean and replace the key in a bibtex function. When keep-key is t, do not replace it. You can use a prefix to specify the key should be kept"
2788   (interactive "P")
2789   (bibtex-beginning-of-entry)
2790 (end-of-line)
2791   ;; some entries do not have a key or comma in first line. We check and add it, if needed.
2792   (unless (string-match ",$" (thing-at-point 'line))
2793     (end-of-line)
2794     (insert ","))
2795
2796   ;; check for empty pages, and put eid or article id in its place
2797   (let ((entry (bibtex-parse-entry))
2798         (pages (bibtex-autokey-get-field "pages"))
2799         (year (bibtex-autokey-get-field "year"))
2800         (doi  (bibtex-autokey-get-field "doi"))
2801         ;; The Journal of Chemical Physics uses eid
2802         (eid (bibtex-autokey-get-field "eid")))
2803
2804     ;; replace http://dx.doi.org/ in doi. some journals put that in,
2805     ;; but we only want the doi.
2806     (when (string-match "^http://dx.doi.org/" doi)
2807       (bibtex-beginning-of-entry)
2808       (goto-char (car (cdr (bibtex-search-forward-field "doi" t))))
2809       (bibtex-kill-field)
2810       (bibtex-make-field "doi")
2811       (backward-char)
2812       (insert (replace-regexp-in-string "^http://dx.doi.org/" "" doi)))
2813
2814     ;; asap articles often set year to 0, which messes up key
2815     ;; generation. fix that.
2816     (when (string= "0" year)
2817       (bibtex-beginning-of-entry)
2818       (goto-char (car (cdr (bibtex-search-forward-field "year" t))))
2819       (bibtex-kill-field)
2820       (bibtex-make-field "year")
2821       (backward-char)
2822       (insert (read-string "Enter year: ")))
2823
2824     ;; fix pages if they are empty if there is an eid to put there.
2825     (when (string= "-" pages)
2826       (when eid
2827         (bibtex-beginning-of-entry)
2828         ;; this seems like a clunky way to set the pages field.But I
2829         ;; cannot find a better way.
2830         (goto-char (car (cdr (bibtex-search-forward-field "pages" t))))
2831         (bibtex-kill-field)
2832         (bibtex-make-field "pages")
2833         (backward-char)
2834         (insert eid)))
2835
2836     ;; replace naked & with \&
2837     (save-restriction
2838       (bibtex-narrow-to-entry)
2839       (bibtex-beginning-of-entry)
2840       (message "checking &")
2841       (replace-regexp " & " " \\\\& ")
2842       (widen))
2843
2844     ;; generate a key, and if it duplicates an existing key, edit it.
2845     (unless keep-key
2846       (let ((key (bibtex-generate-autokey)))
2847
2848         ;; first we delete the existing key
2849         (bibtex-beginning-of-entry)
2850         (re-search-forward bibtex-entry-maybe-empty-head)
2851         (if (match-beginning bibtex-key-in-head)
2852             (delete-region (match-beginning bibtex-key-in-head)
2853                            (match-end bibtex-key-in-head)))
2854         ;; check if the key is in the buffer
2855         (when (save-excursion
2856                 (bibtex-search-entry key))
2857           (save-excursion
2858             (bibtex-search-entry key)
2859             (bibtex-copy-entry-as-kill)
2860             (switch-to-buffer-other-window "*duplicate entry*")
2861             (bibtex-yank))
2862           (setq key (bibtex-read-key "Duplicate Key found, edit: " key)))
2863
2864         (insert key)
2865         (kill-new key))) ;; save key for pasting
2866
2867     ;; run hooks. each of these operates on the entry with no arguments.
2868     ;; this did not work like  i thought, it gives a symbolp error.
2869     ;; (run-hooks org-ref-clean-bibtex-entry-hook)
2870     (mapcar (lambda (x)
2871               (save-restriction
2872                 (save-excursion
2873                   (funcall x))))
2874             org-ref-clean-bibtex-entry-hook)
2875
2876     ;; sort fields within entry
2877     (org-ref-sort-bibtex-entry)
2878     ;; check for non-ascii characters
2879     (occur "[^[:ascii:]]")
2880     ))
2881 #+END_SRC
2882
2883 #+RESULTS:
2884 : org-ref-clean-bibtex-entry
2885
2886 ** Sort the entries in a citation link by year
2887 I prefer citations in chronological order within a grouping. These functions sort the link under the cursor by year.
2888
2889 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2890 (defun org-ref-get-citation-year (key)
2891   "get the year of an entry with key. Returns year as a string."
2892   (interactive)
2893   (let* ((results (org-ref-get-bibtex-key-and-file key))
2894          (bibfile (cdr results)))
2895     (with-temp-buffer
2896       (insert-file-contents bibfile)
2897       (bibtex-search-entry key nil 0)
2898       (prog1 (reftex-get-bib-field "year" (bibtex-parse-entry t))
2899         ))))
2900
2901 (defun org-ref-sort-citation-link ()
2902  "replace link at point with sorted link by year"
2903  (interactive)
2904  (let* ((object (org-element-context))
2905         (type (org-element-property :type object))
2906         (begin (org-element-property :begin object))
2907         (end (org-element-property :end object))
2908         (link-string (org-element-property :path object))
2909         keys years data)
2910   (setq keys (org-ref-split-and-strip-string link-string))
2911   (setq years (mapcar 'org-ref-get-citation-year keys))
2912   (setq data (mapcar* (lambda (a b) `(,a . ,b)) years keys))
2913   (setq data (cl-sort data (lambda (x y) (< (string-to-int (car x)) (string-to-int (car y))))))
2914   ;; now get the keys separated by commas
2915   (setq keys (mapconcat (lambda (x) (cdr x)) data ","))
2916   ;; and replace the link with the sorted keys
2917   (cl--set-buffer-substring begin end (concat type ":" keys))))
2918 #+END_SRC
2919
2920 ** Sort entries in citation links with shift-arrow keys
2921 Sometimes it may be helpful to manually change the order of citations. These functions define shift-arrow functions.
2922 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2923 (defun org-ref-swap-keys (i j keys)
2924  "swap the keys in a list with index i and j"
2925  (let ((tempi (nth i keys)))
2926    (setf (nth i keys) (nth j keys))
2927    (setf (nth j keys) tempi))
2928   keys)
2929
2930 (defun org-ref-swap-citation-link (direction)
2931  "move citation at point in direction +1 is to the right, -1 to the left"
2932  (interactive)
2933  (let* ((object (org-element-context))
2934         (type (org-element-property :type object))
2935         (begin (org-element-property :begin object))
2936         (end (org-element-property :end object))
2937         (link-string (org-element-property :path object))
2938         key keys i)
2939    ;;   We only want this to work on citation links
2940    (when (-contains? org-ref-cite-types type)
2941         (setq key (org-ref-get-bibtex-key-under-cursor))
2942         (setq keys (org-ref-split-and-strip-string link-string))
2943         (setq i (index key keys))  ;; defined in org-ref
2944         (if (> direction 0) ;; shift right
2945             (org-ref-swap-keys i (+ i 1) keys)
2946           (org-ref-swap-keys i (- i 1) keys))
2947         (setq keys (mapconcat 'identity keys ","))
2948         ;; and replace the link with the sorted keys
2949         (cl--set-buffer-substring begin end (concat type ":" keys " "))
2950         ;; now go forward to key so we can move with the key
2951         (re-search-forward key)
2952         (goto-char (match-beginning 0)))))
2953
2954 ;; add hooks to make it work
2955 (add-hook 'org-shiftright-hook (lambda () (org-ref-swap-citation-link 1)))
2956 (add-hook 'org-shiftleft-hook (lambda () (org-ref-swap-citation-link -1)))
2957 #+END_SRC
2958
2959 ** Lightweight messages about links
2960 To get a lighter weight message about the label, ref and cite links, we define a function that gives us the minibuffer message, without the menu. We run this in an idle timer.
2961
2962 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
2963 (defun org-ref-get-label-context (label)
2964   "Return a string of context around a label."
2965   (save-excursion
2966     (catch 'result
2967       (goto-char (point-min))
2968       (when (re-search-forward
2969              (format "label:%s\\b" label) nil t)
2970         (throw 'result (buffer-substring
2971                         (progn
2972                           (previous-line)
2973                           (beginning-of-line)
2974                           (point))
2975                         (progn
2976                           (forward-line 4)
2977                           (point)))))
2978
2979       (goto-char (point-min))
2980       (when (re-search-forward
2981              (format "\\label{%s}" label) nil t)
2982         (throw 'result (buffer-substring
2983                         (progn
2984                           (previous-line)
2985                           (beginning-of-line)
2986                           (point))
2987                         (progn
2988                           (forward-line 4)
2989                           (point)))))
2990
2991       (goto-char (point-min))
2992       (when (re-search-forward
2993              (format "^#\\+label:\\s-*\\(%s\\)\\b" label) nil t)
2994         (throw 'result (buffer-substring
2995                         (progn
2996                           (previous-line)
2997                           (beginning-of-line)
2998                           (point))
2999                         (progn
3000                           (forward-line 4)
3001                           (point)))))
3002
3003       (goto-char (point-min))
3004       (when (re-search-forward
3005              (format "^#\\+tblname:\\s-*\\(%s\\)\\b" label) nil t)
3006         (throw 'result (buffer-substring
3007                         (progn
3008                           (previous-line)
3009                           (beginning-of-line)
3010                           (point))
3011                         (progn
3012                           (forward-line 4)
3013                           (point)))))
3014
3015       ;; maybe we have a CUSTOM-ID
3016       (org-map-entries
3017        (lambda () (when (string=
3018                          label
3019                          (org-entry-get (point) "CUSTOM_ID"))
3020                     (throw 'result (org-get-heading)))))
3021       (beep)
3022       (throw 'result "!!! NO CONTEXT FOUND !!!"))))
3023
3024
3025 (defun org-ref-link-message ()
3026   "Print a minibuffer message about the link that point is on."
3027   (interactive)
3028   (when (eq major-mode 'org-mode)
3029     (let* ((object (org-element-context))
3030            (type (org-element-property :type object)))
3031       (save-excursion
3032         (cond
3033          ;; cite links
3034          ((-contains? org-ref-cite-types type)
3035           (message (org-ref-get-citation-string-at-point)))
3036
3037          ;; message some context about the label we are referring to
3038          ((string= type "ref")
3039           (message (org-ref-get-label-context
3040                     (org-element-property :path object))))
3041
3042          ((string= type "eqref")
3043           (message (org-ref-get-label-context
3044                     (org-element-property :path object))))
3045
3046          ;; message the count
3047          ((string= type "label")
3048           (let ((count (org-ref-count-labels
3049                         (org-element-property :path object))))
3050             ;; get plurality on occurrence correct
3051             (when (> count 1) (beep))
3052             (message (concat
3053                       (number-to-string count)
3054                       " occurence"
3055                       (when (or (= count 0)
3056                                 (> count 1))
3057                         "s")))))
3058
3059          ;; check if the bibliography files exist.
3060          ((string= type "bibliography")
3061           (let* ((bibfile)
3062                  ;; object is the link you clicked on
3063                  (object (org-element-context))
3064                  (link-string (org-element-property :path object))
3065                  (link-string-beginning)
3066                  (link-string-end))
3067
3068             (save-excursion
3069               (goto-char (org-element-property :begin object))
3070               (search-forward link-string nil nil 1)
3071               (setq link-string-beginning (match-beginning 0))
3072               (setq link-string-end (match-end 0)))
3073
3074             ;; now if we have comma separated bibliographies
3075             ;; we find the one clicked on. we want to
3076             ;; search forward to next comma from point
3077             (save-excursion
3078               (goto-char link-string-beginning)
3079               (if (search-forward "," link-string-end 1 1)
3080                   (setq key-end (- (match-end 0) 1)) ; we found a match
3081                 (setq key-end (point)))) ; no comma found so take the point
3082             ;; and backward to previous comma from point
3083             (save-excursion
3084               (goto-char link-string-beginning)
3085               (if (search-backward "," link-string-beginning 1 1)
3086                   (setq key-beginning (+ (match-beginning 0) 1)) ; we found a match
3087                 (setq key-beginning (point)))) ; no match found
3088             ;; save the key we clicked on.
3089             (setq bibfile
3090                   (org-ref-strip-string
3091                    (buffer-substring key-beginning key-end)))
3092             (if (file-exists-p bibfile)
3093                 (message "%s exists." bibfile)
3094               (beep)
3095               (message "!!! %s NOT FOUND !!!" bibfile))))
3096          )))))
3097 #+END_SRC
3098
3099 * Aliases
3100 I like convenience. Here are some aliases for faster typing.
3101
3102 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
3103 (defalias 'oro 'org-ref-open-citation-at-point)
3104 (defalias 'orc 'org-ref-citation-at-point)
3105 (defalias 'orp 'org-ref-open-pdf-at-point)
3106 (defalias 'oru 'org-ref-open-url-at-point)
3107 (defalias 'orn 'org-ref-open-notes-at-point)
3108 (defalias 'ornr 'org-ref-open-notes-from-reftex)
3109
3110 (defalias 'orib 'org-ref-insert-bibliography-link)
3111 (defalias 'oric 'org-ref-insert-cite-link)
3112 (defalias 'orir 'org-ref-insert-ref-link)
3113 (defalias 'orsl 'org-ref-store-bibtex-entry-link)
3114
3115 (defalias 'orcb 'org-ref-clean-bibtex-entry)
3116 #+END_SRC
3117 * Helm interface
3118 [[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.
3119
3120 1. Make the default action to insert selected keys.
3121 2. Make open entry second action
3122 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
3123 (setq helm-source-bibtex
3124       '((name                                      . "BibTeX entries")
3125         (init                                      . helm-bibtex-init)
3126         (candidates                                . helm-bibtex-candidates)
3127         (filtered-candidate-transformer            . helm-bibtex-candidates-formatter)
3128         (action . (("Insert citation"              . helm-bibtex-insert-citation)
3129                    ("Show entry"                   . helm-bibtex-show-entry)
3130                    ("Open PDF file (if present)"   . helm-bibtex-open-pdf)
3131                    ("Open URL or DOI in browser"   . helm-bibtex-open-url-or-doi)
3132                    ("Insert reference"             . helm-bibtex-insert-reference)
3133                    ("Insert BibTeX key"            . helm-bibtex-insert-key)
3134                    ("Insert BibTeX entry"          . helm-bibtex-insert-bibtex)
3135                    ("Attach PDF to email"          . helm-bibtex-add-PDF-attachment)
3136                    ("Edit notes"                   . helm-bibtex-edit-notes)
3137                    ))))
3138 #+END_SRC
3139
3140 Now, let us define a function that inserts the cite links:
3141 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
3142 (defun helm-bibtex-format-org-ref (keys)
3143   "Insert selected KEYS as cite link. Append KEYS if you are on a link.
3144 Technically, this function should return a string that is inserted by helm. This function does the insertion and gives helm an empty string to insert. This lets us handle appending to a link properly.
3145
3146 In the helm-bibtex buffer, C-u will give you a helm menu to select a new link type for the selected entries.
3147
3148 C-u C-u will change the key at point to the selected keys.
3149 "
3150   (let* ((object (org-element-context)))
3151     (cond
3152      ;; case where we are in a link
3153      ((and (equal (org-element-type object) 'link)
3154            (-contains?
3155             org-ref-cite-types
3156             (org-element-property :type object)))
3157       (cond
3158        ;; no prefix. append keys
3159        ((equal helm-current-prefix-arg nil)
3160         (goto-char (org-element-property :end object))
3161         (while (looking-back " ") (backward-char))
3162         (insert (concat "," (mapconcat 'identity keys ","))))
3163        ;; double prefix, replace key at point
3164        ((equal helm-current-prefix-arg '(16))
3165         (setf (buffer-substring
3166                (org-element-property :begin object)
3167                (org-element-property :end object))
3168               (concat
3169                (replace-regexp-in-string
3170                 (car (org-ref-get-bibtex-key-and-file)) ; key
3171                 (mapconcat 'identity keys ",")          ; new keys
3172                 (org-element-property :raw-link object)
3173                 )
3174                ;; replace space at end to avoid collapsing into next word.
3175                " ")))
3176        (t
3177         (message "Not found"))))
3178
3179      ;; We are next to a link, and we want to append
3180      ;; next to a link means one character back is on a link.
3181      ((save-excursion
3182         (backward-char)
3183         (and (equal (org-element-type (org-element-context)) 'link)
3184              (-contains?
3185               org-ref-cite-types
3186               (org-element-property :type (org-element-context)))))
3187       (while (looking-back " ") (backward-char))
3188       (insert (concat "," (mapconcat 'identity keys ","))))
3189
3190      ;; insert fresh link
3191      (t
3192       ;;(message-box "fresh link")
3193       (insert
3194        (concat (if (equal helm-current-prefix-arg '(4))
3195                    (helm :sources `((name . "link types")
3196                                     (candidates . ,org-ref-cite-types)
3197                                     (action . (lambda (x) x))))
3198                org-ref-default-citation-link)
3199                ":"
3200                (s-join "," keys))))))
3201   ;; return empty string for helm
3202   "")
3203
3204 (setq helm-bibtex-format-citation-functions
3205       '((org-mode . helm-bibtex-format-org-ref)))
3206
3207 (defun org-ref-helm-insert-cite-link ()
3208   "org-ref function to use helm on the bibliography defined in the org-file."
3209   (interactive)
3210   (let ((helm-bibtex-bibliography (org-ref-find-bibliography)))
3211     (helm-bibtex)))
3212
3213 (require 'helm-bibtex)
3214
3215 ;; add our own fallback entries where we want them. These appear in reverse order of adding in the menu
3216 (setq helm-bibtex-fallback-options
3217       (-insert-at 1 '("Crossref" . "http://search.crossref.org/?q=%s") helm-bibtex-fallback-options))
3218
3219 (setq helm-bibtex-fallback-options
3220       (-insert-at
3221        1
3222        '("Scopus" . "http://www.scopus.com/scopus/search/submit/xadvanced.url?searchfield=TITLE-ABS-KEY(%s)")
3223        helm-bibtex-fallback-options))
3224
3225 (setq helm-bibtex-fallback-options
3226       (-insert-at 1 '("Open Web of Science" . (lambda () (browse-url "http://apps.webofknowledge.com")))
3227                   helm-bibtex-fallback-options))
3228 #+END_SRC
3229
3230 ** A helm click menu
3231 This code provides a helm interface to things you can do when you click on a citation link. This is an alternative to the minibuffer menu.
3232 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
3233 (defun org-ref-get-citation-string-at-point ()
3234   "Get a string of a formatted citation"
3235   (interactive)
3236   (let* ((results (org-ref-get-bibtex-key-and-file))
3237          (key (car results))
3238          (bibfile (cdr results)))
3239     (if bibfile
3240         (save-excursion
3241           (with-temp-buffer
3242             (insert-file-contents bibfile)
3243             (bibtex-search-entry key)
3244             (org-ref-bib-citation)))
3245       (beep)
3246       "!!! No entry found !!!" )))
3247
3248 (defun org-ref-cite-candidates ()
3249   "Generate the list of possible candidates for click actions on a cite link.
3250 Checks for pdf and doi, and add appropriate functions."
3251   (interactive)
3252   (let* ((results (org-ref-get-bibtex-key-and-file))
3253          (key (car results))
3254          (pdf-file (format (concat org-ref-pdf-directory "%s.pdf") key))
3255          (bibfile (cdr results))
3256          (url (save-excursion
3257                 (with-temp-buffer
3258                   (insert-file-contents bibfile)
3259                   (bibtex-search-entry key)
3260                   (bibtex-autokey-get-field "url"))))
3261          (doi (save-excursion
3262                 (with-temp-buffer
3263                   (insert-file-contents bibfile)
3264                   (bibtex-search-entry key)
3265                   ;; I like this better than bibtex-url which does not always find
3266                   ;; the urls
3267                   (bibtex-autokey-get-field "doi"))))
3268          (candidates `(("Quit" . org-ref-citation-at-point)
3269                        ("Open bibtex entry" . org-ref-open-citation-at-point))))
3270     ;; for some reason, when there is no doi or url, they are returned as "". I
3271     ;; prefer nil so we correct this here.
3272     (when (string= doi "") (setq doi nil))
3273     (when (string= url "") (setq url nil))
3274
3275     ;; Conditional pdf functions
3276     (if (file-exists-p pdf-file)
3277         (add-to-list
3278          'candidates
3279          '("Open pdf" . org-ref-open-pdf-at-point)
3280          t)
3281       (add-to-list
3282        'candidates
3283        '("Try to get pdf" . (lambda ()
3284                               (save-window-excursion
3285                                 (org-ref-open-citation-at-point)
3286                                 (bibtex-beginning-of-entry)
3287                                 (doi-utils-get-bibtex-entry-pdf))))
3288        t))
3289
3290
3291     (add-to-list
3292      'candidates
3293      '("Open notes" . org-ref-open-notes-at-point)
3294      t)
3295
3296     ;; conditional url and doi functions
3297     (when (or url doi)
3298       (add-to-list
3299        'candidates
3300        '("Open in browser" . org-ref-open-url-at-point)
3301        t))
3302
3303     (when doi
3304       (mapc (lambda (x)
3305               (add-to-list 'candidates x t))
3306             `(("WOS" . org-ref-wos-at-point)
3307               ("Related articles in WOS" . org-ref-wos-related-at-point)
3308               ("Citing articles in WOS" . org-ref-wos-citing-at-point)
3309               ("Google Scholar" . org-ref-google-scholar-at-point)
3310               ("Pubmed" . org-ref-pubmed-at-point)
3311               ("Crossref" . org-ref-crossref-at-point)
3312               )))
3313
3314     (add-to-list
3315      'candidates
3316      '("Copy formatted citation to clipboard" . org-ref-copy-entry-as-summary)
3317      t)
3318
3319     (add-to-list
3320      'candidates
3321      '("Copy key to clipboard" . (lambda ()
3322                                   (kill-new
3323                                    (car (org-ref-get-bibtex-key-and-file)))))
3324      t)
3325
3326     (add-to-list
3327      'candidates
3328      '("Copy bibtex entry to file" . org-ref-copy-entry-at-point-to-file)
3329      t)
3330
3331     (add-to-list
3332      'candidates
3333      '("Email bibtex entry and pdf" . (lambda ()
3334                   (save-excursion
3335                     (org-ref-open-citation-at-point)
3336                     (email-bibtex-entry))))
3337      t)
3338   ;; finally return a numbered list of the candidates
3339   (loop for i from 0
3340         for cell in candidates
3341         collect (cons (format "%2s. %s" i (car cell))
3342                       (cdr cell)))))
3343
3344
3345 (defvar org-ref-helm-user-candidates '()
3346   "List of user-defined candidates to act when clicking on a cite link.
3347 This is a list of cons cells '((\"description\" . action)). The action function should not take an argument, and should assume point is on the cite key of interest.
3348 ")
3349
3350 ;; example of adding your own function
3351 (add-to-list
3352  'org-ref-helm-user-candidates
3353  '("Example" . (lambda () (message-box "You did it!")))
3354  t)
3355
3356 (defun org-ref-cite-click-helm (key)
3357   "subtle points.
3358 1. get name and candidates before entering helm because we need the org-buffer.
3359 2. switch back to the org buffer before evaluating the action. most of them need the point and buffer."
3360   (interactive)
3361   (let ((name (org-ref-get-citation-string-at-point))
3362         (candidates (org-ref-cite-candidates))
3363         (cb (current-buffer)))
3364
3365     (helm :sources `(((name . ,name)
3366                       (candidates . ,candidates)
3367                       (action . (lambda (f)
3368                                   (switch-to-buffer cb)
3369                                   (funcall f))))
3370                      ((name . "User functions")
3371                       (candidates . ,org-ref-helm-user-candidates)
3372                       (action . (lambda (f)
3373                                   (switch-to-buffer cb)
3374                                   (funcall f))))
3375                      ))))
3376 #+END_SRC
3377
3378 #+RESULTS:
3379 : org-ref-cite-click-helm
3380
3381 * End of code
3382 #+BEGIN_SRC emacs-lisp :tangle org-ref.el
3383 (provide 'org-ref)
3384 #+END_SRC
3385
3386 * Build                                                            :noexport:
3387 This code will tangle the elisp code out to org-ref.el and load it.
3388
3389 [[elisp:(progn (org-babel-tangle) (load-file "org-ref.el"))]]
3390
3391 Alternatively you may use:
3392
3393 [[elisp:(org-babel-load-file "org-ref.org")]]