ignore some files
[org-ref.git] / org-ref.org
1 #+TITLE: The org-ref manual
2 #+AUTHOR: John Kitchin
3 #+DATE: 2015-03-15 Sun
4 #+OPTIONS: toc:nil ^:{}
5 #+LATEX_HEADER: \usepackage{natbib}
6 \maketitle
7 \tableofcontents
8
9 * Introduction to org-ref
10 Org-ref is a library for org-mode cite:Dominik201408 that provides rich support for citations, labels and cross-references in org-mode. org-ref is especially suitable for org-mode documents destined for LaTeX export and scientific publication. It is also extremely useful for research documents and notes.
11
12 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, and can also use reftex.
13
14 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 in scientific writing.
15
16 org-ref is [[id:32B558A3-7B48-4581-982B-082017B0AEE8][customizable]].
17
18 org-ref has been in development since sometime in 2013. We have published a lot of scientific articles with it cite:hallenbeck-2013-effec-o2,mehta-2014-ident-poten,xu-2014-relat,xu-2014-probin-cover,miller-2014-simul-temper,curnan-2014-effec-concen,boes-2015-estim-bulk,xu-2015-linear-respon,xu-2015-relat. Be sure to check out the supporting information files for each of these. The org source for the supporting information is usually embedded in the supporting information.
19
20 There has been a lot of recent discussion on the org-mode mailing list about a citation syntax for org-mode. It is not clear what the impact of this on org-ref will be. The new syntax will more cleanly support pre/post text, and it will be separate from the links used in org-ref. It is not clear if the new syntax will support all of the citation types, especially those in biblatex, that are supported in org-ref. The new citations are likely to be clickable, and could share functionality with org-ref. The new citation syntax will not cover labels and cross-references though, so these links from org-ref will still exist.
21
22 ** Basic usage of org-ref
23
24 *** Bibliography links
25 org-ref provides a bibliography link to specify which bibtex files to use in the document. You should use the 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. On export, the bibliography will appear at the position where the link is defined.
26
27 There is also a bibliographystyle link that specifies the style. This link does nothing but export to a LaTeX command.
28
29 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.
30
31 *** Citations
32     :PROPERTIES:
33     :CUSTOM_ID: citations
34     :END:
35 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 or org-ref-default-bibliography.
36
37 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 (or use the key-binding C-c ] by default), select the reference(s) you want in the helm-bibtex buffer and press enter. The citation will be inserted automatically into your org-file. You "select" an entry by using the arrow keys to move up and down to the entry you want. You can narrow the selection by typing a pattern to match, e.g. author name, title words, year, keyword, etc... You can select multiple entries by pressing C-spc to mark enties in the helm-bibtex buffer.
38
39 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...
40
41 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.
42
43 Here is a list of supported citation types. You can customize this if you want.
44 #+BEGIN_SRC emacs-lisp :results code
45 org-ref-cite-types
46 #+END_SRC
47
48 #+RESULTS:
49 #+BEGIN_SRC emacs-lisp
50 ("cite" "nocite" "citet" "citet*" "citep" "citep*" "citealt" "citealt*" "citealp" "citealp*" "citenum" "citetext" "citeauthor" "citeauthor*" "citeyear" "citeyear*" "Citet" "Citep" "Citealt" "Citealp" "Citeauthor" "Cite" "parencite" "Parencite" "footcite" "footcitetext" "textcite" "Textcite" "smartcite" "Smartcite" "cite*" "parencite*" "supercite" "autocite" "Autocite" "autocite*" "Autocite*" "Citeauthor*" "citetitle" "citetitle*" "citedate" "citedate*" "citeurl" "fullcite" "footfullcite" "notecite" "Notecite" "pnotecite" "Pnotecite" "fnotecite" "cites" "Cites" "parencites" "Parencites" "footcites" "footcitetexts" "smartcites" "Smartcites" "textcites" "Textcites" "supercites" "autocites" "Autocites" "bibentry")
51 #+END_SRC
52
53 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.
54
55 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.
56
57 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.
58
59 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]]. It is a little awkward to see this because you cannot see the key. It is a low priority to find a fix for this, because it is not common in scientific publishing and you can always fall back to the old-fashioned LaTeX: \cite[See page 20][, for example]{Dominik201408}.
60
61 You may want to bind a hydra menu to a key-binding or key-chord. For example:
62
63 #+BEGIN_SRC emacs-lisp
64 (key-chord-define-global "kk" 'org-ref-cite-hydra/body)
65 #+END_SRC
66
67 This will allow you to quickly press kk while on a cite link to access functions that can act on the link.
68
69 *** label links
70 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.
71
72 Or you can put a label link into a caption like this.
73 #+caption: Another simple table. label:tab-ydata
74 | y |
75 | 4 |
76 | 5 |
77
78 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.
79
80 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!
81
82 *** ref links
83 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.
84
85 #+tblname: table-1
86 #+caption: A simple table.
87 | x |
88 | 1 |
89 | 2 |
90
91 Or you can refer to an org-mode label as in Table ref:table-3.
92
93 #+label: table-3
94 #+caption: A simple table.
95 | x |
96 | 1 |
97 | 2 |
98
99 You can also refer to an org-ref label link as in Table ref:tab-ydata.
100
101 To help you insert ref links, use the "Org->org-ref->Insert ref" menu, or run the command org-ref-helm-insert-ref-link.
102
103 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.
104
105 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. For example section [[#citations]] has a CUSTOM_ID of citations. Section ref:sec-misc has a label link in the headline. That works, but is not too pretty.
106
107 **** Miscellaneous ref links  label:sec-misc
108 org-ref also provides a pageref, nameref and eqref link.
109
110 Note for eqref, you must use a LaTeX label like this:
111
112 \begin{equation}
113 e^x = 4 \label{eq:1}
114 \end{equation}
115
116 Then you can refer to Eq. eqref:eq:1 in your documents.
117
118 ** org-ref customization of helm-bibtex
119 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.
120
121 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.
122
123 ** Some basic org-ref utilities
124 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.
125
126 org-ref-clean-bibtex-entry will sort the fields of a bibtex entry, clean it, and give it a bibtex key. This function does a lot of cleaning:
127
128 1. adds a comma if needed in the first line of the entry
129 2. makes sure the doi field is an actual doi, and not a url.
130 3. fixes bad year entries
131 4. fixes empty pages
132 5. Escapes & to \&
133 6. generate a key according to your setup
134 7. Runs your hook functions
135 8. sorts the fields in the entry
136 9. checks the buffer for non-ascii characters.
137
138 This function has a hook org-ref-clean-bibtex-entry-hook, which you can add functions to of your own. Each function must work on a bibtex entry at point.
139
140 #+BEGIN_SRC emacs-lisp
141 (add-hook 'org-ref-clean-bibtex-entry-hook 'jmax-replace-nonascii)
142 #+END_SRC
143
144 #+RESULTS:
145 | jmax-title-case-article | jmax-replace-nonascii |
146
147 org-ref-extract-bibtex-entries will create a bibtex file from the citations in the current buffer.
148
149 ** LaTeX export
150 All org-ref links are designed to export to the corresponding LaTeX commands.
151
152 ** Other exports
153 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.
154
155 * Other libraries in org-ref
156 These are mostly functions for adding to bibtex files, or for operating on bibtex files.
157
158 ** doi-utils
159 This library adds two extremely useful tools for getting bibtex entries and pdf files of journal manuscripts. Add this to your emacs setup:
160 #+BEGIN_SRC emacs-lisp
161 (require 'doi-utils)
162 #+END_SRC
163
164 The provides two important commands:
165
166 - doi-utils-add-bibtex-entry-from-doi
167 This will prompt you for a DOI, and a bibtex file, and then try to get the bibtex entry, and pdf of the article.
168
169
170 - doi-utils-add-entry-from-crossref-query
171 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.
172
173 ** isbn
174 #+BEGIN_SRC emacs-lisp
175 (require 'isbn)
176 #+END_SRC
177
178 This library provides some functions to get bibtex entries for books from their ISBN.
179
180 - isbn-to-bibtex
181
182 ** pubmed
183 #+BEGIN_SRC emacs-lisp
184 (require 'pubmed)
185 #+END_SRC
186
187 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.
188
189 pmcid:PMC3498956
190
191 pmid:23162369
192
193 nihmsid:NIHMS395714
194
195 Also, you can retrieve a bibtex entry for a PMID with
196
197 - pubmed-insert-bibtex-from-pmid
198
199 ** arxiv
200 #+BEGIN_SRC emacs-lisp
201 (require 'arxiv)
202 #+END_SRC
203
204 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:
205
206 - arxiv-add-bibtex-entry
207 - arxiv-get-pdf
208
209 ** sci-id
210 #+BEGIN_SRC emacs-lisp
211 (require 'sci-id)
212 #+END_SRC
213
214 This package just defines two new org-mode links for http://www.orcid.org, and http://www.researcherid.com. Here are two examples:
215
216 orcid:0000-0003-2625-9232
217
218 researcherid:A-2363-2010
219
220 ** jmax-bibtex
221 These are functions I use often in bibtex files.
222
223 *** Generate new bibtex files with adapted journal names
224 The variable jmax-bibtex-journal-abbreviations contains a mapping of a short string to a full journal title, and an abbreviated journal title. We can use these to create new versions of a bibtex file with full or abbreviated journal titles. You can add new strings like this:
225
226 #+BEGIN_SRC emacs-lisp
227 (add-to-list 'jmax-bibtex-journal-abbreviations
228   '("JIR" "Journal of Irreproducible Research" "J. Irrep. Res."))
229 #+END_SRC
230
231 - jmax-bibtex-generate-longtitles :: Generate a bib file with long titles as
232      defined in `jmax-bibtex-journal-abbreviations'
233 - jmax-bibtex-generate-shorttitles :: Generate a bib file with short titles as
234      defined in `jmax-bibtex-journal-abbreviations'
235
236 *** Modifying bibtex entries
237
238 - jmax-stringify-journal-name :: replace a journal name with a string in
239      `jmax-bibtex-journal-abbreviations'
240 - jmax-set-journal-string :: in a bibtex entry run this to replace the journal
241      with a string selected interactively.
242
243 - jmax-title-case-article :: title case the title in an article entry.
244 - jmax-sentence-case-article :: sentence case the title in an article entry.
245
246 - jmax-replace-nonascii :: replace nonascii characters in a bibtex
247      entry. Replacements are in `jmax-nonascii-latex-replacements'. This
248      function is a hook function in org-ref-clean-bibtex-entry.
249
250 The non-ascii characters are looked up in a list of cons cells. You can add your own non-ascii replacements like this. Note backslashes must be escaped doubly, so one \ is \\\\ in the cons cell.
251
252 #+BEGIN_SRC emacs-lisp
253 (add-to-list 'jmax-nonascii-latex-replacements
254   '("æ" . "{\\\\ae}"))
255 #+END_SRC
256
257 These functions are compatible with bibtex-map-entries, so it is possible to conveniently apply them to all the entries in a file like this:
258
259 #+BEGIN_SRC emacs-lisp
260 (bibtex-map-entries 'jmax-title-case-article)
261 #+END_SRC
262
263
264
265 *** Bibtex entry navigation
266 - jmax-bibtex-next-entry :: bound to M-n
267 - jmax-bibtex-previous-entry :: bound to M-p
268
269 *** Hydra menus for bibtex entries and files
270 - Functions to act on a bibtex entry or file
271   - jmax-bibtex-hydra/body :: gives a hydra menu to a lot of useful functions
272        like opening the pdf, or the entry in a browser, or searching in a
273        variety of scientific search engines.
274   - jmax-bibtex-new-entry/body :: gives a hydra menu to add new bibtex entries.
275   - jmax-bibtex-file/body :: gives a hydra menu of actions for the bibtex file.
276
277 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.
278 You can do that like this before you require jmax-bibtex:
279
280 #+BEGIN_SRC emacs-lisp
281 (setq jmax-bibtex-hydra-key-binding "\C-cj")
282 #+END_SRC
283
284 Or this if you like key-chord:
285
286 #+BEGIN_SRC emacs-lisp
287 (key-chord-define-global "jj" 'jmax-bibtex-hydra/body)
288 #+END_SRC
289
290 * Appendix
291 ** Customizing org-ref
292    :PROPERTIES:
293    :ID:       32B558A3-7B48-4581-982B-082017B0AEE8
294    :END:
295 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")]].
296
297 Here is my minimal setup:
298 #+BEGIN_SRC emacs-lisp
299 (setq reftex-default-bibliography '("~/Dropbox/bibliography/references.bib"))
300
301 (setq org-ref-bibliography-notes "~/Dropbox/bibliography/notes.org"
302       org-ref-default-bibliography '("~/Dropbox/bibliography/references.bib")
303       org-ref-pdf-directory "~/Dropbox/bibliography/bibtex-pdfs/")
304 #+END_SRC
305
306
307
308 * References
309 bibliographystyle:unsrt
310 # <<bibliography link>>
311 bibliography:org-ref.bib