diff --git a/assets/figures/celebrate-citations.svg b/assets/figures/celebrate-citations.svg new file mode 100644 index 0000000..0019ce5 --- /dev/null +++ b/assets/figures/celebrate-citations.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:12b9a81ef4aa491af60ea8dda8cfa9011650dd1c866429ddbca1cfb2578bfd4f +size 109387 diff --git a/assets/figures/citation-structure-basic.svg b/assets/figures/citation-structure-basic.svg new file mode 100644 index 0000000..7d7221b --- /dev/null +++ b/assets/figures/citation-structure-basic.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:73f9724896e0b2fc0ca1d2d19b2dd976edb0c9f5b01b634c69ecfedc459267e9 +size 73914 diff --git a/assets/figures/citation-structure-full.svg b/assets/figures/citation-structure-full.svg new file mode 100644 index 0000000..4b87416 --- /dev/null +++ b/assets/figures/citation-structure-full.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cdf3d2e64b835a61bd40e9250ae88239e4e99cf534ddd97537d531550f68a3ce +size 154385 diff --git a/assets/figures/zotero-cite-styles-menu.png b/assets/figures/zotero-cite-styles-menu.png new file mode 100644 index 0000000..68a3212 --- /dev/null +++ b/assets/figures/zotero-cite-styles-menu.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:506b3945e815d740b5be4d13198512e186099a7c6a9eb805a57487557c1aea54 +size 74217 diff --git a/assets/figures/zotero-export-filename-prompt.png b/assets/figures/zotero-export-filename-prompt.png new file mode 100644 index 0000000..dc435aa --- /dev/null +++ b/assets/figures/zotero-export-filename-prompt.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d2878766c9a197b73590a8f82cb6d407a6a7d3ce607a0906286a4dd7d77fc73d +size 44713 diff --git a/assets/figures/zotero-export-library.png b/assets/figures/zotero-export-library.png new file mode 100644 index 0000000..9db465f --- /dev/null +++ b/assets/figures/zotero-export-library.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d73bd8f3bf90abd978a548ba0dbc029eec52184c7b5185e0fa9d8db77222b697 +size 26295 diff --git a/assets/figures/zotero-export-options-prompt.png b/assets/figures/zotero-export-options-prompt.png new file mode 100644 index 0000000..dacd967 --- /dev/null +++ b/assets/figures/zotero-export-options-prompt.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:59de7034661625fdb0093ddb56d371f351d3fa9dbffdeaee360210e35f597bd3 +size 16594 diff --git a/content/2021-07-31-citations.org b/content/2021-07-31-citations.org new file mode 100644 index 0000000..2053176 --- /dev/null +++ b/content/2021-07-31-citations.org @@ -0,0 +1,334 @@ +#+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". diff --git a/content/orgcite.bib b/content/orgcite.bib new file mode 100644 index 0000000..e4e84a9 --- /dev/null +++ b/content/orgcite.bib @@ -0,0 +1,9 @@ +@article{OrgCitations, + author={org, mode and Syntax, Citation and List, Mailing and Effort, Time}, + journal={Journal of Plain Text Formats}, + title={Elagent Citations with Org-Mode}, + year={2021}, + month={7}, + volume={42}, + number={1} + pages={2-3}}