README.org

   1 #+TITLE: org-ref: citations, cross-references, indexes, glossaries and bibtex utilities for org-mode
   2
   3 #+BEGIN_HTML
   4 <a href="https://travis-ci.org/jkitchin/org-ref"><img src="https://travis-ci.org/jkitchin/org-ref.svg?branch=master"></a>
   5 #+END_HTML
   6
   7 See http://www.youtube.com/watch?v=Zya8SfmCtFA and https://www.youtube.com/watch?v=JyvpSVl4_dg for examples of org-ref in action.
   8
   9 [[./org-ref.org]] contains all documentation and installation instructions.
  10
  11 [[./doi-utils.org]] contains functions for downloading bibtex entries from  a DOI, and redefines the org-mode doi link so it has more functionality.
  12
  13 [[./jmax-bibtex.el]] contains some utility functions:
  14
  15 1. jmax-bibtex runs a menu command with actions to run on a bibtex entry including looking up the doi for the entry in a variety of places, e.g. web of science related/citing articles, Google Scholar, Pubmed, and crossref, or opening a PDF associated with the entry.
  16
  17 2. Bind M-n/M-p to next/previous bibtex entry.
  18
  19 3. Sentence/title casing the title of a bibtex entry
  20
  21 4. Function to replace non-ascii characters in bibtex entries
  22
  23 5. Functions to replace journal names with @string entries, and corresponding short/long names.
  24
  25 To install this, add the org-ref repo directory to your load-path, and
  26
  27 #+BEGIN_SRC emacs-lisp
  28 (add-to-list 'load-path "path-to-org-ref")
  29 (require 'jmax-bibtex)
  30 #+END_SRC
  31
  32 * Installation
  33 You should clone this repository somewhere.
  34
  35 Here is how I load org-ref. This code is in my init.el file.
  36
  37 #+BEGIN_SRC emacs-lisp
  38 ;; remember this directory
  39 (defconst starter-kit-dir (file-name-directory (or load-file-name (buffer-file-name)))
  40     "Directory where the starterkit is installed.")
  41
  42 ;;;;;;; org path for loadable org-files
  43 (defvar org-load-path
  44   (list (file-name-as-directory
  45          (expand-file-name "org" starter-kit-dir)))
  46   "List of directories to find org-files that `org-babel-load-file' can load code from.")
  47
  48 (defun org-require (feature)
  49   "Load a FEATURE from an org-file.
  50 FEATURE is a symbol, and it is loaded from an org-file by the name of FEATURE.org, that is in the `org-load-path'.  The FEATURE is loaded from `org-babel-load-file'."
  51   (let ((org-file (concat (symbol-name feature) ".org"))
  52         (path))
  53
  54     ;; find the org-file
  55     (catch 'result
  56       (loop for dir in org-load-path do
  57             (when (file-exists-p
  58                    (setq path
  59                          (expand-file-name
  60                           org-file
  61                           dir)))
  62               (throw 'result path))))
  63     (let ((default-directory (file-name-directory path)))
  64       (org-babel-load-file path))))
  65
  66 ;; https://github.com/jkitchin/org-ref
  67 ;; for loading org-files
  68 (add-to-list 'org-load-path
  69              (expand-file-name "org-ref" starter-kit-dir))
  70
  71 ;; for loading emacs-lisp files
  72 (add-to-list 'load-path
  73              (expand-file-name "org-ref" starter-kit-dir))
  74
  75 (org-require 'org-ref)
  76 (org-require 'doi-utils)
  77 (org-require 'pubmed)
  78 (require 'jmax-bibtex)
  79 #+END_SRC
  80
  81
  82 You should set these variables. Here is an example of how mine are set in an init.el file.
  83 #+BEGIN_SRC emacs-lisp
  84 (setq reftex-default-bibliography '("~/Dropbox/bibliography/references.bib"))
  85
  86 ;; see org-ref for use of these variables
  87 (setq org-ref-bibliography-notes "~/Dropbox/bibliography/notes.org"
  88       org-ref-default-bibliography '("~/Dropbox/bibliography/references.bib")
  89       org-ref-pdf-directory "~/Dropbox/bibliography/bibtex-pdfs/")
  90 #+END_SRC
  91
  92 You may want to set some convenient keys for working in your bibtex file:
  93
  94 #+BEGIN_SRC emacs-lisp
  95 (global-set-key [f10] 'org-ref-open-bibtex-notes)
  96 (global-set-key [f11] 'org-ref-open-bibtex-pdf)
  97 (global-set-key [f12] 'org-ref-open-in-browser)
  98 #+END_SRC