org-shift hooks for ordering citations

| categories: org-mode, bibtex | tags:

I wrote a function that sorts citations by year, but there might be a reason to order them some other way. Here we develop a method to use shift-arrow keys to do the ordering. We will need to write a function that gets the citations in a link, gets the key under point, and then swap with neighboring keys depending on the arrow pressed. It is trivial to get the key under point (org-ref-get-bibtex-key-under-cursor), and we saw before it is easy to get the keys in a link. Let us examine swapping elements of a list here. This is an old algorithm, we store the first value, replace it with the second value, and then set the second value.

(defun org-ref-swap-keys (i j keys)
 "swap the keys in a list with index i and j"
 (let ((tempi (nth i keys)))
   (setf (nth i keys) (nth j keys))
   (setf (nth j keys) tempi))
  keys)

(org-ref-swap-keys 2 3 '(1 2 3 4))
1 2 4 3

So, we need to get the keys in the link at point, the key at point, the index of the key at point, and then we can swap them, and reconstruct the link. Here is the function that does this, and that adds the hooks.

(defun org-ref-swap-citation-link (direction)
 "move citation at point in direction +1 is to the right, -1 to the left"
 (interactive)
 (let* ((object (org-element-context))	 
        (type (org-element-property :type object))
	(begin (org-element-property :begin object))
	(end (org-element-property :end object))
	(link-string (org-element-property :path object))
        (key (org-ref-get-bibtex-key-under-cursor))
	(keys (org-ref-split-and-strip-string link-string))
        (i (index key keys)) point) ;; defined in org-ref
   (if (> direction 0) ;; shift right
     (org-ref-swap-keys i (+ i 1) keys)
     (org-ref-swap-keys i (- i 1) keys))	
  (setq keys (mapconcat 'identity keys ","))
  ;; and replace the link with the sorted keys
  (cl--set-buffer-substring begin end (concat type ":" keys))
  ;; now go forward to key so we can move with the key
  (re-search-forward key) 
  (goto-char (match-beginning 0))))

(add-hook 'org-shiftright-hook (lambda () (org-ref-swap-citation-link 1)))
(add-hook 'org-shiftleft-hook (lambda () (org-ref-swap-citation-link -1)))
lambda nil (org-ref-swap-citation-link -1)

kanan-2008-in-situ,kanan-2009-cobal,lutterman-2009-self-healin,mcalpin-2010-epr-eviden,liu-2014-spect-studies!

That is it! Wow, not hard at all. Check out this video of the code in action: http://screencast.com/t/YmgA0fnZ1Ogl

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.6

Discuss on Twitter

Exporting citations with biblatex

| categories: org-mode | tags:

Table of Contents

This post illustrates that org-ref works with biblatex. We create a simple document and export it to pdf, and HTML for this post. We also explore how to modify the export behavior of a link. You should look at the org-source at the bottom to see the whole setup; it does not all export to either format.

We need a simple export type with no default packages to avoid the natbib packages I have setup in my default list. Here is the setup. Just run C-c C-c in the block to temporarily add this to your setup.

(add-to-list 'org-latex-classes
	     '("article-biblatex"
	       "\\documentclass{article}
 [NO-DEFAULT-PACKAGES]
 [PACKAGES]
 [EXTRA]"
	       ("\\section{%s}" . "\\section*{%s}")
	       ("\\subsection{%s}" . "\\subsection*a{%s}")
	       ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
	       ("\\paragraph{%s}" . "\\paragraph*{%s}")
	       ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

Add some citations andriotis-2014-infor,armiento-2014-high,biskup-2014-insul-ferrom-films,chemelewski-2014-amorp-feooh,chen-2014-inter-effec and then a single citation chen-2014-inter-effec.

and a complicated latex \cite[pre text][post text]{chen-2014-inter-effec}. Note this one will export to LaTeX fine, but not to HTML.

I would like to create a citation link that exports that way. We will do it by using a parseable syntax in the description of a link. We will have to temporarily define a new format function to achieve this. Here it is, just for the autocite command.

(defun org-ref-format-autocite (keyword desc format)
  (when (eq format 'latex)
    (concat "\\autocite"
	    (cond
	     ((string-match "::" desc)
	      (format "[%s][%s]" (car (setq results (split-string desc "::"))) (cadr results)))
	     (desc (format "[%s]" desc)))
	    (format "{%s}" keyword))))

This is the syntax:

a citation with post text: [[autocite:armiento-2014-high][post text]]

a citation with pre and post text:  [[autocite:andriotis-2014-infor][pre text::post text]]

a citation with post text: armiento-2014-high (the post text is not rendered in html).

a citation with pre and post text: andriotis-2014-infor (the pre/post text is not rendered in html).

The links in org-mode are no longer that readable when they are collapsed as descriptive links, but they are not too bad as literal links.

Here is the file and exporting-with-biblatex.pdf . One of those links is for the pdf, and one is for the HTML file.

1 Summary

org-ref seems to work pretty well with biblatex now.

We use a printbibliography link here. This exports to the latex command, or an html bibliography.

Bibliography

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.6

Discuss on Twitter

Creating bibliographies in other formats with org-ref

| categories: org-mode, bibtex | tags:

org-ref automatically generates bibliographies in LaTeX export, and it does a reasonable job automatically generating HTML bibliographies (ox-bibtex probably does this better, but it relies on an external program, whereas this approach is all elisp). Here we illustrate how to generate other formats, e.g. plain text, or org-mode formatted.

org-ref provides a convenient function that generates a bibliography entry for a key formatted according to the variable org-ref-bibliography-entry-format. This variable is a string that uses the reftex percent escapes to create an entry. The default is setup for an HTML entry like this:

  "%a, %t, <i>%j</i>, <b>%v(%n)</b>, %p (%y). <a href=\"%U\">link</a>. <a href=\"https://doi.org/%D\">doi</a>."

We can redefine it temporarily to get other formats. Here is an example of getting an org-formatted entry with some italics and bold text.

(let ((org-ref-bibliography-entry-format "%a, %t, /%j/, *%v(%n)*, %p (%y). [[%U][link]]. [[https://doi.org/%D][doi]]."))
(org-ref-get-bibtex-entry-citation "andriotis-2014-infor"))

"Andriotis, Mpourmpakis, , Broderick, Rajan, Datta, Somnath, Sunkara \& Menon, Informatics guided discovery of surface structure-chemistry relationships in catalytic nanoparticles, The Journal of Chemical Physics, 140(9), 094705 (2014). link . doi .

Now, we put some citations of various types in for water splitting mccrory-2013-bench-heter, CO2 capture alesi-2012-evaluat-primar, and microfluidic devices voicu-2014-microf-studies. We will convert these links to a bibliography shortly.

Next, we generate an org-formatted bibliography. We will create a bracketed label at the beginning of the entry, and the org-format after that. This is a functional enough bibliography to be useful I think, and it illustrates the ideas. We will do some light transforming to replace escaped & with regular & in the bibliography.

;; temorarily redefine the format
(let ((org-ref-bibliography-entry-format "%a, %t, /%j/, *%v(%n)*, %p (%y). [[%U][link]]. [[https://doi.org/%D][doi]]."))

  (mapconcat
   (lambda (key)
     (format "[%s] %s" key
	     (replace-regexp-in-string
	      "\\\\&"
	      "&" (org-ref-get-bibtex-entry-citation key))))
   (org-ref-get-bibtex-keys) "\n\n"))

[alesi-2012-evaluat-primar] Alesi & Kitchin, Evaluation of a Primary Amine-Functionalized Ion-Exchange Resin for \ce{CO_2} Capture, Industrial & Engineering Chemistry Research, 51(19), 6907-6915 (2012). link . doi .

[mccrory-2013-bench-heter] McCrory, Jung, Peters, Jonas & Jaramillo, Benchmarking Heterogeneous Electrocatalysts for the Oxygen Evolution Reaction, J. Am. Chem. Soc., 135(45), 16977–16987 (2013). link . doi .

[voicu-2014-microf-studies] Voicu, Abolhasani, Choueiri, Rachelle, Lestari, Seiler, , Menard, Greener, Guenther, Axel, Stephan & Kumacheva, Microfluidic Studies of \ce{CO_2} Sequestration by Frustrated {L}ewis Pairs, Journal of the American Chemical Society, 0(0), null (2014). [[][link]]. doi .

You can see some minor issues with the formatting, e.g. sometimes the link is empty, if there is no url in the bibtex entry. There is no easy way to fix that. The 0 and null values in the last entry are because that is an ASAP article, and that is what is in the bibtex entry. I do not try to expand the latex code, and do not plan to do that. I do not know why there appears to be a blank author in the last entry, or why the author full names are not used. Those are reftex issues and low priority to fix for me. They do not exist in the LaTeX export. The main point here is to get a reasonably useful bibliography that you can adapt as you want.

Bibliography

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.6

Discuss on Twitter

Exporting citations in html

| categories: org-mode | tags:

Now that org-ref works well for LaTeX, I want to explore a simple approach to exporting citations with a bibliography in html. This will enable me to put citations in blogposts, like this one armiento-2014-high and these ones daza-2014-carbon-dioxid,mehta-2014-ident-poten,suntivich-2014-estim-hybrid. We should be able to have the same citation in more than one place like this armiento-2014-high, but only have one entry in the bibliography. The bibliography should be sorted if we ask for it alesi-2012-evaluat-primar. I am curious to see this book citation: day-1995-scien-englis.

The first thing we need is a list of bibtex keys cited in this buffer.

(defun org-ref-get-bibtex-keys ()
  "return a list of unique keys in the buffer"
  (interactive)
  (let ((keys '()))
    (org-element-map (org-element-parse-buffer) 'link
      (lambda (link)
        (let ((plist (nth 1 link)))
          (when (-contains? org-ref-cite-types (plist-get plist ':type))
            (dolist
                (key
                 (org-ref-split-and-strip-string (plist-get plist ':path)))
              (when (not (-contains? keys key))
                (setq keys (append keys (list key)))))))))
    keys))

(org-ref-get-bibtex-keys)
armiento-2014-high daza-2014-carbon-dioxid mehta-2014-ident-poten suntivich-2014-estim-hybrid alesi-2012-evaluat-primar day-1995-scien-englis

Good. Now, we need to create an HTML string for the bibliography. For each key, we will create an unordered list of simple citations. Each citation will be a named anchor in html. Let us start with a function that takes a key, and generates the HTML for that entry.

(defun org-ref-get-bibtex-entry-html (key)
(interactive)

 (let ((org-ref-bibliography-files (org-ref-find-bibliography))
       (cb (current-buffer))
       (file) (entry))

   (setq file (catch 'result
                (loop for file in org-ref-bibliography-files do
                      (message "looking for %s in %s" key file)
                      (if (org-ref-key-in-file-p key (file-truename file))
                          (throw 'result file)
                        (message "%s not found in %s" key (file-truename file))))))
   (set-buffer (find-file-noselect file))
   (prog1
       (bibtex-search-entry key nil 0)
     (setq entry (org-ref-bib-citation))
     (set-buffer cb))

   (format "<li><a name=\"#%s\">[%s] %s<\\a><li>" key key entry)))

(org-ref-get-bibtex-entry-html "mehta-2014-ident-poten")
<li><a name="#mehta-2014-ident-poten">[mehta-2014-ident-poten] Mehta, Prateek and Salvador, Paul A. and Kitchin,  John R., "Identifying Potential \ce{BO_2} Oxide Polymorphs for  Epitaxial Growth Candidates", ACS Applied Materials \& Interfaces, 0:null (2014)<\a><li>

That looks excellent. Now we simply map that function over the list of keys.

(defun org-ref-get-html-bibliography ()
(interactive)
(let ((keys (org-ref-get-bibtex-keys)))
(when keys
(concat "<h1>Bibliography</h1>
<ul>"
(mapconcat (lambda (x) (org-ref-get-bibtex-entry-html x)) keys "\n")
"\n</ul>"))))

(org-ref-get-html-bibliography)

<h1>Bibliography</h1> <ul><li><a name="#armiento-2014-high">[armiento-2014-high] Armiento, R. and Kozinsky, B. and Hautier, G. and Fornari, M. and Ceder, G., "High-throughput screening of perovskite alloys for piezoelectric performance and thermodynamic stability", Phys. Rev. B, 89:134103 (2014)<\a><li> <li><a name="#daza-2014-carbon-dioxid">[daza-2014-carbon-dioxid] Daza, Yolanda A. and Kent, Ryan A. and Yung, Matthew M. and Kuhn, John N., "Carbon Dioxide Conversion by Reverse Water-Gas Shift Chemical Looping on Perovskite-Type Oxides", Industrial \& Engineering Chemistry Research, 53:5828-5837 (2014)<\a><li> <li><a name="#mehta-2014-ident-poten">[mehta-2014-ident-poten] Mehta, Prateek and Salvador, Paul A. and Kitchin, John R., "Identifying Potential \ce{BO_2} Oxide Polymorphs for Epitaxial Growth Candidates", ACS Applied Materials \& Interfaces, 0:null (2014)<\a><li> <li><a name="#suntivich-2014-estim-hybrid">[suntivich-2014-estim-hybrid] Suntivich, Jin and Hong, Wesley T. and Lee, Yueh-Lin and Rondinelli, James M. and Yang, Wanli and Goodenough, John B. and Dabrowski, Bogdan and Freeland, John W. and Shao-Horn, Yang, "Estimating Hybridization of Transition Metal and Oxygen States in Perovskites from O K-edge X-ray Absorption Spectroscopy", The Journal of Physical Chemistry C, 118:1856-1863 (2014)<\a><li> <li><a name="#alesi-2012-evaluat-primar">[alesi-2012-evaluat-primar] Alesi, W. Richard and Kitchin, John R., "Evaluation of a Primary Amine-Functionalized Ion-Exchange Resin for \ce{CO_2} Capture", Industrial \& Engineering Chemistry Research, 51:6907-6915 (2012)<\a><li> <li><a name="#day-1995-scien-englis">[day-1995-scien-englis] Robert A. Day, "Scientific English: A Guide for Scientists and Other Profesionals", , : (1995)<\a><li> </ul> <h1>Bibliography</h1> <ul><li><a name="#armiento-2014-high">[armiento-2014-high] Armiento, R. and Kozinsky, B. and Hautier, G. and Fornari, M. and Ceder, G., "High-throughput screening of perovskite alloys for piezoelectric performance and thermodynamic stability", Phys. Rev. B, 89:134103 (2014)<\a><li> <li><a name="#daza-2014-carbon-dioxid">[daza-2014-carbon-dioxid] Daza, Yolanda A. and Kent, Ryan A. and Yung, Matthew M. and Kuhn, John N., "Carbon Dioxide Conversion by Reverse Water-Gas Shift Chemical Looping on Perovskite-Type Oxides", Industrial \& Engineering Chemistry Research, 53:5828-5837 (2014)<\a><li> <li><a name="#mehta-2014-ident-poten">[mehta-2014-ident-poten] Mehta, Prateek and Salvador, Paul A. and Kitchin, John R., "Identifying Potential \ce{BO_2} Oxide Polymorphs for Epitaxial Growth Candidates", ACS Applied Materials \& Interfaces, 0:null (2014)<\a><li> <li><a name="#suntivich-2014-estim-hybrid">[suntivich-2014-estim-hybrid] Suntivich, Jin and Hong, Wesley T. and Lee, Yueh-Lin and Rondinelli, James M. and Yang, Wanli and Goodenough, John B. and Dabrowski, Bogdan and Freeland, John W. and Shao-Horn, Yang, "Estimating Hybridization of Transition Metal and Oxygen States in Perovskites from O K-edge X-ray Absorption Spectroscopy", The Journal of Physical Chemistry C, 118:1856-1863 (2014)<\a><li> </ul>

That is basically all we need. The citation links will export as hrefs to these named targets, so they should work fine. All we need to do is modify the blogofile code a bit to use this, and add those functions to org-ref, and we should get a bibliography in our blogposts.

Bibliography

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.6

Discuss on Twitter

Using org-ref for citations and references

| categories: org-mode, emacs | tags:

org-ref is an emacs-lisp module to handle bibliographic citations, and references to figures, tables and sections in org-mode. It was written first for use in org-mode, and for reasonable export to LaTeX. It does not work well for any other export (eg HTML) for now. The goal of org-ref is to make it easy to add citations, and that the citations be useful, clickable links. Below, I illustrate some of those features.

1 Installation

You can get the source here: https://github.com/jkitchin/jmax/blob/master/org-ref.org . This is an org-mode file, and you can load it with

(org-babel-load-file "org-ref.org")

That should be all you need for basic usage.

2 Basic usage for citations

org-ref was written with bibtex in mind. We will discuss customization to use biblatex later.

The first thing you should do is add a bibliography link to your document. This link is usually put at the end of the document, where you want the bibliography to be printed in a LaTeX export. Use the filename of the bibliography with its extension in the link, and you can use multiple files if they are separated by commas. The bibliography link is clickable, and it will open the bibliography that you clicked on. Depending on the LaTeX class you are exporting to, you may also need to set a bibliographystyle.

Out of the box, org-ref binds the key "C-c ]" to insert a citation. That key runs the command org-ref-insert-cite-link, which will prompt you for a regular expression to search your bibliographies for. The search is done using reftex, so you can mark several entries at once, and they will be added as a citation link. The actual kind of link used is dependent on the value of org-ref-default-citation-link, which defaults to cite.

If your cursor is on a citation link, or at the end of the link, you can run the command again to append new citations to the link. The new entries are separated by commas. The links are clickable, and when you click on them you will see a message in the minibuffer with the citation, and options to open the entry, open a pdf (if you have it), open the url (if the entry has one), or to open notes about the entry. You get this menu for the entry that you clicked on.

If you want a different type of citation, type C-u C-c ]. You will be prompted for a format, and you can choose a different type of link format. Most bibtex formats are supported, and some biblatex formats are supported.

3 Basic usage for references

The other use of org-ref is for references to labels in your document. You can put labels in figure and table captions, and then reference them in your document. The label link is clickable, and when you click on it there will be a message in the minibuffer telling you how many labels of that name were found (it should be one).

Table 1: An uninteresting table. ()
0 3
4 7

You can then refer to Table (tab-boring). The ref links are also clickable, and they take you to the spot where the label is defined. You can enter ref links with completion. Press C-c C-l, type ref, press enter, and then press tab. You will get a list of the labels defined in the buffer you can choose from. There are many things you can make a ref to including a tblname, a label link, an explicit \label{}, and an org-mode #+label: line. (tab-boring)

There is an eqref link that is used for equations. You must use LaTeX labels in the equation for this.

\[e^x = 4 \label{eq-exp} \]

You can see in (eq-exp) the problem to solve.

4 Miscellaneous links

There are two link types for generating a LateX list of tables and list of figures. These links are clickable, and they open a temporary buffer with a list of the tables or figures that you can click on. They export to \listoftables and \listoffigures

You can run these as commands, org-ref-list-of-tables and org-ref-list-of-figures if you do not want a list of those things in your exported document.

5 Customization

5.1 Default bibliography, pdf directory,

This is an optional configuration, but it is handy to define a default bibliography so that you can add citations to an org-file without defining a bibliography link. I store all pdfs of bibtex entries in the directory defined by org-ref-pdf-directory, and by the name of the bibtex entry label. This enables org-ref to open the pdf if it can find it. The notes file is optional, I create org-entries for each bibtex entry, which I have experimented with various ways of organizing them with tags, and in topical headings.

(setq org-ref-bibliography-notes "~/Dropbox/bibliography/notes.org"
      org-ref-default-bibliography '("~/Dropbox/bibliography/references.bib")
      org-ref-pdf-directory "~/Dropbox/bibliography/bibtex-pdfs/")

5.2 New key binding

The default key binding to insert a citation is C-c ]. I chose that because I do not like pressing shift to get ). However, this key binding usurps an org-mode agenda file command. To change this, set this variable

(setq org-ref-insert-cite-key "C-c )")
  • You may have to restart emacs to get C-c ] back.

5.3 Default link type

If you use another citation type alot, you may change the default link type. For example, you may prefer autocite links by default. Just set it like this:

(setq org-ref-default-citation-link "autocite")

5.4 New citation types

There are so many citation types between bibtex and biblatex. I did not try to add them all. You can add new citation links yourself in your init file. Here, we add a new cite link called citez, and assign a reftex menu key of z to it. This function automatically adds the new link to org-mode, with the citation menu functionality, creates the completion function, and adds the citation to the list of known types.

(org-ref-define-citation-link "citez" ?z)

(org-ref-define-citation-link "citeauthorfull" ?F) citeauthorfull:hautier-2012-accur

hautier-2012-accur

It is assumed that this will be exported as \citez[optional stuff]{label}. If you need more flexibility than that, you will have to define everything manually.

For example, the original cite link was defined like this.

(defun org-ref-cite-link-format (keyword desc format)
   (cond
    ((eq format 'html) (format "(<cite>%s</cite>)" path))
    ((eq format 'latex)
     (concat "\\cite" (when desc (format "[%s]" desc)) "{"
             (mapconcat (lambda (key) key) (org-ref-split-and-strip-string keyword) ",")
             "}"))))

(org-add-link-type
 "cite"
 'org-ref-cite-onclick-minibuffer-menu ;; clicking function
 'org-ref-cite-link-format) ;; formatting function

You should also add your new citation type to the list of org-ref-cite-types.

6 Summary

This covers most of the basic org-ref functionality. There are also several utility functions for interacting with org-buffers and bibtex files that will be described later.

See http://screencast.com/t/bxfafVydE for a screencast of using org-ref.

http://screencast.com/t/bxfafVydE

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.7c

Discuss on Twitter
« Previous Page -- Next Page »