org-ref is [[id:32B558A3-7B48-4581-982B-082017B0AEE8][customizable]].
-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-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.
+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.
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.
** Basic usage of org-ref
*** Bibliography links
+index:bibliography index:bibliographystyle
+
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]].
There is also a nobibliography link, which is useful for specifying a bibliography file, but not listing a bibliography in the exported document.
:PROPERTIES:
:CUSTOM_ID: citations
:END:
+index:cite
+
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.
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.
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.
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
- for the cite commands supported in bibtex, and http://ctan.mirrorcatalogs.com/macros/latex/contrib/biblatex/doc/biblatex.pdf
- for the commands supported in biblatex. For most scientific journals, only bibtex is supported.
+ for the cite commands supported in bibtex index:natbib, and http://ctan.mirrorcatalogs.com/macros/latex/contrib/biblatex/doc/biblatex.pdf
+ for the commands supported in biblatex. For most scientific journals, only bibtex is supported. index:biblatex
#+BEGIN_SRC emacs-lisp
org-ref-cite-types
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.
+index:cite!replace
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.
+[[index:cite!shift]]
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.
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}.
This will allow you to quickly press kk while on a cite link to access functions that can act on the link.
*** label links
+index:label
+
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.
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.
:PROPERTIES:
:ID: 290260A1-F07C-4852-B4B3-CEE3E768AA3B
:END:
+index:ref
+
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, ....
#+tblname: table-1
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.
**** Miscellaneous ref links label:sec-misc
+index:ref!pageref index:ref!nameref index:ref!eqref
+
org-ref also provides these links:
- pageref :: The page a label is on
Then you can refer to Eq. eqref:eq:1 in your documents.
*** Some other links
-org-ref provides clickable links for a list-of-tables:nil and list-of-figures:nil. 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.
+[[index:list of tables]] [[index:list of figures]]
+
+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.
** org-ref customization of helm-bibtex
+index:helm-bibtex
+
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.
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.
** Some basic org-ref utilities
+[[index:bibtex!clean entry]]
+
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.
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:
org-ref-extract-bibtex-entries will create a bibtex file from the citations in the current buffer.
** LaTeX export
+index:export!LaTeX
+
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:
#+BEGIN_SRC emacs-lisp
#+END_SRC
** Other exports
+index:export!html index:export!ascii
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.
* Other libraries in org-ref
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.
** doi-utils
+index:doi
+
This library adds two extremely useful tools for getting bibtex entries and pdf files of journal manuscripts. Add this to your emacs setup:
#+BEGIN_SRC emacs-lisp
(require 'doi-utils)
- doi-utils-add-bibtex-entry-from-doi
This will prompt you for a DOI, and a bibtex file, and then try to get the bibtex entry, and pdf of the article.
-
- doi-utils-add-entry-from-crossref-query
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.
+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.
+
** jmax-bibtex
These are functions I use often in bibtex files.
(key-chord-define-global "jj" 'jmax-bibtex-hydra/body)
#+END_SRC
+** wos
+This is a small utility for Web of Science/Knowledge (http://apps.webofknowledge.com).
+
+#+BEGIN_SRC emacs-lisp
+(require 'wos)
+#+END_SRC
+
+- wos :: Convenience function to open WOK in a browser.
+- wos-search :: Search WOK with the selected text or word at point
+
+There is also a new org-mode link that opens a search: [[wos-search:alloy and segregation]]
+
** isbn
+index:isbn
+
#+BEGIN_SRC emacs-lisp
(require 'isbn)
#+END_SRC
- isbn-to-bibtex
** pubmed
+index:pubmed
+
#+BEGIN_SRC emacs-lisp
(require 'pubmed)
#+END_SRC
- pubmed-insert-bibtex-from-pmid
** arxiv
+index:arxiv
+
+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:
+
#+BEGIN_SRC emacs-lisp
(require 'arxiv)
#+END_SRC
-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:
-
- arxiv-add-bibtex-entry
- arxiv-get-pdf
** sci-id
+index:orcid [[index:researcher id]]
+
#+BEGIN_SRC emacs-lisp
(require 'sci-id)
#+END_SRC
researcherid:A-2363-2010
** x2bib
+index:bibtex!conversion
+
#+BEGIN_SRC emacs-lisp
(require 'x2bib)
#+END_SRC
:PROPERTIES:
:ID: 32B558A3-7B48-4581-982B-082017B0AEE8
:END:
+index:customization
+
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")]].
Here is my minimal setup:
** Other things org-ref supports
*** org-completion
+index:completion index:link!completion
+
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:
- bibliography
:ID: AD9663C7-1369-413F-842A-157916D4BB75
:CUSTOM_ID: sec-store-links
:END:
+index:link!storing
+
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.
*** Storing links to bibtex entries
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.
*** Indexes
+index:index
+
org-ref provides links to support making an index in LaTeX. (http://en.wikibooks.org/wiki/LaTeX/Indexing).
- index :: creates an index entry.
- printindex :: Generates a temporary index of clickable entries. Exports to the LaTeX command.
+You will need to use the makeidx package, and use this in the LaTeX header.
+
+#+LATEX_HEADER: \usepackage{makeidx}
+#+LATEX_HEADER: \makeindex
+
You will have to incorporate running makeindex into your PDF build command.
+This is not supported in anything but LaTeX export.
+
*** Glossaries
-See http://en.wikibooks.org/wiki/LaTeX/Glossary.
+index:glossary
+
+See http://en.wikibooks.org/wiki/LaTeX/Glossary. Not all options are supported. I have never actually used this functionality.
+
+- newglossaryentry :: define a term
+- gls :: a reference to a term
+- glspl :: plural reference to a term
+- Gsl :: capitalized reference to a term
+- Glspl :: capitalized plural reference to a term
+
+You will need to incorporate running the command makeglossaries into your PDF build command. You also need use the glossaries LaTeX package.
+
+#+BEGIN_EXAMPLE
+#+LATEX_HEADER: \usepackage[toc]{glossaries}
+#+END_EXAMPLE
-- newglossaryentry
-- gls
-- glspl
-- Gsl
-- Glspl
+This is not supported in anything but LaTeX export.
-You will need to incorporate running the command makeglossaries into your PDF build command.
+* Index
+This is a functional link that will open a buffer of clickable index entries:
+printindex:nil
+
+* Other forms of this document
+** PDF
+You may want to build a pdf of this file. Here is an emacs-lisp block that will create and open the PDF.
+
+#+BEGIN_SRC emacs-lisp
+(org-open-file (org-latex-export-to-pdf))
+#+END_SRC
+
+#+RESULTS:
+
+** HTML
+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.
+
+#+BEGIN_SRC emacs-lisp
+(browse-url (org-html-export-to-html))
+#+END_SRC
+
+#+RESULTS:
+: #<process open ./org-ref.html>
* References
bibliographystyle:unsrtnat
projects / org-ref.git / blobdiff