#+title: July 2021 #+subtitle: Introducing citations! #+author: TEC #+date: 2021-07-31 Last month I not-at-all-subtly hinted that a certain long-awaited feature was arriving imminently. At this point, I think it's a good idea to set the tone for the rest of this post. #+attr_latex: :options inkscapelatex=false [[file:figures/celebrate-citations.svg]] * Citations After /years/ of (on and off) discussion[fn:1], I am elated to be able to present Org's new native citation syntax. Org has grown a thoroughly designed, modular, capable citation system. At last you can refer to Org for all your attribution needs. Special thanks must go to Nicolas Goaziou for leading the charge, John Kitchin for paving the way with the =org-ref= package, Bruce D'Arcus for driving a lot of careful consideration of design decisions and starting to document some of the details --- and the many other denizens of the mailing list who have contributed to the discussion over the years. András Simonyi's also deserves a special mention for his work creating the Elisp CSL library ~Citeproc.el~, which while not directly included in Org is crucial to providing robust CSL support, and integrates with =oc-csl.el=. ** Outline Citations have been carefully designed in such a way that users and Elisp tinkerers will be able to easily adapt and extend it to fit their needs. To that end, Org Cite (or OC for short) has been split into two halves: + =oc.el= which defines the syntax and provides some machinery to interact with citations + Citation processors which interface with =oc.el= to produce nicely-formatted citations to be inserted in your bibliography, within the text, and even rendered in the buffer[fn:2] There are four capabilities that Org Cite uses the processors for 1. Inserting and editing citations 2. Following citations to their definition 3. Fontifying the citations in the buffer 4. Exporting the citations Each capability can have a particular citation processor assigned, independently of the others. Out of the box, Org uses the =basic= processor for all of these tasks. The =basic= citation processor is one of four currently bundled with Org: + =basic=, which has no dependencies and provides all four capabilities. It export to all formats, but only provides very simple citations. + =biblatex= and =natbib=, which provide the export capability to create citations via [[http://biblatex-biber.sourceforge.net/][Biber]] and (to a lesser extent) [[https://ctan.org/pkg/natbib][natbib]], but only for LaTeX. + =csl=, which provides the export capability using the [[https://citationstyles.org/][Citation Style Language]], and exports to HTML, LaTeX, Org, and plain text (with an [[https://github.com/andras-simonyi/citeproc-el/issues/23][open issue]] for ODT) --- but depends on [[https://github.com/andras-simonyi/citeproc-el][citeproc.el]]. This provides a solid foundation for other packages to build off, and despite Org Cite being yet to be released or documented in the manual we are already seeing the development of packages like [[https://github.com/jkitchin/org-ref-cite][org-ref-cite]] (by John Kitchin). ** Basic usage To get started with Org Cite, we must have some form of bibliography. This can either be a BibTeX file or a CSL-JSON file. As an example, say we have a file =orgcite.bib= containing the following #+begin_src bibtex :tangle orgcite.bib :comments none @article{OrgCitations, author={org, mode and Syntax, Citation and List, Mailing and Effort, Time}, journal={Journal of Plain Text Formats}, title={Elegant Citations with Org-Mode}, year={2021}, month={7}, volume={42}, number={1}, pages={2-3}} #+end_src First we need to let Org know about this bibliography file (which must have a =.bib=, =.bibtex=, or =.json= extension), which we do either via the =#+bibliography= keyword, or the variable ~org-cite-global-bibliography~. #+begin_example ,#+bibliography: orgcite.bib #+end_example #+bibliography: orgcite.bib Once you have a bibliography source, you can start referencing to your heart's content! The basic citation syntax is as follows: #+caption: The new citation syntax, for simple citations #+attr_latex: :width 0.5\linewidth :options inkscapelatex=false [[file:figures/citation-structure-basic.svg]] Using the default style =[cite:@OrgCitations]= produces [cite:@OrgCitations]. For more information on the styles currently available, see [[cite-styles]]. Finally, to insert a bibliography somewhere, we just need to insert the =#+print_bibliography= keyword, like so: #+begin_example ,#+print_bibliography: #+end_example #+begin_info #+print_bibliography: #+end_info So, to summarise, all one needs to get started is: #+begin_example ,#+bibliography: references.bib [cite:@key] ,#+print_bibliography: #+end_example That's it! 🎉 ** The cite syntax Don't let the simplicity in the examples above fool you, the new syntax is quite capable of expressing more complex forms. Here's the /full/ version of the new cite syntax: #+caption: The new citations syntax, in full #+attr_latex: :options inkscapelatex=false [[file:figures/citation-structure-full.svg]] + The *style* and *variant* determine what form the exported citation takes + The *common prefix* and *suffix* and put at the start and end of the generated citation, respectively + The citation *key* refers to a Bib(La)TeX or CSL-JSON key - The citation *prefix* and *suffix* are put before and after the reference to the key - Some citation processors recognise locators, which refer to a particular part of the work, for example: =p. 7= to refer to page 7. Using the default CSL citation style (Chicago author-name) =[cite/l/b:see @OrgCitations pp. 7 for fun]= becomes [cite/l/b:see @OrgCitations pp. 7 for fun]. The citation styles and variants, and recognised locators are handled by the citation processors. Org cite's bundled processors currently supports the following citation styles. #+name: cite-styles #+caption: The current set of supported citation styles with variants, #+caption: with samples generated by ~oc-csl.el~ and ~citeproc.el~. #+attr_latex: :font \small | Style | Variant | Sample | Bib(La)TeX | NatBib | |-------------+--------------------+---------------------------------+-------------+-------------| | =a= author | =cf= caps-full | [cite/a/cf:@OrgCitations] | Citeauthor | | | =a= author | =f= full | [cite/a/f:@OrgCitations] | citeauthor | citeauthor* | | =a= author | =c= caps | [cite/a/c:@OrgCitations] | Citeauthor* | Citeauthor | | =a= author | | [cite/a:@OrgCitations] | citeauthor* | citeauthor | |-------------+--------------------+---------------------------------+-------------+-------------| | =na= noauthor | =b= bare | [cite/na/b:@OrgCitations] | | citeyear | | =na= noauthor | | [cite/na:@OrgCitations] | autocite* | citeyearpar | |-------------+--------------------+---------------------------------+-------------+-------------| | =l= locators | =bc= bare-caps | [cite/l/bc:@OrgCitations p. 2] | Notecite | | | =l= locators | =b= bare | [cite/l/b:@OrgCitations p. 2] | notecite | | | =l= locators | =bc= caps | [cite/l/bc:@OrgCitations, p. 2] | Pnotecite | | | =l= locators | | [cite/l:@OrgCitations, p. 2] | pnotecite | | |-------------+--------------------+---------------------------------+-------------+-------------| | =n= nocite | | [cite/n:@OrgCitations] | nocite | nocite | |-------------+--------------------+---------------------------------+-------------+-------------| | =t= text | =b= bare | [cite/t/b:@OrgCitations] | | citealp | | =t= text | =c= caps | [cite/t/c:@OrgCitations] | Textcite | Citep | | =t= text | =f= full | [cite/t/f:@OrgCitations] | | citep* | | =t= text | =bc= bare-caps | [cite/t/bc:@OrgCitations] | | Citealp | | =t= text | =bf= bare-full | [cite/t/bf:@OrgCitations] | | citealp* | | =t= text | =cf= caps-full | [cite/t/cf:@OrgCitations] | | Citep* | | =t= text | =bcf= bare-caps-full | [cite/t/bcf:@OrgCitations] | | Citealp* | | =t= text | | [cite/t:@OrgCitations] | textcite | | |-------------+--------------------+---------------------------------+-------------+-------------| | (default) | =b= bare | [cite//b:@OrgCitations] | cite | citealp | | (default) | =bc= bare-caps | [cite//bc:@OrgCitations] | Cite | Citealp | | (default) | =f= full | [cite//f:@OrgCitations] | | citep* | | (default) | =bf= bare-full | [cite//bf:@OrgCitations] | | citealp | | (default) | =cf= caps-full | [cite//cf:@OrgCitations] | | Citep* | | (default) | =bcf= bare-caps-full | [cite//bcf:@OrgCitations] | | Citealp* | | (default) | | [cite:@OrgCitations] | autocite | citep | The CSL processor supports the following locators: + *=book=*, =bk.=, =bks.= + *=chapter=*, =chap.=, =chaps.= + *=column=*, =col.=, =cols.= + *=figure=*, =fig.=, =figs.= + *=folio=*, =fol.=, =fols.= + *=number=*, =no.=, =Os.= + *=line=*, =l.=, =ll.= + *=note=*, =n.=, =nn.= + *=opus=*, =op.=, =opp.= + *=page=*, =p=, =p.=, =pp.= + *=paragraph=*, =para.=, =paras.=, =¶=, =¶¶=, =§=, =§§= + *=part=*, =pt.=, =pts.= + *=section=*, =sec.=, =secs.= + *=sub verbo=*, =s.v.=, =s.vv.= + *=verse=*, =v.=, =vv.= + *=volume=*, =vol.=, =vols.= ** More on exporting The style of the citations and the bibliography depend on three things: 1. The citation processor used 2. The citation style 3. The bibliography style The citation processor is automatically selected based on ~org-cite-export-processors~ based on the export format being used, but can be set on a per-document basis via the =#+cite_export= keyword. Here, I shall use the =csl= processor, #+begin_example ,#+cite_export: csl #+end_example #+cite_export: csl With ~org-cite-export-processors~, you can also set the bibliography and citation style by giving a triplet of parameters src_elisp{(PROCESSOR BIBLIOGRAPHY-STYLE CITATION-STYLE)} instead of just the processor. You can also use this triplet of values with the =#+cite_export= keyword #+begin_example ,#+cite_export: processor bibliography-style citation-style #+end_example There are also some more options about how the bibliography is produced. These options are handled by the active citation processor. For example, while the CSL processor does not currently support any options, the BibLaTeX processor passes options to a src_LaTeX{\printbibliography} command, allowing for the following: #+begin_example ,#+print_bibliography: :section 2 :heading subbibliography ,#+print_bibliography: :keyword abc,xyz :title "Primary Sources" #+end_example ** Using CSL [[https://github.com/andras-simonyi/citeproc-el][Citeproc]] is currently available on [[https://melpa.org/#/citeproc][MELPA]], and so can be installed via your package manager of choice so long as MELPA is included in your ~package-archives~. When available, it will be automatically loaded by =oc-csl.el=. It currently supports exporting to: + HTML + LaTeX + Org + Plain text Should you be interested in other formats, know that Citeproc is designed to easily support adding new formats (see =citeproc-formatters.el= for examples). Citeproc can currently retrieve bibliographic information from the following formats: + CSL-JSON + Bib(La)TeX + org-bibtex Though support for Bib(La)TeX and [[https://gewhere.github.io/org-bibtex][org-bibtex]] is rudimentary compared to CSL-JSON. When exporting, you can set the style by providing a path to CSL style files, either absolute or relative to ~org-cite-csl-styles-dir~. For example, if I download =apa.csl= I can use it like so: #+begin_example ,#+cite_export: csl ~/Downloads/apa.csl #+end_example When no style is given ~org-cite-csl--fallback-style-file~ will be used, which defaults to a bundled Chicago author-date style. ** Working with Zotero There are quite a few reference managers available, however, the list rapidly shrinks if you restrict yourself to applications which are: + somewhat feature-rich + open source software + not owned by a parasitic company[fn:3] [[https://www.zotero.org/][Zotero]] is a good option, and if you're using it it's quite easy to use it with Org Cite. Out of the box, you can tell it to export your library, or parts of it, to a =.bib= file and automatically keep it in sync. I'd recommend installing the [[https://retorque.re/zotero-better-bibtex/][Better BibTeX]] extension though. #+caption: Zotero library right click context menu, showing the export option #+attr_latex: :width 0.4\linewidth #+attr_html: :class invertible [[file:figures/zotero-export-library.png]] #+caption: Zotero collection export dialog #+attr_latex: :width 0.3\linewidth #+attr_html: :class invertible [[file:figures/zotero-export-options-prompt.png]] Zotero also works well with CSL. In addition to supporting CSL-JSON exports, Zotero also features an easy way to install CSL styles within the preferences. #+caption: Zotero CSL style management within preferences #+attr_latex: :width 0.6\linewidth #+attr_html: :class invertible [[file:figures/zotero-cite-styles-menu.png]] Since these files are put under =~/Zotero/styles=, you can use them with Org Cite and Citeproc simply by setting ~org-cite-csl-styles-dir~ to the Zotero styles directory. #+begin_src emacs-lisp (setq org-cite-csl-styles-dir "~/Zotero/styles") #+end_src To then use the citation style defined by =~/Zotero/styles/apa.csl= one can then simply refer to =apa.csl= when using the =#+cite_export= keyword. #+begin_example ,#+cite_export: csl apa.csl #+end_example ** A bright future Org Cite has only just been merged in the past month, and is yet to be included in an Org release, but we're seeing a tremendous degree of community interest. There are /already/ promising developments with third-party packages, such as [[https://github.com/bdarcus/bibtex-actions][bibtex-actions]] and [[https://github.com/jkitchin/org-ref-cite][org-ref-cite]]. I can't wait to see how the ecosystem continues to develop 😃. * Footnotes [fn:1] Citations were first being mentioned on the mailing list back in 2007, in [[https://lists.gnu.org/archive/html/emacs-orgmode/2007-05/msg00146.html][a thread about footnotes]]. [fn:2]There is currently an [[https://github.com/andras-simonyi/org-cite-csl-activate][ongoing effort]] to use =oc.el= and =citeproc.el= to produce citation overlays in the buffer. [fn:3] I'm talking about a certain company [[https://moneyweek.com/505757/great-frauds-in-history-robert-maxwell][created by a British Fraudster]] that has a [[https://www.theguardian.com/science/2017/jun/27/profitable-business-scientific-publishing-bad-for-science][40% profit margin, engages in blackmail-like practices with universities]], prompted [[http://thecostofknowledge.com/][19,000 researchers]] to boycott them, [[https://www.the-scientist.com/the-nutshell/elsevier-published-6-fake-journals-44160][published six fake journals]], vigorously [[https://web.archive.org/web/20200129202353/http://legacy.earlham.edu/~peters/fos/2007/08/publishers-launch-anti-oa-lobbying.html][lobbys against Open Access]], [[https://rossmounce.co.uk/2017/02/14/elsevier-selling-access-to-open-access-again/][charged for Open Acess articles]] (repeatedly), made [[https://www.michaeleisen.org/blog/?p=807][financial contributions to politicians who then tried to prevent publicly accesible reaserch]], and whose reference manager [[https://www.zotero.org/support/kb/mendeley_import#mendeley_database_encryption][encrypted reaserchers' /own/ databases]] "to comply with GDPR".