+++ /dev/null
-#+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 link>>
-bibliography:org-ref.bib
projects / org-ref.git / blobdiff