add additional documentation.
[org-ref.git] / org-ref.org
1 #+TITLE: The org-ref manual
2 #+AUTHOR: John Kitchin
3 #+DATE: 2015-03-15 Sun
4
5 * Introduction to org-ref
6 Org-ref is an addon library for org-mode cite:Dominik201408 that provides rich support for citations, and cross-references in org-mode. org-ref is especially suitable for org-mode documents destined for LaTeX export.
7
8 The basic idea of org-ref is that it defines a set of functional org-mode links for citations, cross-references and labels that export properly to LaTeX, and that provide clickable functionality to the user. org-ref interfaces with helm-bibtex to facilitate citation entry.
9
10 org-ref provides a fairly large number of utilities for finding bad citations, extracting bibtex entries from citations in an org-file, and functions for interacting with bibtex entries. We find these utilities indispensable.
11
12 org-ref is [[id:32B558A3-7B48-4581-982B-082017B0AEE8][customizable]].
13
14 ** Basic usage of org-ref
15
16 *** Sources of bibtex entries
17
18 *** Bibliography links
19 org-ref provides a bibliography link to specify which bibtex files to use in the document. You should use the full filename with extension, and separate filenames by commas. This link is clickable; clicking on a filename will open the file. Also, if your cursor is on a filename, you will see a minibuffer message about whether the file exists or not.
20
21 There is also a bibliographystyle link that specifies the style. This link does nothing but export to \bibliographystyle{link-string}.
22
23 If you use biblatex, then you use an addbibresource link. biblatex support is not very well tested by me, because we do not use it.
24
25 *** Citations
26     :PROPERTIES:
27     :CUSTOM_ID: citations
28     :END:
29 org-ref uses the [[bibliography link]] to determine which bibtex files to get citations from, and falls back to the bibtex files defined in the variable  reftex-default-bibliography.
30
31 For simple citation needs, org-ref is simple to use. At the point you want to insert a citation, you select the "Org -> org-ref -> Insert citation" menu, select the reference(s) you want in the helm-bibtex buffer and press enter. The citation will be inserted automatically into your org-file. If the cursor is on a citation key, you should see a message in the minibuffer that summarizes which citation it refers to. If you click on a key, you should see a helm selection buffer with some actions to choose, including opening the bibtex entry, opening/getting a pdf for the entry, searching the entry in Web of Science, etc...
32
33 The default citation type is [[id:32B558A3-7B48-4581-982B-082017B0AEE8][customizable]], and set to "cite". If you want another type of citation type, then type C-u before pressing enter in the helm-bibtex selection buffer. You will be prompted for the type of citation you actually want.
34
35 If the cursor is on a citation, or at the end of the citation, and you add another citation, it will be appended to the current citation.
36
37 If you want to /replace/ an existing key in a citation, put the cursor on the key, run the insert citation command, and type C-u C-u before pressing enter in the helm-bibtex selection buffer. The key will be replaced. Of course, you can just delete it yourself, and add a new key.
38
39 Finally, if you do not like the order of the keys in a citation, you can put your cursor on a key and use shift-arrows (left or right) to move the key around. Alternatively, you can run the command org-ref-sort-citation-link which will sort the keys by year, oldest to newest.
40
41 org-ref has basic support for pre/post text in citations. We have very little need for this in scientific publishing; we write pre text before the citation, and post text after it. However, you can get pre/post text by using a description in a cite link, with pre/post text separated by ::. For example, [[cite:Dominik201408][See page 20::, for example]].
42
43 You may want to bind a hydra menu to a key-binding or key-chord. For example:
44
45 #+BEGIN_SRC emacs-lisp
46 (key-chord-define-global "kk" 'org-ref-cite-hydra/body)
47 #+END_SRC
48
49 This will allow you to quickly press kk while on a cite link to access functions that can act on the link.
50
51 *** label links
52 LaTeX uses labels to define places you can refer to. These can be labels in the captions of figures and tables, or labels in sections.
53
54 Or you can put a label link into a caption like this.
55 #+caption: Another simple table. label:tab-ydata
56 | y |
57 | 4 |
58 | 5 |
59
60 org-ref can help you insert unique labels with the command elisp:org-ref-helm-insert-label-link. This will show you the existing labels, and insert your new label as a link.
61
62 label links are "functional" if you put your cursor on the link, you will get a message in the minibuffer showing you the number of occurrences of that label in the buffer. That number should be one!
63
64 *** ref links
65 A ref link refers to a label of some sort. For example, you can refer to a table name, e.g. Table ref:table-1.
66
67 #+tblname: table-1
68 #+caption: A simple table.
69 | x |
70 | 1 |
71 | 2 |
72
73 Or you can refer to an org-mode label as in Table ref:table-3.
74
75 #+label: table-3
76 #+caption: A simple table.
77 | x |
78 | 1 |
79 | 2 |
80
81 You can also refer to an org-ref label link as in Table ref:tab-ydata.
82
83 To help you insert ref links, use the "Org->org-ref->Insert ref" menu, or run the command org-ref-helm-insert-ref-link.
84
85 ref links are functional. If you put the cursor on a ref link, you will get a little message in the minibuffer with some context of the corresponding label. If you click on the ref link, the cursor will jump to the label.
86
87 A brief note about references to a section. This only works if you put a label in the org-mode headline. Otherwise, you must use a CUSTOM_ID and a CUSTOM_ID link.
88
89 **** Miscellaneous ref links
90 org-ref provides a pageref, nameref and eqref link.
91
92 Note for eqref, you must use a LaTeX label like this:
93
94
95 \begin{equation}
96 e^x = 4 \label{eq:1}
97 \end{equation}
98
99 Then you can refer to Eq. eqref:eq:1 in your documents.
100
101 ** org-ref customization of helm-bibtex
102 org-ref adds a few new features to helm-bibtex. First, we add keywords as a searchable field. Second, org-ref modifies the helm-bibtex search buffer to include the keywords. Since keywords now can have a central role in searching, we add some functionality to add keywords from the helm-bibtex buffer as a new action.
103
104 We change the order of the actions in helm-bibtex to suit our work flow, and add some new actions. We define a format function for org-mode that is compatible with the usage defined in section [[#citations]]. Finally, we add some new fallback options for additional scientific search engines.
105
106 ** Some basic org-ref utilities
107 The command org-ref does a lot for you automatically. It will check the buffer for errors, e.g. multiply-defined labels, bad citations or ref links, and provide easy access to a few commands through a helm buffer.
108
109 org-ref-clean-bibtex-entry will sort the fields of a bibtex entry, clean it, and give it a bibtex key.
110
111 org-ref-extract-bibtex-entries will create a bibtex file from the citations in the current buffer.
112
113 ** LaTeX export
114 All org-ref links are designed to export to the corresponding LaTeX commands.
115
116 ** Other exports
117 There is some basic support for HTML and ascii export. Not all bibtex entry types are supported, but basic support exists for articles and books.
118
119 * Other libraries in org-ref
120 These are mostly functions for adding to bibtex files, or for operating on bibtex files.
121
122 ** doi-utils
123 This library adds two extremely useful tools for getting bibtex entries and pdf files of journal manuscripts. Add this to your emacs setup:
124 #+BEGIN_SRC emacs-lisp
125 (require 'doi-utils)
126 #+END_SRC
127
128 The provides two important commands:
129
130 - doi-utils-add-bibtex-entry-from-doi
131 This will prompt you for a DOI, and a bibtex file, and then try to get the bibtex entry, and pdf of the article.
132
133
134 - doi-utils-add-entry-from-crossref-query
135 This will prompt you for a query string, which is usually the title of an article, or a free-form text citation of an article. Then you will get a helm buffer of matching items, which you can choose from to insert a new bibtex entry into a bibtex file.
136
137 ** isbn
138 #+BEGIN_SRC emacs-lisp
139 (require 'isbn)
140 #+END_SRC
141
142 This library provides some functions to get bibtex entries for books from their ISBN.
143
144 - isbn-to-bibtex
145
146 ** pubmed
147 #+BEGIN_SRC emacs-lisp
148 (require 'pubmed)
149 #+END_SRC
150
151 This library provides a number of new org-mode links to Pubmed entries. See http://www.ncbi.nlm.nih.gov/pmc/about/public-access-info/#p3 for details of these identifiers.
152
153 pmcid:PMC3498956
154
155 pmid:23162369
156
157 nihmsid:NIHMS395714
158
159 Also, you can retrieve a bibtex entry for a PMID with
160
161 - pubmed-insert-bibtex-from-pmid
162
163 ** arxiv
164 #+BEGIN_SRC emacs-lisp
165 (require 'arxiv)
166 #+END_SRC
167
168 This library provides an org-mode link to http://arxiv.org entries:  arxiv:cond-mat/0410285, and a function to get a bibtex entry and pdfs for arxiv entries:
169
170 - arxiv-add-bibtex-entry
171 - arxiv-get-pdf
172
173 ** sci-id
174 #+BEGIN_SRC emacs-lisp
175 (require 'sci-id)
176 #+END_SRC
177
178 This package just defines two new org-mode links for http://www.orcid.org, and http://www.researcherid.com. Here are two examples:
179
180 orcid:0000-0003-2625-9232
181
182 researcherid:A-2363-2010
183
184 ** jmax-bibtex
185 These are functions I use often in bibtex files.
186
187 - jmax-bibtex-generate-longtitles
188 - jmax-bibtex-generate-shorttitles
189 - jmax-stringify-journal-name :: replace a journal name with a string in
190      `jmax-bibtex-journal-abbreviations'
191 - jmax-set-journal-string :: in a bibtex entry run this to replace the journal
192      with a string
193 - jmax-title-case-article :: title case the title in an article
194 - jmax-sentence-case-article :: sentence case the title in an article.
195
196 - jmax-replace-nonascii :: replace nonascii characters in a bibtex
197      entry. Replacements are in `jmax-nonascii-latex-replacements'.
198
199 - jmax-title-case-article
200 - jmax-sentence-case-article
201
202 - jmax-bibtex-next-entry :: bound to M-n
203 - jmax-bibtex-previous-entry :: bound to M-p
204
205 - Functions to act on a bibtex entry or file
206   - jmax-bibtex-hydra/body :: gives a hydra menu to a lot of useful functions.
207   - jmax-bibtex-new-entry/body :: gives a hydra menu to add new bibtex entries.
208   - jmax-bibtex-file/body :: gives a hydra menu of actions for the bibtex file
209
210 You will want to bind the hydra menus to a key. You only need to bind the first one, as the second and third can be accessed from the first hydra.
211 You can do that like this before you require jmax-bibtex:
212
213 #+BEGIN_SRC emacs-lisp
214 (setq jmax-bibtex-hydra-key-binding "\C-cj")
215 #+END_SRC
216
217 Or this if you like key-chords:
218
219 #+BEGIN_SRC emacs-lisp
220 (key-chord-define-global "jj" 'jmax-bibtex-hydra/body)
221 #+END_SRC
222
223 * Appendix
224 ** Customizing org-ref
225    :PROPERTIES:
226    :ID:       32B558A3-7B48-4581-982B-082017B0AEE8
227    :END:
228 You will probably want to customize a few variables before using org-ref extensively. One way to do this is through the Emacs customization interface: [[elisp:(customize-group "org-ref")]].
229
230 Here is my minimal setup:
231 #+BEGIN_SRC emacs-lisp
232 (setq reftex-default-bibliography '("~/Dropbox/bibliography/references.bib"))
233
234 (setq org-ref-bibliography-notes "~/Dropbox/bibliography/notes.org"
235       org-ref-default-bibliography '("~/Dropbox/bibliography/references.bib")
236       org-ref-pdf-directory "~/Dropbox/bibliography/bibtex-pdfs/")
237 #+END_SRC
238
239
240
241 * References
242 # <<bibliography link>>
243 bibliography:org-ref.bib