<<top>>
Hi! This is a guide to help you pick up the basics of reading
customization code for Emacs - little snippets of Emacs Lisp that you
can add to your ~/.emacs.d/init.el to change how Emacs works. I hope
this will help you learn how to borrow interesting snippets from
README files and other people’s configs so that you can tweak Emacs to
fit the way you work. This is not a detailed guide on how to
understand Emacs internals, but by the time you find yourself digging
through comint.el to figure out what’s going on with command
interpretation, you probably already know your way around.
We’ll assume that you already have Emacs installed and that you’ve
gone through the built-in tutorial (Help - Emacs Tutorial, <f1> t,
C-h t, or M-x help-with-tutorial). If you haven’t upgraded to at
least Emacs 24.x, please do - it’s worth it! I’ll also assume you have
a little programming background or can deal with the concepts of
variables and functions. Feel free to ask questions if you get stuck
on something or if you want to clarify your understanding.
Please e-mail questions, comments, and suggestions to [email protected]. I want to make this guide better, and I’d love to hear from you. If you would like to help improve this guide, you can find it on Github - pull requests welcome. This guide is dual-licensed under the Creative Commons Attribution License and the GNU Free Documentation License, so feel free to read, share, and build on it.
You can find this guide on the Web at http://emacslife.com/how-to-read-emacs-lisp.html . If you want an EPUB version or a downloadable HTML version, you can get it from Gumroad (free/pay-what-you-want).
Now, on with the guide.
To make the most of Emacs, learn how to read and write Emacs Lisp. Most of Emacs is written in Emacs Lisp: the packages that add extra functionality, the configuration code to set different options. You can change large parts of how Emacs behaves even without restarting Emacs.
Remember: with great power comes lots of time debugging if you mess things up. This is a guide to help you avoid messing up, so you can build the confidence to learn more. It’s worth it. Start with one-line in ten years (or three, or twenty, or next month - all up to you), you’ll be able to tweak Emacs to do more things than other people might imagine a text editor can do.
This is what Emacs Lisp code looks like:
(message "Hello world!")Or something slightly more useful:
(setq delete-old-versions -1)If you want to start playing around with Emacs Lisp code right away, jump ahead to the section on “How can I try Emacs Lisp code?”.
“Why do I have to learn Emacs Lisp in order to get Emacs to do what I want? Shouldn’t Emacs just come with reasonable defaults?”
Reasonable defaults make sense for specific people. Other people might have completely different ideas for how they want a tool to work. Many people use Emacs and have (occasionally quite strong) opinions about how they want it to work. It’s difficult to change the defaults for everyone[fn:: https://xkcd.com/1172/], and since Emacs is so customizable, people tend to just fix things for themselves. If you learn how to read and write Emacs Lisp, you can pick up tips from other people’s configurations and ask people for help.
There are some initiatives to put together common settings or “starter kits” that people may like. You can check them out for inspiration or use them as a starting point. Here are a few popular ones:
You can read them to pick up ideas for customizing Emacs, or you can use them as a starting point for your own configuration. Note that starter kits change the behaviour of Emacs from what you might expect based on manuals and webpages. If you’ve added configuration code that you don’t understand, be sure to mention it when asking for help, since people might otherwise assume you’re starting with the defaults. It may be a good idea to look at starter kits and other people’s configuration for inspiration, but add snippets slowly instead of copying things wholesale.
I find that optimizing my Emacs configuration for my happiness is
worth the mild annoyance of not having my shortcuts handy (or worse,
not having Emacs!) when I pair-program with other people. If you’re
pair-programming with other people, you can switch your configuration
or use a different editor. emacs -q starts Emacs without your
personal configuration. It’s good to be familiar with other editors
like Vi so that you can be productive even if that’s all you have, and
then learn how to make the most of Emacs so that you can reap the
benefits over the decades.
Many people synchronize their configuration across multiple computers by using version control systems like Git or file synchronization tools like Dropbox. You can set up Emacs to check for hostname or other system variables before loading system-specific configuration.
You might think it’s not worth customizing Emacs if you spend most of your time ssh-ed into other servers. With Emacs, you can use TRAMP to edit files through SSH and sudo in your local Emacs.
Emacs Lisp code can help you save time by automating repetitive actions, smoothening rough edges, or enabling time-saving features like autocompletion. Investing some time can help you save a lot of time later. Learning from other Emacs users can help you figure out customizations that take little time for big results.
That said, it’s a good idea to take a step back and figure out if what you’re trying to customize is really worth it. One of the occupational hazards of using Emacs is that tweaking your Emacs configuration can be fun, almost addictive. If you catch yourself spending four hours fiddling with something minor, it might be time to put that aside and focus on getting stuff done first.[fn:: Is it worth the time - http://xkcd.com/1205/]
<<try>>
<<understanding-lisp>>
I’ve posted the source for this document on Github (http://github.com/sachac/emacs-notes). This guide is dual-licensed under the Creative Commons Attribution License and the GNU Free Documentation License, so feel free to read, share, and build on it. Patches and pull requests welcome!
Thanks to aidalgol, rryoumaa, shergill, taus, tali713, Fuco, @philandstuff, forcer, DaveP (detailed feedback, thanks!), Adrian Lewis, Andrzej P., Artur Malabarba, Daniel Wu, Iaroslav Tymchenko, and Sebastian Hörberg for feedback!
- Sacha Chua