-#+DATE: April 29, 2014
-
-* Introduction
-
-This document is an experiment at creating a literate program to provide similar features as reftex for org-mode referencing. These features include:
-
-1. using completion to create links
-2. storing links to places,
-3. Clickable links that do useful things
-4. Exportable links to LaTeX
-5. Utility functions for dealing with bibtex files and org-files
-
-Some additional features include
-1. Get minibuffer messages for the cite/ref/label link under point
-
-With helm integration (default) you can:
-
-1. C-c ] to insert a citation link
- in helm-bibtex
- - Enter to insert or append citation(s)
- - C-u Enter to insert an alternative cite link
- - C-u C-u Enter to replace the citation at point
-2. C-u C-c ] to insert a ref link with helm completion
-3. C-u C-u C-c ] to insert a label with completion
-4. M-x org-ref to get a helm completion buffer with link checks, utilities and export options
-
-** Header
-#+BEGIN_SRC emacs-lisp :tangle org-ref.el
-;;; org-ref.el --- setup bibliography, cite, ref and label org-mode links.
-
-;; Copyright(C) 2014 John Kitchin
-
-;; Author: John Kitchin <jkitchin@andrew.cmu.edu>
-;; This file is not currently part of GNU Emacs.
-
-;; This program is free software; you can redistribute it and/or
-;; modify it under the terms of the GNU General Public License as
-;; published by the Free Software Foundation; either version 2, or (at
-;; your option) any later version.
-
-;; This program is distributed in the hope that it will be useful, but
-;; WITHOUT ANY WARRANTY; without even the implied warranty of
-;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-;; General Public License for more details.
-
-;; You should have received a copy of the GNU General Public License
-;; along with this program ; see the file COPYING. If not, write to
-;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-;; Boston, MA 02111-1307, USA.
-
-;;; Commentary:
-;;
-;; Lisp code to setup bibliography cite, ref and label org-mode links. also
-;; sets up reftex and helm for org-mode citations. The links are clickable and
-;; do things that are useful. You should really read org-ref.org for details.
-;;
-;; Package-Requires: ((dash) (helm) (helm-bibtex))
-#+END_SRC
-
-** requires
-The only external require is reftex-cite
-
-#+BEGIN_SRC emacs-lisp :tangle org-ref.el
-(require 'reftex-cite)
-(require 'dash)
-(require 'helm)
-(require 'helm-config)
-(require 'helm-bibtex)
-#+END_SRC
-
-** Custom variables
-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.
-
-#+BEGIN_SRC emacs-lisp :tangle org-ref.el
-(defgroup org-ref nil
- "customization group for org-ref")
-
-(defcustom org-ref-bibliography-notes
- nil
- "filename to where you will put all your notes about an entry in
- the default bibliography."
- :type 'file
- :group 'org-ref)
-
-(defcustom org-ref-default-bibliography
- nil
- "list of bibtex files to search for. You should use full-paths for each file."
- :type '(repeat :tag "List of bibtex files" file)
- :group 'org-ref)
-
-(defcustom org-ref-pdf-directory
- nil
- "directory where pdfs are stored by key. put a trailing / in"
- :type 'directory
- :group 'org-ref)
-
-(defcustom org-ref-default-citation-link
- "cite"
- "The default type of citation link to use"
- :type 'string
- :group 'org-ref)
-
-(defcustom org-ref-insert-cite-key
- "C-c ]"
- "Keyboard shortcut to insert a citation."
- :type 'string
- :group 'org-ref)
-
-(defcustom org-ref-bibliography-entry-format
- '(("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>.")
-
- ("book" . "%a, %t, %u (%y).")
-
- ("proceedings" . "%e, %t in %S, %u (%y).")
-
- ("inproceedings" . "%a, %t, %p, in %b, edited by %e, %u (%y)"))
-
- "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."
- :type 'string
- :group 'org-ref)
-
-(defcustom org-ref-open-notes-function
- (lambda ()
- (org-show-entry)
- (show-branches)
- (show-children)
- (org-cycle '(64))
- ;;(org-tree-to-indirect-buffer)
- (outline-previous-visible-heading 1)
- (recenter-top-bottom 0))
- "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"
-:type 'function
-:group 'org-ref)
-
-
-(defcustom org-ref-open-pdf-function
- 'org-ref-open-pdf-at-point
-"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'."
- :type 'function
- :group 'org-ref)
-
-
-(defcustom org-ref-insert-cite-function
- 'org-ref-helm-insert-cite-link
- "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."
- :type 'function
- :group 'org-ref)
-
-
-(defcustom org-ref-cite-onclick-function
- 'org-ref-cite-click-helm
- "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."
- :type 'function
- :group 'org-ref)
-
-(defcustom org-ref-show-citation-on-enter t
- "If non-nil add a hook function to show the citation summary in
- the minibuffer just by putting the cursor in a link"
- :group 'org-ref)
-
-#+END_SRC
-
-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.
-
-#+BEGIN_SRC emacs-lisp :tangle org-ref.el
-(defcustom org-ref-cite-types
- '("cite" "nocite" ;; the default latex cite commands
- ;; natbib cite commands, http://ctan.unixbrain.com/macros/latex/contrib/natbib/natnotes.pdf
- "citet" "citet*" "citep" "citep*"
- "citealt" "citealt*" "citealp" "citealp*"
- "citenum" "citetext"
- "citeauthor" "citeauthor*"
- "citeyear" "citeyear*"
- "Citet" "Citep" "Citealt" "Citealp" "Citeauthor"
- ;; biblatex commands
- ;; http://ctan.mirrorcatalogs.com/macros/latex/contrib/biblatex/doc/biblatex.pdf
- "Cite"
- "parencite" "Parencite"
- "footcite" "footcitetext"
- "textcite" "Textcite"
- "smartcite" "Smartcite"
- "cite*" "parencite*" "supercite"
- "autocite" "Autocite" "autocite*" "Autocite*"
- "Citeauthor*"
- "citetitle" "citetitle*"
- "citedate" "citedate*"
- "citeurl"
- "fullcite" "footfullcite"
- ;; "volcite" "Volcite" cannot support the syntax
- "notecite" "Notecite"
- "pnotecite" "Pnotecite"
- "fnotecite"
- ;; multicites. Very limited support for these.
- "cites" "Cites" "parencites" "Parencites"
- "footcites" "footcitetexts"
- "smartcites" "Smartcites" "textcites" "Textcites"
- "supercites" "autocites" "Autocites"
- ;; for the bibentry package
- "bibentry"
- )
- "List of citation types known in org-ref"
- :type '(repeat :tag "List of citation types" string)
- :group 'org-ref)
-#+END_SRC
-
-We need a hook variable to store user-defined bibtex entry cleaning functions
-#+BEGIN_SRC emacs-lisp :tangle org-ref.el
-(defcustom org-ref-clean-bibtex-entry-hook nil
- "Hook that is run in org-ref-clean-bibtex-entry. The functions should take no arguments, and operate on the bibtex entry at point."
- :group 'org-ref
- :type 'hook)
-#+END_SRC
-
-** Program variables
-#+BEGIN_SRC emacs-lisp :tangle org-ref.el
-(defvar org-ref-bibliography-files
- nil
- "variable to hold bibliography files to be searched")
-#+END_SRC
-
-** org-mode / reftex setup
-
-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.
-
-#+BEGIN_SRC emacs-lisp :tangle org-ref.el
-(require 'reftex)
-(defun org-mode-reftex-setup ()
- (and (buffer-file-name)
- (file-exists-p (buffer-file-name))
- (global-auto-revert-mode t)
- ;; I do not remember why I put this next line in. It doesn't
- ;; work for org-files. Nothing very bad happens, but it gives
- ;; an annoying error. Commenting it out for now.
- ;(reftex-parse-all
- )
- (make-local-variable 'reftex-cite-format)
- (setq reftex-cite-format 'org))
-
-;; define key for inserting citations
-(define-key org-mode-map
- (kbd org-ref-insert-cite-key)
- org-ref-insert-cite-function)
-
-(add-hook 'org-mode-hook 'org-mode-reftex-setup)
-
-(eval-after-load 'reftex-vars
- '(progn
- (add-to-list 'reftex-cite-format-builtin
- '(org "Org-mode citation"
- ((?\C-m . "cite:%l") ; default
- (?d . ",%l") ; for appending
- (?a . "autocite:%l")
- (?t . "citet:%l")
- (?T . "citet*:%l")
- (?p . "citep:%l")
- (?P . "citep*:%l")
- (?h . "citeauthor:%l")
- (?H . "citeauthor*:%l")
- (?y . "citeyear:%l")
- (?x . "citetext:%l")
- (?n . "nocite:%l")
- )))))
-#+END_SRC
-
-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.
-
-#+BEGIN_SRC emacs-lisp :tangle no
-;; add new format
-(setf (nth 2 (assoc 'org reftex-cite-format-builtin))
- (append (nth 2 (assoc 'org reftex-cite-format-builtin)) '((?W . "textcite:%l")
- (?z . "newcite:%l"))))
-#+END_SRC
-
-You can define a new citation link like this:
-#+BEGIN_SRC emacs-lisp :tangle no
-(org-ref-define-citation-link "citez" ?z)
-#+END_SRC