From: John Kitchin Date: Sun, 15 Mar 2015 20:57:58 +0000 (-0400) Subject: still adding documentation X-Git-Url: https://git.donarmstrong.com/?p=org-ref.git;a=commitdiff_plain;h=c3d7aaa5d0202053e1d1b68136d804504705c07a still adding documentation --- diff --git a/org-ref.org b/org-ref.org index 9bca7c2..bc84328 100644 --- a/org-ref.org +++ b/org-ref.org @@ -1,24 +1,30 @@ #+TITLE: The org-ref manual #+AUTHOR: John Kitchin #+DATE: 2015-03-15 Sun +#+OPTIONS: toc:nil ^:{} +#+LATEX_HEADER: \usepackage{natbib} +\maketitle +\tableofcontents * 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. +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. -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. +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. -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 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. org-ref is [[id:32B558A3-7B48-4581-982B-082017B0AEE8][customizable]]. -** Basic usage of org-ref +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. + +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. -*** Sources of bibtex entries +** Basic usage of org-ref *** 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. +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. -There is also a bibliographystyle link that specifies the style. This link does nothing but export to \bibliographystyle{link-string}. +There is also a bibliographystyle link that specifies the style. This link does nothing but export to a LaTeX command. 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. @@ -26,19 +32,31 @@ If you use biblatex, then you use an addbibresource link. biblatex support is no :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. +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. + +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. -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... +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. +Here is a list of supported citation types. You can customize this if you want. +#+BEGIN_SRC emacs-lisp :results code +org-ref-cite-types +#+END_SRC + +#+RESULTS: +#+BEGIN_SRC emacs-lisp +("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") +#+END_SRC + 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]]. +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}. You may want to bind a hydra menu to a key-binding or key-chord. For example: @@ -84,14 +102,13 @@ To help you insert ref links, use the "Org->org-ref->Insert ref" menu, or run th 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. +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 -org-ref provides a pageref, nameref and eqref link. +**** Miscellaneous ref links label:sec-misc +org-ref also 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} @@ -106,7 +123,26 @@ We change the order of the actions in helm-bibtex to suit our work flow, and add ** 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-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: + +1. adds a comma if needed in the first line of the entry +2. makes sure the doi field is an actual doi, and not a url. +3. fixes bad year entries +4. fixes empty pages +5. Escapes & to \& +6. generate a key according to your setup +7. Runs your hook functions +8. sorts the fields in the entry +9. checks the buffer for non-ascii characters. + +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. + +#+BEGIN_SRC emacs-lisp +(add-hook 'org-ref-clean-bibtex-entry-hook 'jmax-replace-nonascii) +#+END_SRC + +#+RESULTS: +| jmax-title-case-article | jmax-replace-nonascii | org-ref-extract-bibtex-entries will create a bibtex file from the citations in the current buffer. @@ -184,28 +220,59 @@ researcherid:A-2363-2010 ** jmax-bibtex These are functions I use often in bibtex files. -- jmax-bibtex-generate-longtitles -- jmax-bibtex-generate-shorttitles +*** Generate new bibtex files with adapted journal names +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: + +#+BEGIN_SRC emacs-lisp +(add-to-list 'jmax-bibtex-journal-abbreviations + '("JIR" "Journal of Irreproducible Research" "J. Irrep. Res.")) +#+END_SRC + +- jmax-bibtex-generate-longtitles :: Generate a bib file with long titles as + defined in `jmax-bibtex-journal-abbreviations' +- jmax-bibtex-generate-shorttitles :: Generate a bib file with short titles as + defined in `jmax-bibtex-journal-abbreviations' + +*** Modifying bibtex entries + - 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. + with a string selected interactively. + +- jmax-title-case-article :: title case the title in an article entry. +- jmax-sentence-case-article :: sentence case the title in an article entry. - jmax-replace-nonascii :: replace nonascii characters in a bibtex - entry. Replacements are in `jmax-nonascii-latex-replacements'. + entry. Replacements are in `jmax-nonascii-latex-replacements'. This + function is a hook function in org-ref-clean-bibtex-entry. + +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. + +#+BEGIN_SRC emacs-lisp +(add-to-list 'jmax-nonascii-latex-replacements + '("æ" . "{\\\\ae}")) +#+END_SRC + +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: + +#+BEGIN_SRC emacs-lisp +(bibtex-map-entries 'jmax-title-case-article) +#+END_SRC + -- jmax-title-case-article -- jmax-sentence-case-article +*** Bibtex entry navigation - jmax-bibtex-next-entry :: bound to M-n - jmax-bibtex-previous-entry :: bound to M-p +*** Hydra menus for bibtex entries and files - 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-hydra/body :: gives a hydra menu to a lot of useful functions + like opening the pdf, or the entry in a browser, or searching in a + variety of scientific search engines. - 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 + - 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: @@ -214,7 +281,7 @@ You can do that like this before you require jmax-bibtex: (setq jmax-bibtex-hydra-key-binding "\C-cj") #+END_SRC -Or this if you like key-chords: +Or this if you like key-chord: #+BEGIN_SRC emacs-lisp (key-chord-define-global "jj" 'jmax-bibtex-hydra/body) @@ -239,5 +306,6 @@ Here is my minimal setup: * References +bibliographystyle:unsrt # <> bibliography:org-ref.bib