Configure Emacs Writing Studio

A vanilla version of Emacs has a lot of functionality out of the box and you could easily write a book without any configuration. But to truly leverage its capabilities, Emacs needs external packages and additional configuration.

Some Emacs users use pre-configured systems, such as Doom Emacs, or Spacemacs, or one of the other starter kits. While these configurations are helpful, they sometimes provide ‘everything but the kitchen sink’.

On the other side of the spectrum, you can configure your system from scratch, which can become a productivity sink as you wade your way through highly technical instructions written by experts.

Emacs Writing Studio (EWS) seeks the golden mean by providing a minimal configuration. The main objective of EWS is to get you started writing in Emacs and generate sufficient curiosity for you to further develop your skills and keep improving your configuration.

When you start Emacs, it loads the initialisation file, or init file in short. This file contains Lisp code that configures Emacs and loads additional packages.

The first time you start Emacs, it will create the configuration directory. The init file lives in this location, which will also contain the packages and other files needed to personalise your system.

Emacs looks for a file called .emacs, .emacs.el or init.el. The dot in front of the file means that it is hidden from view to prevent cluttering your directories. The location of the configuration folder depends on your operating system and Emacs version. The Emacs help functionality can tell you where to store the init.el file.

Type C-h v (describe-variable), and type user-emacs-directory and Enter (or user-e TAB) in the minibuffer at the bottom of the screen. The help buffer that now appears provides the correct folder name, for example "Its value is "~/.config/emacs/".

You can now visit (open or create) the init.el file in your Emacs directory and copy and write your configuration. Your init file will become active after you restart Emacs (use M-x restart-emacs).

You can download the complete EWS configuration file from GitHub and save it in the user directory. Copy the init.el and ews.el files to your user directory. The first file contains the Emacs configuration and the second file contains bespoke EWS functions.

emacs-writing-studio

Please note that when you start Emacs with the Emacs Writing Studio configuration for the first time, Emacs will download several packages from their online repositories and compile them. This process might generate scary-looking text, but you can ignore it, as it only appears when you install new packages.

While using commercial software is like renting a fully furnished house, using Emacs is more like buying a new empty house. Your new digital home needs some paint and new carpets, which means you need to configure Emacs to make it your digital home.

Commercial software provides graphical menus to define how the software operates. Like the examples below, you might tick a box, select an item in a list, or enter a value in a text box to configure the program to your wishes.

Being a plain text program, Emacs doesn't use a graphical interface but a programming language called Lisp. The code below is equivalent to the graphical user interface shown above.

  (setq-default inhibit-startup-message t
                initial-scratch-message "Hello world"
                cursor-type 'bar)

Although the text-based method is superficially more complex than ticking boxes, writing text and selecting a drop-down list, it is far more potent than a graphical interface. Writing code to configure your computer may not seem user-friendly initially because we are used to the graphical interface. However, once you learn how to write simple Emacs Lisp programs, you will find that Emacs is the most user-friendly system because it gives you so much power over your computer. But with that power comes great responsibility and a steep learning curve.

Using Emacs Lisp is the epitome of ease of use. You control how your computer behaves instead of the computer controlling your behaviour.

A Lisp program consists of expressions, which are statements enclosed in parentheses. Each expression starts with the name of a function (setq-default), followed by some parameters.

The setq-default function is commonly used to set the default value of a parameter. For example, (setq-default inhibit-startup-message t) has the same effect as putting a checkmark in the inhibit-startup-message box, while inhibit-startup-message nil is the same as removing the checkmark in that box. The expression in this example determines whether Emacs displays a startup message when you open it for the first time.

You don’t have to learn to program Lisp to configure Emacs. The examples on this site provide sensible defaults to turn vanilla Emacs into your personal writing studio. Each article offers a thoroughly documented configuration. Many Emacs users share their configuration with the community so that you can copy their code. The copy-and-paste method is a shortcut to learning more about Emacs Lisp because you can change the settings and examine the results of your changes.

Besides crafting your own configuration or using a starter kit, Emacs has a customisation menu that lets you configure Emacs without writing code. This system writes the required Emacs Lisp code to the init file.

Emacs Wring Studio uses two separate init files to prevent Emacs from changing your hand-crafted config. The configuration below changes the automated configuration file’s name to custom.el and evaluates it when it exists.

  (setq-default custom-file
                (expand-file-name "custom.el" user-emacs-directory))
  (when (file-exists-p custom-file)
    (load custom-file))

The first lines of code instruct Emacs to use a separate file for the internal configuration system (custom.el). The expand-file-name expression adds the filename to the location of the Emacs user directory. This method ensures the code works irrespective of the Emacs user directory location.

The last two lines load this file when it exists (file-exists-p). As this is the first action in the configuration, your personal init file will override any settings in the custom file.

Emacs Writing Studio variables

For convenience, the Emacs Writing Studio defines some variables to configure the system.

You can change these, and any other variable in Emacs, variables with the customize-variable function, search for ews, and pick the variable you seek to change. Alternatively, use customize-group and search for ews to see all variables. You can then change the entry in the text field to your preference and hit the Apply and save button. Emacs saves the new value(s) to the custom.el file and they will be loaded next time you start Emacs.

The Emacs customisation functionality is a low-code option to configure your system and the Emacs Writing Studio is configured so that the variables set with this method will override the default configuration presented in these pages. Alternatively you can of course hack your init file directly.

Emacs Writing Studio also includes a handful of bespoke convenience functions, which are discussed in their relevant pages. All bespoke configuration is stored in the ews.el file on GitHub.

Configuring Emacs can be a daunting task and become a productivity sink because of the ease by which it can be done. Within the Emacs community, a discussion emerges every now and then about the need to make so many changes to the vanilla software to get it to behave how you like it.

A commonly asked question is why can't Emacs have 'sensible default' values? This may seem like a reasonable question, but what is sensible to one user is an annoyance for another. Emacs developers are as such quite conservative when it comes to changing the default settings.

The Emacs developers cannot cater to every personal preference, so they provide a skeleton system you must enhance to suit your workflow. Emacs Lisp is like a box of Lego. You can play with it out of the box using vanilla Emacs, but it is much more fun when you create your own toys. Working on your Emacs configuration is like building with Lego and eventually you configure Emacs to perfectly meet your needs.

It can be tempting to constantly fine-tune your configuration. Wielding the power to create a bespoke Emacs system is a temptation that can lead to fake productivity, which is one of the three forms of procrastination:

1. Nihilistic procrastination: Watching TV or playing computer games.
2. Sophisticated procrastination: Fake productivity, e.g. Emacs hacking, switching productivity tools, taking notes for volume instead of quality.
3. Productive procrastination: Daydreaming.

Tinkering with your Emacs configuration is not as bad as nihilistic procrastination but can become a form of fake productivity. The productivity gains from fine-tuning your Emacs to cut out a few keystrokes can take more time than you will save with your new workflow. Writing is more than the number of words you can type into your buffer. Writing is as much a contemplative act as it is about productivity. Don’t get sucked into trying as many packages as possible. It will lead to what Emacs aficionados call Dot Emacs bankruptcy, which occurs when your init file is so enormous and disorganised that it becomes unmanageable.

The best way to learn how to configure your Emacs system is to search the web for examples and copy them to your init file. Initially, the code might look gibberish, but its logic will become more apparent as you do this more often. Emacs has an extensive help system that you can use to explore functions or variables you like to know more about. Use C-h o (describe-symbol) to search for any function or variable.

Hopefully, the Emacs Writing Studio configuration will help you reduce the time it takes to configure Emacs to suit your preferred workflow.

If you like to support my work, then please purchase the Emacs Writing Studio book.

Emacs is a malleable system, and everybody has personal preferences on how to undertake a task and configure Emacs. Any article on how to use Emacs is thus opinionated. If you have a different way of doing things, please complete the contact form to send me an email or contact me on social media.

The next article explains the principles of writing prose in Emacs.