search

jkitchin / org-ref

org-mode modules for citations, cross-references, bibliographies in org-mode and useful bibtex tools to go with it.
GNU General Public License v3.0
1.35k stars 242 forks source link

readme

-- org-edit-src-content-indentation: 0; --

+TITLE: org-ref: citations, cross-references, indexes, glossaries and bibtex utilities for org-mode

+BEGIN_html

MELPA

MELPA Stable

+END_html

Overview of org-ref for export to PDF via LaTeX.

+BEGIN_html

+END_html

=org-ref= makes it easy to insert citations, cross-references, indexes and glossaries as hyper-functional links into org files. The links are fontified so you can tell them apart from other links, and each link is clickable to access functions like opening a pdf, notes or url associated with the link. Each link also can be exported to LaTeX to build a PDF. For citations, export to other formats is supported by [[https://github.com/andras-simonyi/citeproc-el][citeproc]] for high quality export to HTML, markdown, plain text, or stand-alone (i.e. independent of a bibtex file) LaTeX. For a full explanation of the features in org-ref see [[./org-ref.org]].

** What about org-cite?

A new syntax for citations was added in org-mode version 9.5. org-cite is designed to be very modular, with different processors for inserting, activating, following and exporting citations. It also uses a different cite/style type of syntax. It does not handle cross-references or provide any of the bibtex tools that are available in org-ref. The main advantages of org-cite include:

  1. It is built in to org-mode now
  2. It is highly modular, so you can configure it any way you want

It is possible to use org-cite for citation support instead of the org-ref citation links. You can configure the ~org-ref-insert-cite-function~ variable to use ~org-cite-insert~. This will then use your org-cite configured [[https://orgmode.org/manual/Citation-handling.html][processors]] to insert, follow, activate and export citations. You should avoid mixing org-ref citation links and org-cite citations. They are handled independently.

+BEGIN_SRC emacs-lisp

(setq org-ref-insert-cite-function (lambda () (org-cite-insert nil)))

+END_SRC

You can still use the org-ref cross-reference links if you use org-cite citations. These packages should be able to co-exist without issue.

Here are some annotated images of basic insertion of citations in org-mode. These are with the ivy backend.

+attr_org: :width 800

[[./screenshots/introduction.png]]

This what an inserted link looks like.

+attr_org: :width 800

+caption: Tooltip on an inserted link.

[[./screenshots/cite-tooltip.png]]

The links in org-ref are hyper-functional (that means they have more than one action associated with them). They do things when your cursor is on them, or you click on them, and when the mouse hovers over them.

Here is an example of a menu of actions you get when you click on a cite link.

+attr_org: :width 800

+caption: Menu of actions from clicking on a cite link.

[[./screenshots/functional-cite-links.png]]

Here is a cross-reference link.

+attr_org: :width 800

+caption: Functional cross-reference link.

[[./screenshots/functional-links-2.png]]

org-ref can analyze your org-file and tell you about it, for example if there are bad citations, multiply defined labels, bad reference links, missing bibliography files, etc... You can select each one and it will jump to the location to help you fix it.

+attr_org: :width 800

+caption: Screenshot from the org-ref analysis command.

[[./screenshots/org-ref-analysis.png]]

** Package installation via Melpa

org-ref has been added to Melpa. This is the recommended way to install org-ref as it should also install almost all the dependencies. It also should reflect what is in the master branch in the Github repo (https://github.com/jkitchin/org-ref).

+BEGIN_SRC emacs-lisp

(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t) (package-initialize)

+END_SRC

Then, you should be able to do M-x package-list-packages, find org-ref and install it, or with

+BEGIN_SRC emacs-lisp

(use-package org-ref)

+END_SRC

Two exceptions to packages that are /not/ installed are helm, helm-bibtex, ivy and ivy-bibtex. You have to install those yourself. This change is to accommodate people who just can not stand having those packages installed if they do not use them.

** Installation via github

Make sure all the [[https://github.com/jkitchin/org-ref/blob/master/org-ref.el#L9][dependencies]] are installed. Then clone this repo, add it to your load-path.

+BEGIN_SRC sh

git clone https://github.com/jkitchin/org-ref.git

+END_SRC

Add this to your .emacs file and see the [[*Configuration]] section.

** Configuration

Version 3 has eliminated all the =org-ref-*= variables, and instead uses analogous variables defined in =bibtex-completion=.

There are some working configurations at https://github.com/jkitchin/org-ref/tree/master/melpa.

Here is how I have these variables set for myself.

+BEGIN_SRC emacs-lisp

(setq bibtex-completion-bibliography '("~/Dropbox/emacs/bibliography/references.bib" "~/Dropbox/emacs/bibliography/dei.bib" "~/Dropbox/emacs/bibliography/master.bib" "~/Dropbox/emacs/bibliography/archive.bib") bibtex-completion-library-path '("~/Dropbox/emacs/bibliography/bibtex-pdfs/") bibtex-completion-notes-path "~/Dropbox/emacs/bibliography/notes/" bibtex-completion-notes-template-multiple-files "* ${author-or-editor}, ${title}, ${journal}, (${year}) :${=type=}: \n\nSee [[cite:&${=key=}]]\n"

bibtex-completion-additional-search-fields '(keywords)
bibtex-completion-display-formats
'((article       . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*} ${journal:40}")
  (inbook        . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*} Chapter ${chapter:32}")
  (incollection  . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*} ${booktitle:40}")
  (inproceedings . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*} ${booktitle:40}")
  (t             . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*}"))
bibtex-completion-pdf-open-function
(lambda (fpath)
  (call-process "open" nil 0 nil fpath)))

+END_SRC

I also find these settings helpful for automatically generating bibtex keys.

+BEGIN_SRC emacs-lisp

(require 'bibtex)

(setq bibtex-autokey-year-length 4 bibtex-autokey-name-year-separator "-" bibtex-autokey-year-title-separator "-" bibtex-autokey-titleword-separator "-" bibtex-autokey-titlewords 2 bibtex-autokey-titlewords-stretch 1 bibtex-autokey-titleword-length 5)

(define-key bibtex-mode-map (kbd "H-b") 'org-ref-bibtex-hydra/body)

+END_SRC

After you set those options, you have these options to load org-ref.

If you prefer ivy-bibtex, you should use this. It requires =ivy-bibtex=, but this is not currently automatically installed by MELPA.

+BEGIN_SRC emacs-lisp

(require 'org-ref) (require 'org-ref-ivy)

+END_SRC

If you prefer helm, you can instead use this. This uses code from =helm-bibtex= for citation insertion. It requires helm-bibtex, but this is not currently automatically installed by MELPA.

+BEGIN_SRC emacs-lisp

(require 'org-ref) (require 'org-ref-helm)

+END_SRC

org-ref no longer binds keyboard shortcuts for you. You have some options here. To get the behavior of version 2, use this in your init file:

+BEGIN_SRC emacs-lisp

(define-key org-mode-map (kbd "C-c ]") 'org-ref-insert-link)

+END_SRC

or

+BEGIN_SRC emacs-lisp

(define-key org-mode-map (kbd "C-c ]") 'org-ref-insert-link-hydra/body)

+END_SRC

You can bind each insert command separately if you want after the library is loaded like this. Here I use the hyper key as a modifier, but you can choose anything you find convenient.

+BEGIN_SRC emacs-lisp

(define-key org-mode-map (kbd "H-c") org-ref-insert-cite-function) (define-key org-mode-map (kbd "H-r") org-ref-insert-ref-function) (define-key org-mode-map (kbd "H-l") org-ref-insert-label-function)

+END_SRC

If you use some other completing-read backend like selectrum, or ido, then for a bare-bones library that uses vanilla completing-read, you can simply require 'org-ref. I don't find the vanilla completing-read setup that useful on its own as it doesn't do candidate narrowing or fuzzy matching without some external configuration. It is an option if you want it though.

+BEGIN_SRC emacs-lisp

(require 'org-ref)

+END_SRC

You can use any other library that inserts links you want. Some of these include:

  1. citar (https://github.com/bdarcus/citar#configuration)
  2. ebib (https://joostkremers.github.io/ebib/)
  3. You could even roll your own insert functions.

** LaTeX/PDF export

If you plan to build PDF files via LaTeX you need to make sure that org-latex-pdf-process is set to process the bibliography (using bibtex or biblatex). Here is one example of how to do that (see [[./org-ref.org::*LaTeX export]] for other alternatives).

+BEGIN_SRC emacs-lisp

(setq org-latex-pdf-process (list "latexmk -shell-escape -bibtex -f -pdf %f"))

+END_SRC

Go forth and citate.

Note many of these have been renamed with an org-ref prefix.

The following libraries are not loaded by default. They may be useful in specialist cases:

The following libraries are still included, but they have been unreliable and are no longer recommended for use:

For more information, see the [[https://github.com/jkitchin/org-ref/blob/master/org-ref.org][org-ref manual]], or preferably use ~M-x org-ref-help~ in emacs.

Please report errors here: [[https://github.com/jkitchin/org-ref/issues][issues]].

I would like to thank the [[https://github.com/jkitchin/org-ref/graphs/contributors][contributors]] to org-ref, and everyone who has filed an [[https://github.com/jkitchin/org-ref/issues][issue]], or asked about org-ref on the [[http://orgmode.org/community.html][org-mode Mailing list]].

If you are interested in making a contribution to org-ref, I encourage you to reach out to me to discuss the idea first. The issue handler is a great way to do that, so that others can offer opinions too.