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

1.2 Change History

  • Version 1.5: added When I've Finished a Novel
  • Version 1.4: added Simple Version Control
  • Version 1.3: added Stylesheet and Productivity Tips~
  • 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, 2015 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 When I've Finished a Novel

Just because the novel is finished, it doesn't mean the file should be disposed of. This is not just sentiment, experience suggests the file is something that I will return to over the coming months. There are a few reasons for this. Here are a few:

  • Blurbs, summaries and press releases will need to be written
  • This is the age of Social Media. Blog and Guest Blog entries will need to be written
  • I may wish to refer to events when writing a sequel
  • There may be another novel or short story to be written in the same setting
  • There will be unused ideas in there that can be used elsewhere.

The following process is intended to tidy up the file, removing the chaff and sorting the useful stuff into some sort of order. It's well worth the time taken.

First, use org-sparse-tree to check for unfinished TODOs. According to my setup this brings up TODOs and IDEAs

C-c / t

Here's a short example from Dream Paris, my latest novel

** TODO P.232 More explanation of (2)You and You(2)?
** TODO Get Mr Monagan mentioned earlier
** TODO Do something about the Tu Vous numbers
** TODO Why is Anna the Hero of Dream Paris?
** TODO Where did Kaolin's intelligence come from?
** TODO Kaolin speaks a leetle like this.  Good 'ealth!

Go through and mark those TODOs which have been done as DONE

Find the PAUSED ideas in a similar way and change them to TODOs (they might be useful in other stories)

C-c / T PAUSED

Now begin the process of sorting. Add three headings at the beginning of the file.

* A General Ideas
* B Blog
* C Sequel

Mark up the remaining TODOs using Shift up and down to give them a priority of A (for General Ideas), B (for Blog) and C (for Sequel) (I don't use org-mode priorities, so this is just a quick way of marking up)

Now that the notes are categorised, copy them to the appropriate heading, ready for refiling. There are a number of ways this can be done. Here are a couple to get you going.

Use org-sparse-tree to identify the individual entries and then org-refile to the appropriate heading:

C-c / / #A	Find all the #A General ideas
C-c C-w		Refile to appropriate heading

or

Make a copy of the buffer and then use M-x keep-lines to flush all lines that do not contain the regexp #A. Copy the remaining lines to the appropriate heading.

I did write an elisp function to do the above, but it was just automation for the sake of it.

At the end of all that, I'm left with a list of notes ready to be transferred to other files. Here's an edited sample:

* A General Ideas
** TODO [#A] Vive L'indifference!
** TODO [#A] Wallace Fountains
** IDEA [#A] Diagonal Anneka
** IDEA [#A] Geppetto (8 or 35)
* B Blog
** TODO [#B] Blog? This is an adult story.  In real life, kids shouldn't be
expected to save their parents.
** TODO [#B] Anna and Francis Orangina
** IDEA [#B] The wine scene
* C Sequel
** TODO [#C] Soldiers with guns saying (12)Mine
** TODO [#C] Dream Paris Courtesans
** TODO [#C] Walking around Dream Paris
** TODO [#C] German Brass Band Instruments

Now it's time to start the next novel…

11 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-&lt;up&gt; and M-&lt;down&gt;

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…

12 Sylesheet

I never knew of the existence of stylesheets until the copyedit came back for my first novel. They struck me as such a good idea that ever since I've tried (and failed) to keep one up to date as I'm writing a novel.

The reason why they fail is that I change my mind as to what style to use as I'm writing. For example, I couldn't decide whether the antagonists in DREAM PARIS were pierrots or Pierrots. In COSMOPOLITAN PREDATORS!, I couldn't decide whether a character was named young man or Young Man.

I came about the solution by using the occur function.

M-x occur pierrot

occur lists lines containing a regexp in a separate buffer. Since Emacs regexps are case insensitive by default, the above finds both pierrot and Pierrot. It opens a buffer rather like the one in the self referential example below:

7 matches in 5 lines for "pierrot" in buffer: workout.org
     16:The reason why they fail is that I change my mind
     as to what style to use as I'm writing.  For
     example, I couldn't decide whether the antagonists
     in my most recently completed novel, DREAM PARIS
     were pierrots or Pierrots.  In COSMOPOLITAN
     PREDATORS!, I couldn't decide whether a character
     was named young man or Young Man.  
     21:M-x occur pierrot 
     24:Emacs regexps are case insensitive by
     default, so the above finds pierrot and Pierrot. It
     opens a buffer rather like the example below: 
     31:M-s h l pierrot 
     34:highlights lines with pierrot in.

Clicking or hitting enter on a line in the Occur buffer jumps you to the original location in the text.

A big advantage of occur is that you can look at the words in situ before deciding on the final style and running a query-replace-regexp to replace them all.

Another useful mode in when looking at styles is hi-lock mode.

M-s h l pierrot

The above highlights lines containing the regexp pierrot.

A really useful feature of hi-lock mode is that it highlights on the fly, highlighting lines as you type in the words. I use this feature to act as a reminder of whether I'm typing in the right (or wrong) style.

As a bonus, hi-lock mode allows you to choose from a pallete of colours. Use M-n and M-p to scroll through the choices, or enter your own choice - very useful when tracking more than one style.

13 Simple Version Control

About once every six months or so I spend the morning happily overwriting an existing piece of work. Either that or I unwittingly delete whole sections, only to discover my mistake later that day or worse, later that week or even month.

That's were Emacs version control comes in handy. Add the following to your .emacs file (courtesy of the EmacsWiki)

(setq version-control t ;; Use version numbers for backups
       kept-new-versions 16 ;; Number of newest versions to keep
       kept-old-versions 2 ;; Number of oldest versions to keep
       delete-old-versions t ;; Ask to delete excess backup versions?
       backup-by-copying-when-linked t) ;; Copy linked files, don't rename.
 (defun force-backup-of-buffer ()
   (let ((buffer-backed-up nil))
     (backup-buffer)))
 (add-hook 'before-save-hook  'force-backup-of-buffer)

You can probably deduce from the comments in the code what it does, but as an illustration, here's a sample of what the file I'm currently writing looks like under version control:

-rw-rw-r--  1 XXXX XXXX 29816 Aug 11  2014 EmacsWritingTips.org.~24~
.rw-rw-r--  1 XXXX XXXX 29816 Aug 11  2014 EmacsWritingTips.org.~25~
-rw-rw-r--  1 XXXX XXXX 28844 Aug 11  2014 EmacsWritingTips.org.~26~
-rw-rw-r--  1 XXXX XXXX 29322 Aug 11  2014 EmacsWritingTips.org.~27~

The last 16 versions of the file are kept, the versions indicated by ~ ver ~

Having all of those versions can sometimes make it difficult to find files under dired. Fortunately, dired-x has a mode that omits uninteresting files. Add the following to .emacs

(require 'dired-x)
(setq dired-omit-mode t)

Now just hit C-x M-o (or M-o on older versions of Emacs) to omit those files.

16 past versions combined with my regular backup routine have proven enough for me to find the accidentally deleted text. For a more in depth discussion see http://www.emacswiki.org/emacs/ForceBackups

14 Productivity Tips

The following are various posts from The Emacs Workout that are specific to writers

14.1 Transposition

Sacha Chua writes here about developing microhabits. It's an article close to my heart, in fact, it's the reason that I write the Emacs workout. Sacha's article was inspired in turn by this tweet from Frederik Appelburg

Using transpose-chars is a litmus test. If you care enough to save keystrokes to internalize C-t, then you must be a power user.

I agree with Frederik: I use C-t all the time for that very reason (in fact I've written elsewhere that my litmus test is do you use M-c to capitalise words?).

But Frederik got me thinking about M-t. How often do I have to transpose a word?

Transpose two lines, yes, transpose a sentence. Well, when I'm editing stories, I do this a lot. But I rarely find myself transposing words.

Emacs has five built in transpose commands:

C-t		transpose-chars		Transpose the two letters.
M-t		transpose-words		Switch two words.
C-x C-t		transpose-lines		Switch two lines.
		transpose-sentences	Switch two sentences.
		transpose-paragraphs	Switch two paragraphs.

The trouble is, there is no key binding for the last two, the ones I'm most likely to use. Well, Emacs was made to be customised, it says so in the name. I could have added a couple of extra key bindings, but for various reasons I chose to use aliases, and so I added the following code to my .emacs file.

1: (defalias 'ts 'transpose-sentences)
2: (defalias 'tp 'transpose-paragraphs)

Now I just move the cursor between two sentences or paragraph, hit M-x ts or M-x tp and that's it.

It's such a simple customisation, and one I should have done years ago. But there you go: you have to work hard to be lazy.

15 Various Lisp Functions

15.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 "[“”]" nil t) (replace-match "\"" nil t))
 8:   (goto-char (point-min))
 9:   (while (re-search-forward "[‘’]" 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… "

Author: Tony Ballantyne

Created: 2016-02-16 Tue 15:16

Emacs 24.5.1 (Org mode 8.2.10)

Validate