Introduction

The goal of this book is really very simple: to teach you, dear reader, how to program Emacs, or rather, to help you teach it to yourself. Emacs – and Emacs Lisp – have grown to be quite complex, but that doesn’t mean you need a Ph.D. to code in Elisp. In this book, we will start small, though not very small – I assume that you’ve read the late Robert J. Chassell’s excellent An introduction to programming in Emacs Lisp. It’s well-written, informative, pretty light and free, so why not? I will repeat a thing from that book here and there, but mostly I will build upon what you already know from it.

Of course, the first question we might want to ask is: why would you want to program Emacs? If you are an Emacs user, you most probably know the answer – to make your editing experience better. Maybe there is some behavior of Emacs which annoys you and you’d like to change it. Maybe you have some repetitive action you want to automate. Maybe you use some application which can be used via a CLI or a Web API and you want to drive it from Emacs. There can be probably a ton of other reasons.

If you are not (yet) an Emacs user, this book is probably not for you. If you heard that Emacs is a fantastic, programmable text editor and you could benefit from using it and coding in Emacs Lisp, you should probably start with learning how to use Emacs. The first resource you might want to check out is the built-in Emacs tutorial, and you could proceed to the (very fine!) Emacs manual or the Mastering Emacs blog and book by Mickey Petersen. Then, at some point in time you can read An introduction to programming in Emacs Lisp, and come back to this book afterwards.

Ok, so you’re still here. Great! Let me explain a bit about what I wanted to achieve with this book.

I spent considerable time thinking what to include here and what to leave out, and in what order to present things. And really, there is no universal way of doing it. It was clear to me from the beginning that I should start easy and then move on to more sophisticated topics, but that opened more questions than it answered. After a lot of internal discussions with myself and a few drafts, I decided on a few guiding principles for myself to follow.

First of all, I try not to pull rabbits out of my hat – instead of telling the reader “well, this and that is a function which solves the issue at hand, what, you didn’t know about it? how stupid!”, I tried to assume that you haven’t read the whole source code of Emacs, or even the whole 1300+ pages of the GNU Emacs Lisp Reference Manual (called the “Elisp reference” from now on). (If you have, why would you need this book anyway?) So, at least in the beginning, whenever I introduce some useful function, I try to show how you, yourself, could find out about it. (Later on you’ll already know most of the tricks to find functions doing what you want.) It is not always easy, but Emacs really is self-documenting and many things are more or less easily discoverable. (Although why some functions were named the way they were is still a mystery to me.)

The next thing is that I tried to show real-life examples (as much as possible). Of course, many, many possible enhancements to basic text editing are either present in core Emacs or as packages, so sometimes the code here may replicate what is already available – but nevertheless, I tried to choose ideas that are really useful, and for as wide as audience as possible. This means that the examples are not tied to any specific programming language. Also, I did not touch Org-mode, which is great – and programmable – but not every Emacs user is also an Org-mode user.

Last but not least, I tried to cover as many useful things as possible (even if sometimes superficially), so that you will learn about some common techniques useful in many different situations, like leveraging built-in editing features, using region in your custom commands, writing a minor mode and many others. Sometimes I only mention some feature, variable or function, and if you find it interesting or useful, you can always go to the Elisp reference, the relevant docstrings or even the source code.

The book is intended to be read in order. This means that even if you are interested in e.g. writing a minor mode, you should probably at least skim through the first chapter before diving in to the second one. After all, this is a textbook, not a reference, and so in later chapters I sometimes use ideas explained earlier without much commentary.

Here is a short breakdown of the chapters. In the first one, we build a function to move the current line up or down, which is quite useful when programming – but also when e.g. typing short itemized lists. The second chapter is devoted to a utility helping with editing texts – a tool to rearrange words in a sentence. It is the longest one in the book, since the tool is going to be quite complicated, and we will use many Emacs features. In the third one, we count lines of code (in a way that can be used for Elisp or other programming languages).

This is a good place to thank a few people who made this book possible. It is obvious that it could never exist without Richard Stallman who wrote the first version of Emacs and numerous people who contributed to it over the decades. It is written in Org-mode, first made by Carsten Dominik and then developed by many other people. Diego Zamboni wrote the Org exporter to convert Org-mode syntax to Markua, expected by Leanpub. Christian Tietze provided a nice idea now incorporated in the sentence-reordering code. Last but not least, my wife and children put up with me writing instead of spending more time with them.

If you like my writing and want to learn more about Emacs and Emacs Lisp, you might consider reading some Emacs blogs. A good portion of my personal blog is also devoted to Emacs.

Just in case, please remember that when I link to some website, mention some person or quote some piece of art, it does not mean that I fully endorse any of those things or share the values of the person mentioned – it means that I consider that information relevant, interesting or maybe just funny in the context.

Important note: this book is still subject to change. What you are reading is version 1, but I hope to add at least two more chapters some day in the future, creating version 2. (When? I don’t know yet. A Wednesday, perhaps. Maybe next Wednesday, or just one of the Wednesdays. Seriously though, some time in mid-2022 is the most probable time.) Nevertheless, I consider it “complete” in the sense that it is a certain whole, and even if I don’t manage to add anything, it can stand on its own as it is now, and the chapters that do exist should not change too much.

Also, you may want to know that I consider releasing this book on some pretty permissive license in the future (most likely one of the Creative Commons ones), but not earlier than perhaps 2023. If you prefer not to pay for it, it might be enough to wait a few years. On the other hand, I owe it to my family that the time I spend without them is compensated, e.g. in the form of money needed to sustain our well-being – so I am only willing to release the book for free if and when I attain a reasonable hourly rate (that is, if/when the income it generates divided by the amount of time I spent on it reaches some minimum). This means that paying me now is a step towards making it more probable that the book will be available for free in the future.

So, let’s get into business of programming Emacs!