make html export for links be to a div id.
[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. org-ref is also extremely useful for research documents and notes. org-ref bundles several other libraries that provide functions to create and modify bibtex entries from a variety of sources, but most notably from a DOI.
11
12 The basic idea of org-ref is that it defines a convenient interface to insert citations from a reference database (e.g. from a bibtex file(s)), and 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 it 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. It was written to aid in the preparation of scientific manuscripts.  We have published a lot of scientific articles with it so far  cite:hallenbeck-2013-effec,mehta-2014-ident-poten,xu-2014-relat-elect,xu-2014-probin-cover,miller-2014-simul-temper,curnan-2014-effec-concen,boes-2015-estim-bulk,xu-2015-linear-respon,xu-2015-relat-between. 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. We anticipate a long life for org-ref.
21
22 ** Basic usage of org-ref
23
24 *** Bibliography links
25 index:bibliography index:bibliographystyle
26
27 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. Usually this link goes near the end of your document, e.g. like [[bibliography link][here]].
28
29 There is also a nobibliography link, which is useful for specifying a bibliography file, but not listing a bibliography in the exported document.
30
31 There is also a bibliographystyle link that specifies the style. This link does nothing but export to a LaTeX command.
32
33 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.
34
35 *** Citations
36     :PROPERTIES:
37     :CUSTOM_ID: citations
38     :END:
39 index:cite
40
41 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 if no bibliography link is found.
42
43 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.
44
45 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...
46
47 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.
48
49 Here is a list of supported citation types. You can customize this if you want. If you do not know what all these types are, you probably do not need them. The default cite is what you need. See http://ctan.unixbrain.com/macros/latex/contrib/natbib/natnotes.pdf
50  for the cite commands supported in bibtex index:natbib, and http://ctan.mirrorcatalogs.com/macros/latex/contrib/biblatex/doc/biblatex.pdf
51  for the commands supported in biblatex. For most scientific journals, only bibtex is supported. index:biblatex
52
53 #+BEGIN_SRC emacs-lisp
54 org-ref-cite-types
55 #+END_SRC
56
57 #+RESULTS:
58 | 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 |
59
60 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.
61
62 index:cite!replace
63 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.
64
65 [[index:cite!shift]]
66 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.
67
68 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}.
69
70 You may want to bind a hydra menu to a key-binding or key-chord. For example:
71
72 #+BEGIN_SRC emacs-lisp
73 (key-chord-define-global "kk" 'org-ref-cite-hydra/body)
74 #+END_SRC
75
76 This will allow you to quickly press kk while on a cite link to access functions that can act on the link.
77
78 *** label links
79 index:label
80
81 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. We illustrate some uses here.
82
83 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! It is most preferable to put a label link into a caption like this.
84 #+caption: Another simple table. label:tab-ydata
85 | y |
86 | 4 |
87 | 5 |
88
89 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. There is no default key-binding for this.
90
91 *** ref links
92     :PROPERTIES:
93     :ID:       290260A1-F07C-4852-B4B3-CEE3E768AA3B
94     :END:
95 index:ref
96
97 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. You have to provide the context before the ref link, e.g. Table, Figure, Equation, Section, ....
98
99 #+tblname: table-1
100 #+caption: A simple table.
101 | x |
102 | 1 |
103 | 2 |
104
105 Or you can refer to an org-mode label as in Table ref:table-3.
106
107 #+label: table-3
108 #+caption: Another simple table.
109 | y |
110 |---|
111 | 3 |
112 | 2 |
113
114 You can also refer to an org-ref label link as in Table ref:tab-ydata.
115
116 To help you insert ref links, use the "Org->org-ref->Insert ref" menu, or run the command elisp:org-ref-helm-insert-ref-link. There is no default key-binding for this.
117
118 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.
119
120 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.
121
122 **** Miscellaneous ref links  label:sec-misc
123 index:ref!pageref index:ref!nameref index:ref!eqref
124
125 org-ref also provides these links:
126
127 - pageref :: The page a label is on
128 - nameref :: The name of a section a label is in
129 - eqref :: Puts the equation number in parentheses
130
131 Note for eqref, you must use a LaTeX label like this:
132
133 \begin{equation}
134 e^x = 4 \label{eq:1}
135 \end{equation}
136
137 Then you can refer to Eq. eqref:eq:1 in your documents.
138
139 *** Some other links
140 [[index:list of tables]] [[index:list of figures]]
141
142 org-ref provides clickable links for a list-of-tables:nil and list-of-figures:nil. We have to put some text in the link, anything will do. These export as listoftables and listoffigures LaTeX commands, and they are clickable links that open a mini table of contents with links to the tables and figures in the buffer. There are also interactive commands for this: elisp:org-ref-list-of-tables and elisp:org-ref-list-of-figures.
143
144 ** org-ref customization of helm-bibtex
145 index:helm-bibtex
146
147 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.
148
149 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.
150
151 ** Some basic org-ref utilities
152 [[index:bibtex!clean entry]]
153
154 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.
155
156 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:
157
158 1. adds a comma if needed in the first line of the entry
159 2. makes sure the doi field is an actual doi, and not a url.
160 3. fixes bad year entries
161 4. fixes empty pages
162 5. Escapes & to \&
163 6. generate a key according to your setup
164 7. Runs your hook functions
165 8. sorts the fields in the entry
166 9. checks the buffer for non-ascii characters.
167
168 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.
169
170 #+BEGIN_SRC emacs-lisp
171 (add-hook 'org-ref-clean-bibtex-entry-hook 'jmax-replace-nonascii)
172 #+END_SRC
173
174 #+RESULTS:
175 | jmax-title-case-article | jmax-replace-nonascii |
176
177 org-ref-extract-bibtex-entries will create a bibtex file from the citations in the current buffer.
178
179 ** LaTeX export
180 index:export!LaTeX
181
182 All org-ref links are designed to export to the corresponding LaTeX commands for citations, labels, refs and the bibliography/bibliography style. Once you have the LaTeX file, you have to build it, using the appropriate latex and bibtex commands. You can have org-mode do this for you with a setup like:
183
184 #+BEGIN_SRC emacs-lisp
185 (setq org-latex-pdf-process
186       '("pdflatex -interaction nonstopmode -output-directory %o %f"
187         "bibtex %b"
188         "pdflatex -interaction nonstopmode -output-directory %o %f"
189         "pdflatex -interaction nonstopmode -output-directory %o %f")
190 #+END_SRC
191
192 ** Other exports
193 index:export!html index:export!ascii
194 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. For a markdown export, the cite links are exported as Pandoc style links.
195
196 * Other libraries in org-ref
197 These are mostly functions for adding entries to bibtex files, modifying entries or for operating on bibtex files. Some new org-mode links are defined.
198
199 ** doi-utils
200 index:doi
201
202 This library adds two extremely useful tools for getting bibtex entries and pdf files of journal manuscripts. Add this to your emacs setup:
203 #+BEGIN_SRC emacs-lisp
204 (require 'doi-utils)
205 #+END_SRC
206
207 The provides two important commands:
208
209 - doi-utils-add-bibtex-entry-from-doi
210 This will prompt you for a DOI, and a bibtex file, and then try to get the bibtex entry, and pdf of the article.
211
212 - doi-utils-add-entry-from-crossref-query
213 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.
214
215 This library also redefines the org-mode doi link. Now, when you click on this link you will get a menu of options, e.g. to open a bibtex entry or a pdf if you have it, or to search the doi in some scientific search engines. Try it out  doi:10.1021/jp511426q.
216
217 ** jmax-bibtex
218 These are functions I use often in bibtex files.
219
220 *** Generate new bibtex files with adapted journal names
221 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:
222
223 #+BEGIN_SRC emacs-lisp
224 (add-to-list 'jmax-bibtex-journal-abbreviations
225   '("JIR" "Journal of Irreproducible Research" "J. Irrep. Res."))
226 #+END_SRC
227
228 - jmax-bibtex-generate-longtitles :: Generate a bib file with long titles as
229      defined in `jmax-bibtex-journal-abbreviations'
230 - jmax-bibtex-generate-shorttitles :: Generate a bib file with short titles as
231      defined in `jmax-bibtex-journal-abbreviations'
232
233 *** Modifying bibtex entries
234
235 - jmax-stringify-journal-name :: replace a journal name with a string in
236      `jmax-bibtex-journal-abbreviations'
237 - jmax-set-journal-string :: in a bibtex entry run this to replace the journal
238      with a string selected interactively.
239
240 - jmax-title-case-article :: title case the title in an article entry.
241 - jmax-sentence-case-article :: sentence case the title in an article entry.
242
243 - jmax-replace-nonascii :: replace nonascii characters in a bibtex
244      entry. Replacements are in `jmax-nonascii-latex-replacements'. This
245      function is a hook function in org-ref-clean-bibtex-entry.
246
247 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.
248
249 #+BEGIN_SRC emacs-lisp
250 (add-to-list 'jmax-nonascii-latex-replacements
251   '("æ" . "{\\\\ae}"))
252 #+END_SRC
253
254 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:
255
256 #+BEGIN_SRC emacs-lisp
257 (bibtex-map-entries 'jmax-title-case-article)
258 #+END_SRC
259
260
261 *** Bibtex entry navigation
262 - jmax-bibtex-next-entry :: bound to M-n
263 - jmax-bibtex-previous-entry :: bound to M-p
264
265 *** Hydra menus for bibtex entries and files
266 - Functions to act on a bibtex entry or file
267   - jmax-bibtex-hydra/body :: gives a hydra menu to a lot of useful functions
268        like opening the pdf, or the entry in a browser, or searching in a
269        variety of scientific search engines.
270   - jmax-bibtex-new-entry/body :: gives a hydra menu to add new bibtex entries.
271   - jmax-bibtex-file/body :: gives a hydra menu of actions for the bibtex file.
272
273 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.
274 You can do that like this before you require jmax-bibtex:
275
276 #+BEGIN_SRC emacs-lisp
277 (setq jmax-bibtex-hydra-key-binding "\C-cj")
278 #+END_SRC
279
280 Or this if you like key-chord:
281
282 #+BEGIN_SRC emacs-lisp
283 (key-chord-define-global "jj" 'jmax-bibtex-hydra/body)
284 #+END_SRC
285
286 ** wos
287 This is a small utility for Web of Science/Knowledge (http://apps.webofknowledge.com).
288
289 #+BEGIN_SRC emacs-lisp
290 (require 'wos)
291 #+END_SRC
292
293 - wos :: Convenience function to open WOK in a browser.
294 - wos-search :: Search WOK with the selected text or word at point
295
296 There is also a new org-mode link that opens a search: [[wos-search:alloy and segregation]]
297
298 ** isbn
299 index:isbn
300
301 #+BEGIN_SRC emacs-lisp
302 (require 'isbn)
303 #+END_SRC
304
305 This library provides some functions to get bibtex entries for books from their ISBN.
306
307 - isbn-to-bibtex
308
309 ** pubmed
310 index:pubmed
311
312 #+BEGIN_SRC emacs-lisp
313 (require 'pubmed)
314 #+END_SRC
315
316 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.
317
318 pmcid:PMC3498956
319
320 pmid:23162369
321
322 nihmsid:NIHMS395714
323
324 Also, you can retrieve a bibtex entry for a PMID with
325
326 - pubmed-insert-bibtex-from-pmid
327
328 ** arxiv
329 index:arxiv
330
331 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:
332
333 #+BEGIN_SRC emacs-lisp
334 (require 'arxiv)
335 #+END_SRC
336
337 - arxiv-add-bibtex-entry
338 - arxiv-get-pdf
339
340 ** sci-id
341 index:orcid [[index:researcher id]]
342
343 #+BEGIN_SRC emacs-lisp
344 (require 'sci-id)
345 #+END_SRC
346
347 This package just defines two new org-mode links for http://www.orcid.org, and http://www.researcherid.com. Here are two examples:
348
349 orcid:0000-0003-2625-9232
350
351 researcherid:A-2363-2010
352
353 ** x2bib
354 index:bibtex!conversion
355
356 #+BEGIN_SRC emacs-lisp
357 (require 'x2bib)
358 #+END_SRC
359
360 If you find you need to convert some bibliographies in some format into bibtex, this library is a starting point. This code is mostly wrappers around the command line utilities at http://sourceforge.net/p/bibutils/home/Bibutils. I thankfully have not had to use this often, but it is here when I need it again.
361
362 - ris2bib :: Convert an RIS file to a bibtex file.
363 - medxml2bib :: Convert Pubmed XML to bibtex.
364 - clean-entries :: Map over a converted bibtex file and "clean it".
365
366 * Appendix
367 ** Customizing org-ref
368    :PROPERTIES:
369    :ID:       32B558A3-7B48-4581-982B-082017B0AEE8
370    :END:
371 index:customization
372
373 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")]].
374
375 Here is my minimal setup:
376 #+BEGIN_SRC emacs-lisp
377 (setq reftex-default-bibliography '("~/Dropbox/bibliography/references.bib"))
378
379 (setq org-ref-bibliography-notes "~/Dropbox/bibliography/notes.org"
380       org-ref-default-bibliography '("~/Dropbox/bibliography/references.bib")
381       org-ref-pdf-directory "~/Dropbox/bibliography/bibtex-pdfs/")
382 #+END_SRC
383
384 For jmax-bibtex I like:
385
386 #+BEGIN_SRC emacs-lisp
387 (setq jmax-bibtex-hydra-key-chord "jj")
388 #+END_SRC
389
390 ** Other things org-ref supports
391 *** org-completion
392 index:completion index:link!completion
393
394 Most org-ref links support org-mode completion. You can type C-c C-l to insert a link. You will get completion of the link type, type some characters and press tab. When you select the type, press tab to see the completion options. This works for the following link types:
395
396 - bibliography
397 - bibliographystyle
398 - all cite types
399 - ref
400
401 *** Storing org-links to labels
402     :PROPERTIES:
403     :ID:       AD9663C7-1369-413F-842A-157916D4BB75
404     :CUSTOM_ID: sec-store-links
405     :END:
406 index:link!storing
407
408 If you are on a label link, or on a table name, or on an org-mode label you can "store" a link to it by typing C-c l. Then you can insert the corresponding ref link with C-c C-l. This will insert a ref link or custom_id link as needed. This usually works, but it is not used by me too often, so it is not tested too deeply.
409
410 *** Storing links to bibtex entries
411 If you have a bibtex file open, you type C-c C-l with your cursor in a bibtex entry to store a link to that entry. In an org-buffer if you then type C-c l, you can enter a cite link.
412
413 *** Indexes
414 index:index
415
416 org-ref provides links to support making an index in LaTeX. (http://en.wikibooks.org/wiki/LaTeX/Indexing).
417
418 - index :: creates an index entry.
419 - printindex :: Generates a temporary index of clickable entries. Exports to the LaTeX command.
420
421 You will need to use the makeidx package, and use this in the LaTeX header.
422
423 #+LATEX_HEADER: \usepackage{makeidx}
424 #+LATEX_HEADER: \makeindex
425
426 You will have to incorporate running makeindex into your PDF build command.
427
428 This is not supported in anything but LaTeX export.
429
430 *** Glossaries
431 index:glossary
432
433 See http://en.wikibooks.org/wiki/LaTeX/Glossary. Not all options are supported. I have never actually used this functionality.
434
435 - newglossaryentry :: define a term
436 - gls :: a reference to a term
437 - glspl :: plural reference to a term
438 - Gsl :: capitalized reference to a term
439 - Glspl :: capitalized plural reference to a term
440
441 You will need to incorporate running the command makeglossaries into your PDF build command. You also need use the glossaries LaTeX package.
442
443 #+BEGIN_EXAMPLE
444 #+LATEX_HEADER: \usepackage[toc]{glossaries}
445 #+END_EXAMPLE
446
447 This is not supported in anything but LaTeX export.
448
449 * Index
450 This is a functional link that will open a buffer of clickable index entries:
451 printindex:nil
452
453 * Other forms of this document
454 ** PDF
455 You may want to build a pdf of this file. Here is an emacs-lisp block that will create and open the PDF.
456
457 #+BEGIN_SRC emacs-lisp
458 (org-open-file (org-latex-export-to-pdf))
459 #+END_SRC
460
461 #+RESULTS:
462
463 ** HTML
464 You may want to build an html version of this file. Here is an emacs-lisp block that will create and open the html in your browser. You will see the bibliography is not perfect, but it is pretty functional.
465
466 #+BEGIN_SRC emacs-lisp
467 (browse-url (org-html-export-to-html))
468 #+END_SRC
469
470 #+RESULTS:
471 : #<process open ./org-ref.html>
472
473 * References
474 bibliographystyle:unsrtnat
475 # <<bibliography link>>
476 bibliography:org-ref.bib