An Absolute Beginners Guide to Spacemacs for Academic Writing – Part 2

Part 1 of this guide dealt mainly with installing and configuring Spacemacs.

Now for the academic writing part

If you now have Spacemacs installed and have used org-mode to write some text for an academic paper you will want to be able to enter citations and a bibliography and to be able to convert your org file to various formats like pdf and docx.

My purpose in developing this workflow was to be able to use org-mode in Spacemacs to write academic papers and also be able to export the finished product to Word for the professors to read and comment on. In order to use the open source tools I prefer, that requires going via the open document format used by LibreOffice.

I have experimented a bit and looked at a few other workflows that people have posted and come up with something that works for me. I use Zotero because it is open source, it is very good at grabbing references – and pdfs – off various resources on the web, has a number of powerful features, and has good tools and plug-ins available for working with plain text.

If you prefer to use Jabref, or other BibTeX tools rather than Zotero, if you don’t need to convert to Word, or if you just want to put together your own workflow, there are plenty of posts by good people that can help you with that.

My setup uses all free and open source software and works on Mac OS X, but it should also work on GNU/Linux using the appropriate package manager e.g. apt-get. Although some distributions do not come with emacs 24.4 or above as required by Spacemacs – e.g. Trisquel and Mint, you can search on Synaptic package manager for emacs snapshot and installing that will keep you up to date. If you experience issues on Ubuntu there are many resources on the web to address these. I have had no problems with installation on Linux Mint.

Ideally you will have a few spare GB on your hard drive – This workflow involves installing quite a lot of software. Don’t worry. You’re well on your way to becoming a super-user. If you haven’t already got them you will need to install the items below in the order I have listed them.

Please follow the instructions on the linked pages unless I have included “brew install” instructions. Note: Homebrew is optional as are a number of sections below which I have indented. These can safely be skipped if using up to date org mode and Zotero.

For my install instructions, enter the text after the $ (command prompt) that I have provided onto the command line of Terminal and press the Enter/Return key (this entering of text and pressing ENTER is often abbreviated to “enter” or just “do”).
Sometimes you will need to wait quite a while for the install process to finish and return you to the command prompt (yourusername $).

Don’t forget that, on a Mac, you can bring up Terminal through Spotlight by
Pressing Command+Space and typing Terminal and pressing the Enter/Return key

Install:

Firefox, by the Mozilla community: open source browser with good security and privacy features
https://www.mozilla.org/en-US/firefox/new/

Pandoc, by John MacFarlane: serious document conversion
http://pandoc.org/installing.html
tells you to that the simplest way to get the latest pandoc release is to use the installer.

You can still install by doing

$ brew install pandoc

but the pandoc site notes that if you are using macOS < 10.10, brew installs pandoc from source, which takes a long time and a lot of space for the ghc compiler and dependent Haskell libraries.

Here is the manual
http://pandoc.org/MANUAL.html

Note: citeproc should not be necessary if you are using Zotero as I do. Indented as optional

pandoc-citeproc, by John MacFarlane, Andrea Rossato, for rendering bibliographic reference citations into a variety of styles
https://github.com/jgm/pandoc-citeproc
To install do

$ brew install pandoc-citeproc

Here is the manual

For export directly from org-mode to pdf, LaTeX is required. However, in recent versions of Word and LibreOffice or OpenOffice you can save as pdf or export to pdf

I have therefore indented the following section as optional

MacTeX – by the contributors
https://tug.org/mactex/mactex-download.html
(or – if you are truly short of space – Basic Tex)
https://tug.org/mactex/morepackages.html

If you are on Ubuntu or similar, install TexLive with any extras you wish.
$ apt-get install texlive

LibreOffice, by the LibreOffice community: Open source office suite based on the OpenDocument Format – can export to docx, pdf and others
https://www.libreoffice.org/

Zotero for Firefox, by the developers:
Powerful open source reference manager that grabs citations and pdfs from the web
https://www.zotero.org/

Previously you had a choice of Zotero standalone, or, if using Firefox, Zotero as Add-on. However, with the release of Zotero 5 the Add-on version became obsolete, and instead, a connector is available for Firefox, Chrome, or Safari. If you are on Linux and you are in the social sciences, you may wish to have a look at Sebastian Mathôt’s collection of tools: https://www.linuxhelp.com/how-to-install-zotero-in-ubuntu/

You will want these Zotero Add-ons/Plug-ins (the list is here: https://www.zotero.org/support/plugins – they are also called “extensions” in Firefox ):

The Better Bib(La)TeX add-on, by Emiliano Heyns for drag-and-drop citations and more see https://github.com/retorquere/zotero-better-bibtex  Installation instructions here

right-click on the zotero-better-bibtex-(version).xpi and choose Save Link As

In Zotero, select Tools -> Add-ons -> Gear (upper right) -> Install Add-On from file, and install the downloaded xpi file.

zotxt, by Erik Hetzner: Cite items from your Zotero library while writing in plain text
https://github.com/egh/zotxt
A good comparison of zotxt and Better Bib(La)Tex add-on and set of instructions for installing zotxt is here

The RTF/ODF-Scan for Zotero add-on, by Frank Bennett, Sebastian Karcher: Insert citation markers into any document saved as .odt and convert those into active Zotero citations.
https://zotero-odf-scan.github.io/zotero-odf-scan/

Please note “Zoteros RTF-Scan seems to have some problems with umlauts used in Author names. So if you dragged & dropped an entry to your document it maybe looks ok, e.g. {Börtz & Döring, 2010}. When running RTF Scan the entry cannot be found, since Zotero destroys the “ö”s in the Authors names. Solution for now: Replace the umlauts in the Authors name with a different (but correct) writing: ö=oe, ü=ue, ä=ae. Just change the umlauts in the Authors names. The other umlauts in your entry can stay untouched, since they are not important for matching and linking during RTF Scan. So after sucessful alteration drag and drop again and it should look like this {Boertz & Doering, 2012}. This is a correct writing style and much better: RTF Scan works very well with it.” – Thanks to Bastian Wimmer.

Zutilo is a very useful add-on that lets you, among other things, right-click on a Zotero item (or cmd-right-click to select more than one) and copy the citations (use QuickCopy items to clipboard) to the clipboard for pasting to your editor.

These scannable cites appear like this: { | Klein, 2007 | | |zu:19876:X2QQZ4D3}. If you have many of these citations they can be a little distracting when you are writing and you may wish to hide them. Scrivener does this rather well with a separate closeable column (by the way, Scrivener for Linux is still available for free and works on older versions of linux if you want to check it out. It is a bit out of date, but you can test run the latest Windows version with wine. A nice alternative is Zettlr) My solution is simply to hide the scannable cites in footnotes.

SPC m i f

to insert footnote in Spacemacs org-mode.

Zotero plug-in for LibreOffice
https://www.zotero.org/support/word_processor_integration

Report Customizer by Emiliano Heyns is not yet compatible with Zotero 5 (Nov 2018)
https://github.com/retorquere/zotero-report-customizer

Recommended: – available in the Plug-ins collection

ZotFile, by Joscha Legewie: to automatically rename, move, and attach PDFs (or other files) to Zotero items

and ZoteroQuickLook, by mronkko – reproduces Mac quicklook function for Zotero attachemnts

Have a cup of coffee ..

Using Zotero to build a database of references is documented in their quick start guide

I recommend saving all items to the top-level “My Library” and organizing links to these items in collections and sub-collections

The section indented below is optional if using Zotero as your bibliography manager.

If you use a specific collection for citations in your current paper, you can export that collection for use by pandoc.

This will be your bibliography file for pandoc to work with. Right-click on the collection and select “Export Collection …” Choose Better BibLaTex as your Format and tick only “Keep updated”. Click OK and save the collection with the name of your choice in your folder with the documents you are currently working on. Now you have a “mybibliography.bib” file.

Now you need to set up RTF/ODF-Scan in Zotero. Follow the instructions under “From Zotero Client” at
http://zotero-odf-scan.github.io/zotero-odf-scan/

The section indented below is optional if using Zotero as your bibliography manager

Now, since you will want to specify the citation style for pandoc to use, you will need the .csl (Citation Style Language) file. For the sake of certainty I copied the style I use into my current documents folder, but Pandoc will check ~/.csl/ by default. Here’s how to do that:

Use the Mac Finder to search for your preferred citation style (mine is apa.csl) in your home folder (Zotero has it there). On my system it can be found at /Users/christopherpoor/Library/Application Support/Firefox/Profiles/nhlkm2qb.default-1455547641581/zotero/styles

Alternatively you can download the styles you want from http://citationstyles.org/styles/ by following their instructions.

Copy and paste the csl file into the folder where the documents you want to convert are stored. This a “quick and dirty” solution. Alternatively, within your pandoc command, you could point to the style saved elsewhere with
--csl=/path/to/style-file.csl

Now to convert your org file using pandoc.

However, note that since version 1.17.2 pandoc supports the H export option in Emacs which controls the level below which headlines are converted into list items. The Emacs default is 3 heading levels. This is also the case in org-mode. To avoid having heading levels below level 3 exported as lists you can add

#+OPTIONS: H:9

at the top of your org-mode file. See the orgmode documentation for details (thanks to tarleb for this pointer).

Your file can now simply be exported by using

SPC SPC org-pandoc-export-to-odt

This is straight-forward and currently appears to give the best result. (It is also possible to use pandoc in Terminal or in pandoc-mode within Spacemacs. To do the latter see  pandoc layer page and for an explanation of all the options offered by pandoc-mode, see the Pandoc-mode website.)

The section indented below is optional if using Zotero as your bibliography manager

To run pandoc in the Terminal : Open Terminal and use the cd command to navigate to the folder with the document to be converted.

If any of your folder names contain spaces see my Command Line Tips

In pandoc you can use the default ODT reference template.

You need to enter your version of this on one line of the command line

$ pandoc --filter pandoc-citeproc --csl=apa.csl --bibliography=mybibliography.bib myfile.org -o myfile.odt

or

$ pandoc --filter pandoc-citeproc --csl=/path/to/style-file.csl --bibliography=mybibliography.bib myfile.org -o myfile.odt

if you saved the .csl file elsewhere.

Press Enter.

For a full list of possible conversions see the Pandoc documentation.

Now, in Zotero, click on RTF/ODF Scan in the Tools menu. Select “ODF (to citations)” as file type, and select your .odt file exported in the step above as the input, and your desired output file – a name with (citations) appended will be offered. Click “Next” and the plugin will convert the citations in your document.
You now have an odt document with live Zotero citations. Open it in LibreOffice.

What I have found is that endnotes from org mode now appear as footnotes in LibreOffice. If you want them to be endnotes I believe you need to make the conversion in Word. But first you will want to insert a Bibliography.

Add a page break at the end of your document and then click the Add/Edit Bibliography button in the LibreOffice Zotero toolbar.

The process may take some time and may require you to make some interactive corrections. Note that if a citation contains more than one item, the first one is referred to by Zotero as “item 0.”

In order to produce a Word document with citations, what I do now is a Zotero “Refresh” by clicking the turning arrows tool in the LibreOffice Zotero toolbar.
This gives two options: Save citations as “Reference Marks” or as “Bookmarks.” I save as “Reference Marks” (this gives me the correct apa format and is also compatible with citations inserted in foot/endnotes).

Now you can save the document in LibreOffice as docx document. The resulting document can be opened in Word (and footnotes converted to endnotes if desired) but the citations cannot be edited with Zotero. In any case, I would not recommend editing the document in Word or else you will end up with different versions of the thing you’re still working on. The real use of the .docx file is to share with people who use only Word. Unless you are nearly done, it is probably more productive (assuming that you are enjoying the Spacemacs experience) to file these .odt and .docx files away and continue writing in Spacemacs.

As noted above, Org-mode supports footnotes out of the box.

To re-order/re-number your footnotes correctly (the newest one is just added to the top of the footnotes section by default) use

SPC SPC org-footnote-normalize

Back to Part 1   —   Open Spacemacs cheat sheet — Go on to Spacemacs Basics

License

Copyright © 2016 Christopher J Poor. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

Code in this document is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This document and its code are distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details <http://www.gnu.org/licenses/>.