My Emacs Writing Setup
My Emacs Writing Setup
Table of Contents
1 About this Document
This document was written due to the interest generated by a post on my blog entitled Writing Tools.
The document is not an Emacs Tutorial, nor is it an exhortation to learn Emacs, but rather a description of how I use Emacs org-mode to help me write fiction (see TonyBallantyne.com for more). My tech blog, Tony Ballantyne Tech, contains more Emacs materials including tips and tricks (The Emacs Workout) and a brief ELisp tutorial (Just Enough Emacs Lisp)
Many of the ideas on the use of org-mode were taken from Bernt Hansen's excellent document Org Mode Organize Your Life in Plain Text!, as was the format of this document itself. Some of the Emacs tricks came from the Emacs Wiki and Xah Lee's Emacs tutorial.
1.1 Related Materials
- TonyBallantyne.com: My blog
- Emacs Tutorial: Emacs Tutorial for Writers
- Tips on How to Write: More tips for writers
1.2 Change History
Version 1.2: added Emacs and Scrivener This is version 1.1 of this document: added Finding My Place and Various Lisp Functions
2 License
Copyright (C) 2014 Tony Ballantyne. 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 code is 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.
3 Why Emacs?
I think of Emacs as a text editors' tool. As I spend most of my life working with text, either programming or writing, I want to do it as efficiently as possible.
It first struck me when I was editing my novel Divergence just how inefficient I was being in pressing the arrow key and waiting for the cursor to get to where I wanted. That got me thinking about the time spent deleting text, transposing words, moving around paragraphs… I realised there must be a quicker way.
And then I remembered Emacs.
It makes sense for someone who spends most of their time manipulating text to learn a group of obscure key combinations. It saves time and increases productivity. Learning to use Emacs properly reminds me of playing Jazz on the piano. I've learnt all those chords and runs and fills so that I can use them without thinking when I'm improvising. Likewise, I've practised using Emacs key strokes such as M-f, M–M-c and C-M-<Space> so often I use them without thinking when editing. I rely on M-/ to complete words, and I can't do without M-h and C-e to select and move around text.
I practice using Emacs because it makes me a more productive writer. If you're interested, I've written up some of those tips and exercises on my Emacs Workout.
4 Setup
Instructions on how to set up Emacs and Org-mode appear on the Emacs Setup Section of my website Tony Ballantyne Tech
5 Structuring a Story
I begin a story by creating an org mode file with something like the following structure:
* Refile
* Things Todo
* Plot
* Story
* Characters
* Places
* Scenes
* Quotations
* Styles
* Ideas
- Refile is for things I just need to write down fast, it's a list of things that need to be refiled later.
- Things Todo is just that, a list of things I must remember to do in the story
- Plot contains the shape of the story, as it is at the time. This gets rewritten as I go on. It also acts as a reminder of what I've done so far
- Story is just that, the story itself
- Characters, Places, Scenes, Quotations are notes on those things that are to be included in the story
- Styles is there to remind me just how I wrote things out e.g. Daddy Bear, not Daddy bear.
- Ideas are ideas that may or may not be included in the story.
Here's an example of what a typical structure might look like. Different types of stories have different sections. My Penrose novels (The Penrose Series), for example, have sections dealing with Robot physiology.
* Refile
* Things Todo
** Resolve what happens to Mummy Bear
* Plot
** Episode 1
Bears make porridge, go into woods
** Episode 2
Goldilocks arrives, eats the porridge, falls asleep
** Episode 3
Bears return. Find Goldilocks, threaten to eat her
** Episode 4
Big Bad Wolf saves the day
* Story
** Episode 1
Once upon a time there were three bears. Mummy Bear, Daddy Bear, Baby Bear etc...
* Characters
** Daddy Bear (38)
Brown fur, brown eyes.
Biggest bear. Gruff.
** Mummy Bear (39)
Black fur, golden eyes.
Clever, sarcastic
* Places
** Wood
** Cabin
Built of wood. Three rooms. Enter directly into main room, no hallway.
* Scenes
* Quotations
** Who's been eating my porridge?
** Then I'll huff and I'll puff and I'll blow your greenhouse down
* Ideas
** Bears have an invisible motorbike
** Daddy Bear once served time in prison for bearslaughter
Some things to note:
- I always write down the age of my characters: it helps to fix them in my mind
- I get ideas for quotations and scenes from all over. I now record them using the Evernote App on my phone and copy them into the appropriate file when I have time.
- I try to keep the plot section up to date as I write the book. It helps to remind me of any changes I've made.
6 Adding Todos
As well as writing, I use Emacs for GTD. (Actually, I use Emacs for just about everything, but that's a whole series of other posts…)
Over the years, I've narrowed down my todo keywords to the following
(setq org-todo-keywords
(quote ((sequence "TODO(t!)" "NEXT(n!)" "|" "DONE(d!)")
(sequence "REPEAT(r)" "WAIT(w!)" "|" "PAUSED(p@/!)" "CANCELLED(c@/!)" )
(sequence "IDEA(i!)" "MAYBE(y!)" "STAGED(s!)" "WORKING(k!)" "|" "USED(u!/@)")
)))
The last block of TODOs are the ones concerned with writing.
- IDEA Just that, an brief idea that I may or may not use
- MAYBE A completed scene or chapter that I'm not sure whether to include
- STAGED A completed section that is waiting to be put in place (I use the STAGED keyword for items ready to be emailed or put on my blog, for example)
- WORKING Things I am currently working on - Characters I'm developing, scenes I'm writing, places I'm realising. I try not to have more than three or four of these at a time. The WORKING tag makes it easy to see things I've forgotten about.
- USED A formerly STAGED section that has now been used.
Here's how my structure might look at a given moment:
* Refile
* Things Todo
** TODO Resolve what happens to Mummy Bear
** TODO Goldilocks discovered sleeping in Baby Bear's bed
* Plot
** Episode 1
Bears make porridge, go into woods
** Episode 2
Goldilocks arrives, eats the porridge, falls asleep
** Episode 3
Bears return. Find Goldilocks, threaten to eat her
** Episode 4
Big Bad Wolf saves the day
* Story
** STAGED Episode 1
Once upon a time there were three bears. Mummy Bear, Daddy Bear, Baby Bear etc...
** WORKING Episode 2
** TODO Episode 3
* Characters
** Daddy Bear (38)
Brown fur, brown eyes.
Biggest bear. Gruff.
** Mummy Bear (39)
Black fur, golden eyes.
Clever, sarcastic
* Places
** TODO Wood
Needs more realisation
** Cabin
Built of wood. Three rooms. Enter directly into main room, no hallway.
* Scenes
* Quotations
** USED Who's been eating my porridge?
** MAYBE Then I'll huff and I'll puff and I'll blow your greenhouse down
* Ideas
** IDEA Bears have an invisible motorbike
** IDEA Daddy Bear once served time in prison for bearslaughter
** USED Baby Bear's porridge is just right
I use these keywords to track what needs doing on a story. Every so often I use C-c / t to find all the outstanding Todos.
7 Finding my Place
It can be a nuisance finding where things are even when writing a short story. When writing a novel, it's easy to get lost amongst the story, the notes, the character sketches…
Fortunately, Emacs and Org-Mode have a number of features to help you find your way around.
The most basic and most useful method, of course, is Emacs search. I've written more about this here.
Similar to search are
M-x occur, and C-c / r org-occur
These highlight all occurrences of the search string. This can be handy, for example, when searching to see which chapters a character appears in.
Quite often I find myself jumping up and down a file, adding text here and there. You can use the standard mark-ring commands:
C-<SPC> C-<SPC> Set the mark to the mark ring C-u C-<SPC> Move point to where the mark was
… but org-mode has two commands that respectively push your current position to the mark-ring and jump to the last position on the mark ring. For convenience, I've bound them to the f7 key as follows.
(global-set-key (kbd "<f7>") 'org-mark-ring-push) (global-set-key (kbd "C-<f7>") 'org-mark-ring-goto)
Now, I simply hit f7 to remember my position before heading off to edit elsewhere in the file, then hit C-f7 to return to where I started.
7.1 Bookmarks
I'm assuming you already know how to use bookmarks, but if you don't, here's a link to the Emacs Wiki for a crash course.
As I write on multiple machines, I keep my bookmarks file on Dropbox so that I have a consistent set of bookmarks wherever I happen to be working. I've added the following command to my .emacs file to let Emacs know where my bookmarks are.
(setq bookmark-default-file "~/Dropbox/common/emacs/bookmarks.bmk" bookmark-save-flag 1)
I've got into the habit of having a bookmark named here. I try to set this mark when I finish working. When I start work, I simply jump to here.
8 Markup
I markup my text for export as I write. I don't use many codes as I prefer to get the story down than to get it formatted. The excellent org-mode manual contains a full and easy to follow explanation of org-mode markup.
Here are a few things to be aware of
- Leave a line break between paragraphs.
- Use * bold * or preferably / italic / only for emphasis
- Don't use smart quotes. Leave it to the exporter to handle these. I've written an elisp function to remove them.
And that's it.
9 Export
When a story is completed, I export it as an odt document using C-C C-e o O.
I've set up an ott template so the document is suitably formatted (double spaced, appropriate headers and footers, page numbers)
C-c C-e # inserts the default export template, as follows:
#+ODT_STYLES_FILE: "/home/******/Templates/EmacsStory.ott"
#+TITLE: Writing with Emacs
#+DATE: <2013-05-05 Sun>
#+AUTHOR: Tony Ballantyne
#+OPTIONS: ':nil *:t -:t ::t <:t H:3 \n:nil ^:t arch:headline
#+OPTIONS: author:t c:nil creator:comment d:(not LOGBOOK) date:t e:t
#+OPTIONS: email:nil f:t inline:t num:t p:nil pri:nil stat:t tags:t
#+OPTIONS: tasks:t tex:t timestamp:t toc:t todo:t |:t
#+CREATOR: Emacs 23.3.1 (Org mode 8.0.2)
#+DESCRIPTION:
#+EXCLUDE_TAGS: noexport
#+KEYWORDS:
#+LANGUAGE: en
#+SELECT_TAGS: export
The various options control such things as whether to use smart quotes or to include the author's name in the title. The manual list all the options
Once I've exported a story to odt format I save it in .doc format and then use this document for the remainder of the editing process. This is mainly due to the fact that the readers who initially critique my work write their suggestions on the document either using a pen or the change tracking function.
10 Emacs and Scrivener
I heard a lot of people talking about Scrivener so I downloaded a trial copy (on Windows, there's no Linux version, sadly…) and gave it a try.
It seems like a suitable tool for writers to use, it comes with a nice tutorial, and I'd recommend that anyone give the free 30 day trial a go, (this despite the fact the company behind it are called Literature and Latte).
I still prefer Emacs, though. Most of the features that Scrivener offers are easily replicable in Emacs. If you've been following my Emacs Writing Tips you'll have been doing something similar anyway.
One thing I did like about Scrivener, though, was the corkboard, a place where you could pin synopsis cards and move them around whilst you're putting your ideas in order. This is a really good idea, and one thing that Emacs can't replicate so well. Here's a work around,
The idea is quite straightforward
1. Write your synopsis in headings 2. Move them up and down using M-<up> and M-<down>
It's not as nice as the corkboard, but if you want a graphical interface, you're using the wrong program.
It's also worth mentioning org-tree-to-indirect-buffer, here. This allows you to replicate the document map in Microsoft word. It's easiest to try this out for yourself
1. Open an org file in Emacs 2. Navigate to the subtree you want to edit 3. C-x 3 to split the window vertically (org-tree-to-indirect-buffer defaults to a vertical split) 4. C-c C-x b to open the narrowed subtree in the other frame
It all sounds rather complicated, but it's really quite straightforward, and very useful…
11 Various Lisp Functions
11.1 Find and Replace in a Region: Strip Smart Quotes in a Region
These are smart quotes: “ ” ‘ ’
The easiest way to get Emacs to automatically insert smart-quotes is to use smart-quotes mode.
I prefer not to use smart-quotes mode, however. I find it easier when editing to stick to plain quotes (" and ') and then to let org-mode export convert to smart quotes.
What makes things awkward is finding text with smart-quotes already included. I wrote the following function to strip those smart-quotes out. It narrows to a region, uses save-restriction to remember how things were before the narrowing and then uses two regex searches to find first double quotes and then single quotes, replacing both with plain quotes.
1: (defun strip-smart-quotes (rStart rEnd)
2: "Replace smart quotes with plain quotes in text"
3: (interactive "r")
4: (save-restriction
5: (narrow-to-region rStart rEnd)
6: (goto-char (point-min))
7: (while (re-search-forward "[\342\200\234\342\200\235]" nil t) (replace-match "\"" nil t))
8: (goto-char (point-min))
9: (while (re-search-forward "[\342\200\230\342\200\231]" nil t) (replace-match "'" nil t))
10: ))
Before: “You put your smart-quotes in, you take your smart-quotes out… ”
After: "You put your smart-quotes in, you take your smart-quotes out… "
