This site will soon include a new workflow for Research Note-taking in Zotero. The beta version (soon to be Zotero 6) has many enhancements to assist in note-taking.

---

---

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

Apologies for not having updated this guide recently. However, Parts 1 & 2 were updated on November 2018 and should now be more useful. I also added the Tips page. Some key-bindings in the cheat sheet are now out of date (for example spare tree is now invoked with , s s). I will be updating the cheat sheet when I have time.

This guide is in two parts. Part 1 covers downloading and installing. Part 2 addresses the academic writing configuration and usage – in particular, integration with Zotero.

A note on conventions for user guides:

Many guides, such as the excellent – and brief – O’Reilly’s Learning the Unix Operating System, use typewriter fonts like courier for commands, and refer to keys by the lower case letter. One letter this can be confusing for is “l” which looks very similar to “1” in courier. In this guide, where it is not obvious, I will refer to a lower case “L” as “the letter l” and the numeral “1” as “the number 1.”

Part 1. Getting Started

I use my computer mostly for writing academic prose (I am not a coder, although I wrote a few wee scripts when I had Windows for Workgroups on an early PC). I wrote this guide for absolute beginners who don’t mind looking under the hood of their Mac or PC and who long for a truly elegant and efficient way of writing – for many, that means using plain text.

One of my main requirements in a writing app is good support for outlines – and for me that includes text folding.

To use these very handy writing features in plain text, the way to go for many people is writing in Markdown, which is a simple way to add formatting like headings, bold, bulleted lists and similar extras to plain text. Emacs (and Spacemacs) org-mode implements these same features and more.

There are many websites you can visit to find out more about Markdown. Here‘s one.

Org-mode in Emacs and Spacemacs has great folding and outlining support. I also want to be able to use footnotes or endnotes and citations (more about these in Part 2).

Before settling on Spacemacs I have used

TextWrangler – It has poor folding support and does not support Markdown out of the box. If you are on High Sierra or above you are recommended to upgrade to BBEdit free (if you want to implement Markdown for HTML in TextWrangler this video tells you how), and TextMate, but I really wanted to go the Free and Open Source (foss) route, partly because I think the foss community is marvellous – so I also tried out

Atom – which I like and has various packages available for writers but not of the quality and range you’ll find in Spacemacs and org-mode.

Having briefly tried Emacs and Vim, Spacemacs seemed like a good option for a plain text editor. Here are some of my reasons for and against:

Spacemacs pros and cons

Pros

• Spacemacs allows you to use the more ergonomic keyboard shortcuts (key bindings) of Vim – these are known as “evil” keybindings – but has the broader customisation options of Emacs. This happy combination by the brilliant folks at Spacemacs leaps over a lot of the issues in what has been called “the editor wars” between fans of Emacs and Vim.
• Discovery of key bindings is made easy with “which-key.” All the key bindings are accessible by pressing the space bar, making for a very ergonomic setup.
• Key bindings are organised using mnemonic prefixes like b for buffer, p for project, s for search, h for help etc.
• To quote from But She’s a Girl: Essentially, Spacemacs is a starter kit for Emacs, but one that includes some very clever default configuration and choice of packages, which magically makes it more than the sum of its parts.

• A nicely designed, minimalist GUI promotes distraction free writing.

• Spacemacs comes with “batteries included” with hundreds of ready-to-use packages well organised in easy to install configuration layers.  This is a great simplification compared the configuration of Emacs packages. Many of these packages are useful for writers.

• Org-mode gives great outlining, note-taking and much more.Org Mode implements its own markup language, similar to Markdown, but more powerful. It can export to Markdown, PDF, and other formats.

• The Markdown layer adds Markdown support to Spacemacs.

• Spacemacs’ wealth of features keep out of the way when you don’t use them and the documentation is very comprehensive.

Cons

Emacs and Spacemacs are unfamiliar to first time users due to

• Use of a different lexicon (jargon) from most text editors. Here is a good resource for understanding these differences, but note that Spacemacs has recently improved the clarity of this lexicon, especially with respect to “close” “kill” and “delete” simplifying the notion of “closing/deleting” things under the d key for delete. For example, they moved SPC w c and SPC w C to SPC w d and SPC w D. So this part is a pro – the folks at Spacemacs concentrate on making things sensible.

• A user interface that requires you to change states (however see this thread) and encourages you to use the command-line-like mini-buffer (although menus are available in the GUI).

• Also, the documentation is not entirely beginner friendly (a beginner tutorial has recently been written – find it here), but it is very comprehensive and is constantly improving. Although Spacemacs is now fairly mature, it is still officially in Beta (as of December 2018).
• Some of the keybindings were changed in early Beta and you could find that some of the less used ones may have changed recently. However, this may also be done by the Org-mode or Emacs teams.

Here is a longer list of pros and cons including Emacs.

For an option that is not still Beta you might like to investigate Emacs in Evil-mode.

Preparation

If you want to try Spacemacs you will need to know

• The basics of how Emacs works – here is a good resource – you won’t want to learn the Emacs commands (SPC is better). Jess Hamrick has written an excellent beginner’s guide to Emacs. Sacha Chua also has good tips for learning Emacs. Spacemacs also has its own Beginner’s Tutorial, which I highly recommend.

• The differences between Emacs and Spacemacs – mainly that M-x has been replaced by SPC SPC This is the Spacemacs command key SPC (executed after the leader key – SPC) and it can be changed with the variable dotspacemacs-emacs-command-key of your ~/.spacemacs. If you find that your version has the old SPC : as command key, you can change it in your dotspcacemacs file. See the line “Open your .spacemacs file … ” below). Also, that there are different “states” (referred to as “modes” in Vim) – in particular: “normal” and “insert.”

To use Emacs (or Vim) it helps to be reasonably comfortable using the command line in Terminal. This is also true for Spacemacs.

If you need to get up to speed with the command line (and release your inner geek) there are some good tutorials for that such as http://linuxcommand.org and another

I highly recommend that you work through the first seven or eight pages of the linuxcommand.org tutorial, up to and including “Working with Commands.”

The OS X Terminal opens up a world of powerful UNIX utilities and scripts.

Although you can run Spacemacs as an app with a regular user interface, it is well worth having some knowledge of the command line and the bash shell.

Installing

You will want to be logged on to an account with administrator capability. In Mac OS X and Ubuntu and Linux Mint the default user account can perform administrator functions by entering the user’s password. For my install instructions, enter the text that I have provided,  onto the command line of Terminal, after the $ (command prompt), and press the Enter/Return key (this entering of text and pressing ENTER is often abbreviated to simply “Enter” or “do”).

Sometimes you will need to wait quite a while for the install process to finish and return you to the command prompt (yourusername $).

You can try Spacemacs without modifying your existing Emacs.

If you decide to install Spacemacs ….

For Windows users this tutorial should suffice.

I use mostly Mac OS X and Linux Mint so my experience and suggestions are based on that.

The first thing to do is install the recommended version of Emacs – see Prerequisites on the this page (or see the adjacent section for your operating system)

which says that the recommended way of installing Emacs on Mac OS is using the package manager, Homebrew. To install Homebrew,  (package manager for Mac OS by Mark Howell) go to http://brew.sh/ then, with homebrew installed,  you can do

$ brew tap d12frosted/Emacs-plus

$ brew install emacs-plus

$ brew linkapps emacs-plus

Note the number following d in the first line is twelve (hint: copy and paste).

THE INSTALLATION WILL TAKE SOME TIME. When I last performed this installation emacs-plus needed to be built from source (not the case on Sierra and High Sierra because it is “bottled” ready to pour.) This may cause an error message but is not a problem. On Yosemite or prior expect several minutes, at least, for the installation (depends on your machine) – but it can be unattended.

Brew may also give a WARNING about “linkapps” being deprecated. However, it should still work.

Then follow the Spacemacs install instructions

Or you can go to spacemacs.org and either download the .zip file or press the “Install” button – I recommend the latter, which will give you a url to copy and paste into your command line.

(The note that warns you not to modify “master” is for active users of git – in general this does not apply to new users – who would not think of modifying it anyway – and who I would advise to avoid active use of git unless you are fully confident with it).

You may also want to install the source code pro fonts – do:

git clone --depth 1 --branch release https://github.com/adobe-fonts/source-code-pro.git ~/.fonts/adobe-fonts/source-code-pro
fc-cache -f -v ~/.fonts/adobe-fonts/source-code-pro

As point 4 in the Install guide says: You need to start Emacs from the terminal

$ emacs

for Spacemacs to download all its files.

You will be asked which editing style you prefer. I recommend you type v for Vim and ENTER, then press ENTER to accept the defaults. Then, once Spacemacs has downloaded and installed its packages, restart and you will have the Spacemacs app. You will also be able to run it from the terminal by running emacs (unless you decided to follow the instructions at the link above for trying Spacemacs without modifying your existing Emacs).

In Spacemacs you can use arrow and Page-up and Page-down keys and the mouse, but it is recommended that the next thing to do is have a look through the Spacemacs evil (vi) tutor as suggested in the Quick Start Guide

Get out of the vi tutor with SPC b d   and switch to another buffer with SPC b b

The tutorial in Spacemacs will know which keybindings you have chosen (Vim, emacs, or hybrid) so that it will be useful for your setup.

Although you will want to learn about configuration layers, you might as well get on with using Spacemacs. Evil will make that more comfortable.

If you are on a Mac you may want to use OS X keybindings (implemented as a ‘configuration layer’) – see below and the Layers section of the Spcacemacs Documentation

for implementing this.

Note that such configuration layers need to be added as a line to the text file

~/.spacemacs which is found in your home (~/) folder (folder with same name as your user name).

Normally, files beginning with “.” (dot files) are invisible.

Here is a way to show and hide them easily.

You could open your .spacemacs file (usually called dotspacemacs for clarity) with a text editor like jEdit, but it is more convenient to use Spacemacs itself: do

SPC f e d

Scroll down to (or search for) dotspacemacs-configuration-layers

There you should find a line with “markdown” you can uncomment this, if you like, to give you the markdown layer. You will need to enter “insert” state by pressing the “I” key. Your cursor should change from a block to a bar.

;; markdown

Remove the semicolons (which “comment out” the line) to give

markdown

Then press the Enter/Return key to get a new line and type

osx

You should also uncomment the “org” layer and, while you are editing your dotspacemacs file, go ahead and add the pandoc (so you can use org-pandoc-export and, optionally, pandoc-mode in Spacemacs – see part 2 of this guide for pandoc installation), deft, and bibtex layers (optional):

osx

bibtex

deft




pandoc

Here are my currently active layers (Nov. 2018)

(note: as of Dec. 2018) To allow use of just ‘t’ on heading to cycle between Todo, Done and normal, add the org-want-todo-bindings to your layers list like so

dotspacemacs-configuration-layers  
'(

(org :variables org-want-todo-bindings t)

Press ESC to exit “insert” mode, do SPC f s and SPC b d to save and close the buffer (file) in Spacemacs. Alternatively to load the new configuration without restarting Spacemacs do SPC f e R

If you get a messages window you can close it with SPC w d.

If using another text editor, for example, jEdit, save the file and close jEdit.

You can restart Spacemacs with SPC q r  then restart again SPC q r  to get your new layers installed.

The OSX and other layers should appear under your home folder at ~/spacemacs/.emacs.d/layers/

I run Spacemacs both as an app and sometimes from the terminal: $ emacs If you find that some features are slow in the app or you have problems in Terminal, you can close Spacemacs and run it the other way – It’s the same Spacemacs. The stability of the app is constantly improving.

For the basic Emacs commands as implemented in Spacemacs I recommend using the key bindings discovery feature of Spacemacs. You might also like to print or refer to a copy of my compact cheat sheet: spacemacs_cheat_sheet

An introduction to Spacemacs that is beginner friendly, oriented toward coders is here.

Opening and Creating Files

You can use SPC f f to open or create a text, org, or Markdown file on your computer. You will see a mini-buffer open below the spacemacs buffer where you will begin at your home folder and you can navigate to the desired folder by typing the first few letters and completing with tab

->/users/yourusername/Docu tab

Continue until you reach the directory you want and type the name of the file you want to open or create and press enter/return. If the file does not already exist you will be asked if you want to create it. To do so type Y.

Switch to “Insert state” by pressing the i key and once you have entered text, exit “Insert state” by pressing esc and save the file with SPC f s. You can use the .txt extension (for example: myfile.txt) or, if you want this to be a Markdown file, .md, or org-mode file, .org. Spacemacs recognizes these files when you open them and switches on the Markdown or org layer for you to use.

Another way to find an existing file is to open a NeoTree with SPC p t, arrow down, or navigate with Vim down j and up k, and press enter or the letter l key when the cursor is on the folder or file you want to open. See the full instructions on using NeoTree at Spacemacs documentation.

Support

If you have any problems and don’t find the answer in the usual places try asking on Gitter Chat – click on the link on the Spacemacs app front page or go to

https://gitter.im/syl20bnr/spacemacs

— go to Part 2 —

See my Cheat Sheet page for some useful key bindings

Note that this cheat sheet is slightly out of date as of December 2018. I will update it soon.

More at http://spacemacs.org/doc/DOCUMENTATION.html

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/>.