X-Git-Url: https://git.donarmstrong.com/?p=org-ref.git;a=blobdiff_plain;f=org-ref.org;h=297be57cffc04af43bed22e0e32c2ac12f5a7831;hp=9bca7c24c1b61c81bd23a0c86474a74362aeda08;hb=3f79a48e7c9188ce8d8a03da19ae1b2496c5d4cf;hpb=1bbb737e91f7517b3812f33e9e57c673ea5e2a37 diff --git a/org-ref.org b/org-ref.org deleted file mode 100644 index 9bca7c2..0000000 --- a/org-ref.org +++ /dev/null @@ -1,243 +0,0 @@ -#+TITLE: The org-ref manual -#+AUTHOR: John Kitchin -#+DATE: 2015-03-15 Sun - -* Introduction to org-ref -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. - -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. - -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. - -org-ref is [[id:32B558A3-7B48-4581-982B-082017B0AEE8][customizable]]. - -** Basic usage of org-ref - -*** Sources of bibtex entries - -*** Bibliography links -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. - -There is also a bibliographystyle link that specifies the style. This link does nothing but export to \bibliographystyle{link-string}. - -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. - -*** Citations - :PROPERTIES: - :CUSTOM_ID: citations - :END: -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. - -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... - -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. - -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. - -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. - -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]]. - -You may want to bind a hydra menu to a key-binding or key-chord. For example: - -#+BEGIN_SRC emacs-lisp -(key-chord-define-global "kk" 'org-ref-cite-hydra/body) -#+END_SRC - -This will allow you to quickly press kk while on a cite link to access functions that can act on the link. - -*** label links -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. - -Or you can put a label link into a caption like this. -#+caption: Another simple table. label:tab-ydata -| y | -| 4 | -| 5 | - -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. - -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! - -*** ref links -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. - -#+tblname: table-1 -#+caption: A simple table. -| x | -| 1 | -| 2 | - -Or you can refer to an org-mode label as in Table ref:table-3. - -#+label: table-3 -#+caption: A simple table. -| x | -| 1 | -| 2 | - -You can also refer to an org-ref label link as in Table ref:tab-ydata. - -To help you insert ref links, use the "Org->org-ref->Insert ref" menu, or run the command org-ref-helm-insert-ref-link. - -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. - -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. - -**** Miscellaneous ref links -org-ref provides a pageref, nameref and eqref link. - -Note for eqref, you must use a LaTeX label like this: - - -\begin{equation} -e^x = 4 \label{eq:1} -\end{equation} - -Then you can refer to Eq. eqref:eq:1 in your documents. - -** org-ref customization of 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 -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. - -org-ref-extract-bibtex-entries will create a bibtex file from the citations in the current buffer. - -** LaTeX export -All org-ref links are designed to export to the corresponding LaTeX commands. - -** Other exports -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. - -* Other libraries in org-ref -These are mostly functions for adding to bibtex files, or for operating on bibtex files. - -** doi-utils -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) -#+END_SRC - -The provides two important commands: - -- 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. - -** isbn -#+BEGIN_SRC emacs-lisp -(require 'isbn) -#+END_SRC - -This library provides some functions to get bibtex entries for books from their ISBN. - -- isbn-to-bibtex - -** pubmed -#+BEGIN_SRC emacs-lisp -(require 'pubmed) -#+END_SRC - -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. - -pmcid:PMC3498956 - -pmid:23162369 - -nihmsid:NIHMS395714 - -Also, you can retrieve a bibtex entry for a PMID with - -- pubmed-insert-bibtex-from-pmid - -** arxiv -#+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 -#+BEGIN_SRC emacs-lisp -(require 'sci-id) -#+END_SRC - -This package just defines two new org-mode links for http://www.orcid.org, and http://www.researcherid.com. Here are two examples: - -orcid:0000-0003-2625-9232 - -researcherid:A-2363-2010 - -** jmax-bibtex -These are functions I use often in bibtex files. - -- jmax-bibtex-generate-longtitles -- jmax-bibtex-generate-shorttitles -- jmax-stringify-journal-name :: replace a journal name with a string in - `jmax-bibtex-journal-abbreviations' -- jmax-set-journal-string :: in a bibtex entry run this to replace the journal - with a string -- jmax-title-case-article :: title case the title in an article -- jmax-sentence-case-article :: sentence case the title in an article. - -- jmax-replace-nonascii :: replace nonascii characters in a bibtex - entry. Replacements are in `jmax-nonascii-latex-replacements'. - -- jmax-title-case-article -- jmax-sentence-case-article - -- jmax-bibtex-next-entry :: bound to M-n -- jmax-bibtex-previous-entry :: bound to M-p - -- Functions to act on a bibtex entry or file - - jmax-bibtex-hydra/body :: gives a hydra menu to a lot of useful functions. - - jmax-bibtex-new-entry/body :: gives a hydra menu to add new bibtex entries. - - jmax-bibtex-file/body :: gives a hydra menu of actions for the bibtex file - -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. -You can do that like this before you require jmax-bibtex: - -#+BEGIN_SRC emacs-lisp -(setq jmax-bibtex-hydra-key-binding "\C-cj") -#+END_SRC - -Or this if you like key-chords: - -#+BEGIN_SRC emacs-lisp -(key-chord-define-global "jj" 'jmax-bibtex-hydra/body) -#+END_SRC - -* Appendix -** Customizing org-ref - :PROPERTIES: - :ID: 32B558A3-7B48-4581-982B-082017B0AEE8 - :END: -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: -#+BEGIN_SRC emacs-lisp -(setq reftex-default-bibliography '("~/Dropbox/bibliography/references.bib")) - -(setq org-ref-bibliography-notes "~/Dropbox/bibliography/notes.org" - org-ref-default-bibliography '("~/Dropbox/bibliography/references.bib") - org-ref-pdf-directory "~/Dropbox/bibliography/bibtex-pdfs/") -#+END_SRC - - - -* References -# <> -bibliography:org-ref.bib