Part 2

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, say, Docear, BibTeX or Jabref 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 or apt-get (although some distributions do not come with emacs 24.4 or above as required by Spacemacs – e.g. Trisquel – and some users report issues on Ubuntu. 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.

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/

Homebrew, by Mark Howell: package manager for Mac OS
http://brew.sh/

Pandoc, by John MacFarlane: serious document conversion
http://pandoc.org/installing.html
tells you to install pandoc by doing

$ brew install pandoc

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

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

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

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/

You have a choice of Zotero standalone, or, if using Firefox, Zotero as Add-on. However, although, with the release of Zotero 5 the Add-on version will become obsolete, at present I recommend the Firefox add-on version. On Linux you may wish to follow the instructions as https://www.linuxhelp.com/how-to-install-zotero-in-ubuntu/ You will also want to install the connector for your chosen browser. There is a choice of Firefox, Chrome or Safari.

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
https://github.com/retorquere/zotero-better-bibtex

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/

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

Zotero Report Customizer by Emiliano Heyns
https://github.com/retorquere/zotero-report-customizer

Recommended: – available in the Firefox Add-ons collection under the Tools menu (hint – scroll down to “see more add-ons!”)

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

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/

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. 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. This can be done simply by using

SPC SPC org-pandoc-export-to-odt

This appears to give the best result as long as your style file is in the same folder as your org file. You can also 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.

To run pandoc on 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.

Then, in Zotero, click on RTF/ODF Scan in the gears/action menu. Select “ODF (to citations)” as file type and select your saved file as the input and your desired output file. Click “Next” and the plugin will convert the citations in your document.
You now have an odt document with live Zotero citations.

You next want 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).

Now you can save the document in LibreOffice as docx document. The resulting document can be opened in Word 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.

And footnotes? 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   —   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/>.

6 thoughts on “Part 2

  1. Thanks for this post. I’ve been using Spacemacs for programming/academic writing but I’ve recently gone through some pretty miserable experiences getting .org files into .odt/.docx. What I love about this approach is:

    – Working in Spacemacs is incredibly faster than any word processor
    – You can embed images in .org that render in .odt/.docx
    – Organizing a paper into sections is way easy
    – Pandoc seems to work pretty well

    What I’m still having a hard time with is:

    – Altering figure/table number and styles.
    – Centering images
    – Creating tables. I know that this is possible with .org tables, but org’s functionality here seems lacking. E.g. I can’t seem to create merged/nested columns.
    – Changing font/pitch.

    It seems as though most (not the table stuff) has to do with LibreOffice settings rather than org/spacemacs. Do you have any tips on how to deal with these issues?

    Like

    1. I’m afraid I don’t use these features of org.mode so I have to refer you to their forum. You can also ask on Reddit and Stackexchange. I will have a look at it when I get back home. I’m currently in Shanghai.

      Like

  2. This is a great beginner series, thank you for sharing. Will there be third part with focus on Auctex and advanced editing within spacemacs (snippets, surround etc)?

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s