Contents

Contents

Introduction Thank You . . . . . . . . . . . . . . . . . . . . Intended Audience . . . . . . . . . . . . . . . . What Youll Learn . . . . . . . . . . . . . . . .

TheWay of Emacs Guiding Philosophy . . . . . . . . . . . . . . . .

LISP? . . . . . . . . . . . . . . . . . . . . . Extensibility . . . . . . . . . . . . . . . . .

Important Conventions . . . . . . . . . . . . . . The Buer . . . . . . . . . . . . . . . . . . The Window and the Frame . . . . . . . . The Point and Mark . . . . . . . . . . . . . Killing, Yanking and CUA . . . . . . . . . .emacs.d, init.el, and .emacs . . . . . . . . . Major Modes and Minor Modes . . . . . .

First Steps Installing and Starting Emacs . . . . . . . . . . .

Starting Emacs . . . . . . . . . . . . . . . .

The Emacs Interface . . . . . . . . . . . . . . . Keys . . . . . . . . . . . . . . . . . . . . . . . .

Caps Lock as Control . . . . . . . . . . . . M-x: Execute Extended Command . . . . . Universal Arguments . . . . . . . . . . . . Discovering and Remembering Keys . . . .

Conguring Emacs . . . . . . . . . . . . . . . . The Customize Interface . . . . . . . . . . Evaluating Elisp Code . . . . . . . . . . . . The Package Manager . . . . . . . . . . . . Color Themes . . . . . . . . . . . . . . . .

Getting Help . . . . . . . . . . . . . . . . . . . The Info Manual . . . . . . . . . . . . . . Apropos . . . . . . . . . . . . . . . . . . . The Describe System . . . . . . . . . . . .

The Theory of Movement The Basics . . . . . . . . . . . . . . . . . . . . .

C-x C-f: Find le . . . . . . . . . . . . . . . C-x C-s: Save Buer . . . . . . . . . . . . . C-x C-c: Exits Emacs . . . . . . . . . . . . . C-x b: Switch Buer . . . . . . . . . . . . . C-x k: Kill Buer . . . . . . . . . . . . . . ESC ESC ESC: Keyboard Escape . . . . . . . . C-/: Undo . . . . . . . . . . . . . . . . . .

Window Management . . . . . . . . . . . . . . Working with Other Windows . . . . . . .

Frame Management . . . . . . . . . . . . . . . . Elemental Movement . . . . . . . . . . . . . . .

Navigation Keys . . . . . . . . . . . . . . . Moving by Character . . . . . . . . . . . .

Moving by Line . . . . . . . . . . . . . . . Moving by Word . . . . . . . . . . . . . . Moving by S-Expressions . . . . . . . . . . Other Movement Commands . . . . . . . Scrolling . . . . . . . . . . . . . . . . . . .

Bookmarks and Registers . . . . . . . . . . . . . Selections and Regions . . . . . . . . . . . . . .

Selection Compatibility Modes . . . . . . . Setting the Mark . . . . . . . . . . . . . .

Searching and Indexing . . . . . . . . . . . . . . Isearch: Incremental Search . . . . . . . . . Occur: Print lines matching an expression . Imenu: Jump to denitions . . . . . . . . . Helm: Incremental Completion and Selection IDO: Interactively DO Things . . . . . . .

Other Movement Commands . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . .

The Theory of Editing Killing and Yanking Text . . . . . . . . . . . . .

Killing versus Deleting . . . . . . . . . . . Yanking Text . . . . . . . . . . . . . . . .

Transposing Text . . . . . . . . . . . . . . . . . C-t: Transpose Characters . . . . . . . . . . M-t: Transpose Words . . . . . . . . . . . . C-M-t: Transpose S-expressions . . . . . . . Other Transpose Commands . . . . . . . .

Filling and Commenting . . . . . . . . . . . . . Filling . . . . . . . . . . . . . . . . . . . . Commenting . . . . . . . . . . . . . . . .

Search and Replace . . . . . . . . . . . . . . . .

Case Folding . . . . . . . . . . . . . . . . . Regular Expressions . . . . . . . . . . . . .

Changing Case . . . . . . . . . . . . . . . . . . Counting Things . . . . . . . . . . . . . . . . . Text Manipulation . . . . . . . . . . . . . . . .

Editable Occur . . . . . . . . . . . . . . . . Deleting Duplicates . . . . . . . . . . . . . Flushing and Keeping Lines . . . . . . . . . Joining and Splitting Lines . . . . . . . . . Whitespace Commands . . . . . . . . . . .

Keyboard Macros . . . . . . . . . . . . . . . . . Basic Commands . . . . . . . . . . . . . . Advanced Commands . . . . . . . . . . . .

Text Expansion . . . . . . . . . . . . . . . . . . Abbrev . . . . . . . . . . . . . . . . . . . . DAbbrev and Hippie Expand . . . . . . . .

Indenting Text and Code . . . . . . . . . . . . . RET: Indenting New lines . . . . . . . . . . TAB: Indenting the Current Line . . . . . . Indenting Regions . . . . . . . . . . . . . .

Sorting and Aligning . . . . . . . . . . . . . . . Sorting . . . . . . . . . . . . . . . . . . . . Aligning . . . . . . . . . . . . . . . . . . .

Other Editing Commands . . . . . . . . . . . . Zapping Characters . . . . . . . . . . . . . Spell Checking . . . . . . . . . . . . . . . uoted Insert . . . . . . . . . . . . . . . .

The Practicals of Emacs Exploring Emacs . . . . . . . . . . . . . . . . .

Reading the Manual . . . . . . . . . . . . .

Using Apropos . . . . . . . . . . . . . . . C-h: Exploring Prex keys . . . . . . . . . C-h k: Describe what a key does . . . . . . C-h m: Finding mode commands . . . . . .

Working with Log Files . . . . . . . . . . . . . . Browsing Other Files . . . . . . . . . . . .

TRAMP: Remote File Editing . . . . . . . . . . Multi-Hops and User Switching . . . . . .

Dired: Files and Directories . . . . . . . . . . . Navigation . . . . . . . . . . . . . . . . . . Marking and Unmarking . . . . . . . . . . Operations . . . . . . . . . . . . . . . . . . Working Across Directories . . . . . . . . .

Shell Commands . . . . . . . . . . . . . . . . . Compiling in Emacs . . . . . . . . . . . . .

Shells in Emacs . . . . . . . . . . . . . . . . . . M-x shell: Shell Mode . . . . . . . . . . . . M-x ansi-term: Terminal Emulator . . . . . M-x eshell: Emacss Shell . . . . . . . . . .

Conclusion Other Resources . . . . . . . . . . . . . . . . .

Chapter

Introduction

Im using Linux. A library that emacs uses tocommunicate with Intel hardware.

Erwin, emacs, Freenode.

Thank You

Thank you for purchasing Mastering Emacs. This book hasbeen a long time coming. When I started my blog, Master-ing Emacs, in , it was at the recommendation of a goodfriend, Lee, who suggested that I share my thoughts onEmacs and work ow in Emacs. At the time I had accruedin an org mode le titled blogideas.org a large but randomassortment of ideas and concepts that Id learned about andwished someone had taught me. The end result of that leis the blog and now this book.

Special Thanks

Introduction

I would like to thank the following people fortheir encouragement, advice, suggestions andcritiques:

Akira Kitada, Alvaro Ramirez, Arialdo Mar-tini, Bob Koss, Catherine Mongrain, ChandanRajendra, Christopher Lee, Daniel Hannaske,Edwin Ong, Evan Misshula, Friedrich Paetzke,Gabriela Hajduk, Gabriele Lana, Greg Sieranski,Holger Pirk, John Mastro, John Kitchin, JonasEnlund, Konstantin Nazarenko, Lee Cullip,Luis Gerhorst, Lukas Pukenis, Manuel Uberti,Marcin Borkowski, Mark Kocera, Matt Wilbur,Matthew Daly, Michael Reid, Nanci Bonm,Oliver Martell, Patrick Mosby, Patrick Martin,Sebastian Garcia Anderman, Stephen Nelson-Smith, Steve Mayer, Tariq Master, TravisJeerson, Travis Hartwell.

Like a lot of people, I was thrust into the world of Emacswithout knowing anything about it; in my case it was inmy rst year of University where the local computer soci-ety was made up primarily of Vim users. It was explainedto me, in no uncertain terms, that you use Vim thatsit. Not wanting to be told what to do, I picked the polaropposite of Vim and went with Emacs.

Emacs proved to be a stable and reliable editor in all thoseyears, but it was a tough one to get to know. Despite theextensive user documentation, it never helped me to learnand understand Emacs.

Introduction

As it turns out, Emacs is a philosophy or even a religion. So,the joke about the Church of Emacs is eerily accurate inmany ways, as you will nd out in the next chapter.

Intended Audience

Its a bit weird talking about the intended audience whenyouve already bought the book on the subject. But it bearsmentioning anyway so no matter your Emacs skill level youwill get something out of this book.

The rst and (most obvious) audience are people new toEmacs. If youve never used Emacs before in your life, youwill hopefully nd this book very useful. However, ifyoure new to Emacs and non-technical, then youre goingto have a harder time. Emacs, despite being suitable formuch more than just programming, is squarely aimed atcomputer-savvy people. Although its perfectly possibleto use Emacs anyway, this book will assume that youretechnically inclined, but not necessarily a programmer.

If youve tried Emacs before but given up, then I hope thisbook is what convinces you to stick with it. But its ne ifyou dont; some languages or environments dont (contraryto what a lot of Emacs users would claim) work well withEmacs. If youre primarily a Microsoft Windows developerworking with Visual Studio, using Emacs is going to be acase of two steps forward, one step back: you gain unprece-dented text editing and tool integration but lose all the ben-ets a unied would give you.

If youre a Vim refugee, then welcome to the dark side! Ifyour primary objective is to use Emacss Vim emulation lay-

Introduction

ers, then some of this book is redundant; it concerns itselfwith the default Emacs bindings and it teaches the Emacsway of doing things. But not to worry: a lot of the tips andadvice herein are still applicable, and who knows maybeyoull switch away from Evil mode in time.

And nally, if youre an existing Emacs user but strugglingto take it to the next level, or maybe you just need a refreshercourse from the ground up, then this book is also for you.

What Youll Learn

Covering all of Emacs in just one book would be a Sisypheantask. Instead, I aim to teach you what you need to be produc-tive in Emacs, which is just a small subset of Emacss capabil-ity. Hopefully, by the end of this book, and with practice,you will know enough about Emacs to seek out and answerquestions you have about the editor.

To be more specic, I will teach you, in broad terms, sixthings:

What Emacs is about A thorough explanation of impor-tant terminology and conventions that Emacs useswhich in many cases diers greatly from other editors.You will also learn what the philosophy of Emacs is,and why a text editor even has a philosophy. I willalso talk about Vim briey and the Editor Wars andwhat the deal is with all those dierent keys.

Getting started with Emacs How to install Emacs, how torun it, and how to ensure youre using a reasonably

Introduction

new version of Emacs. I explain how to modify Emacsand what you need to do to make your changes perma-nent. I will introduce the Customize interface and howto load a color theme. And nally, Ill talk about theuser interface of Emacs and some handy tips in caseyou get stuck.

Discovering Emacs Emacs is self-documenting; but whatdoes it mean and how can you leverage that aspectto discover more about Emacs or answer questionsyou have about particular features? I will show youwhat I do when I have to learn how to use a newmode or feature in Emacs, and how you can use theself-documenting nature of Emacs to nd things forwhich youre looking.

Movement How to move around in Emacs. At rst glance asimple thing to do, but in Emacs there are many waysof going from where you are to where you need togo in the fewest possible keystrokes. Moving aroundis probably half the battle for a developer and know-ing how to do it quickly will make you more ecient.Some of the things youll learn: moving by syntacticunits, and what exactly syntactic units are; using win-dows and buers; searching and indexing text; select-ing text and using the mark.

Editing As in the chapter on movement, I will show youhow to edit text using a variety of tools oered to youby Emacs. This includes things like editing text by bal-anced expressions, words, lines, paragraphs; creatingkeyboard macros to automate repetitive tasks; search-

Introduction

ing and replacing; registers; multi-le editing; abbre-viations; remote le editing; and more.

Productivity Emacs can do more than just edit text and thischapter is only a taste of what attracts so many peopleto Emacs: its tight integration with hundreds of exter-nal tools. I will whet your appetite and show you someof the more interesting things you can do when youchoreograph Emacss movement and editing.

Chapter

TheWay of Emacs

The purpose of a windowing system is to putsome amusing u around your one almightyemacs window.

Mark, gnu.emacs.help.

If you imagine the span of the modern computing era be-ginning in the s, then Emacs has been there longer thanjust about everything else. It was rst written by RichardStallman as a set of macros on top of another editor, called, back in .1 is now mostly remembered for be-ing even more obtuse and hard to understand than Emacsand -era WordPerfect combined. Since then, there havebeen many competing implementations of Emacs but todayyoure only likely to encounter XEmacs and Emacs.

https://www.gnu.org/software/emacs/manual/html_mono/efaq.htmlOrigin-of-the-term-Emacs

TheWay of Emacs

This book will only concern itself with Emacs. Onceupon a time XEmacs was the more advanced and featurerich editor, but this is no longer the case: from Emacs on-wards Emacs is the best Emacs out there. The historyof XEmacs and Emacs is an interesting one. It was oneof the rst major forks2 in a free software project and bothXEmacs and Emacs are developed in parallel to this day.

Note

To almost everyone, the wordEmacs refers specif-ically to Emacs. I will only spell out the fullname when I am distinguishing between dier-ent implementations. When I mention Emacs, Ialways talk about Emacs.

Because of Emacss age there are a number of oddities.Weird choices of terminology and historical anachronismspersist because in most cases Emacs was ahead of the editor- curve for many decades and thus had to invent its ownterminology for things. There are talks of replacing Emacssown vernacular with words familiar to everyone, but thatis still a long way o.

Despite the lack of marketing, a small core of Emacs devel-opers, the anachronisms and terminology that predates themodern Personal Computing-era, there are many peopleout there who just love using Emacs. When Sublime Textshowed o its mini-map feature (a miniature display of thesource code) someone immediately coded up a minimappackage doing the same thing in Emacs. In fact, it is this

http://www.jwz.org/doc/lemacs.html

TheWay of Emacs

extensibility that attracts some to and repels others from Emacs.

This chapter will talk about the Way of Emacs: the terminol-ogy and what Emacs means to a lot of people, and why un-derstanding where Emacs comes from will make it easier toadopt it.

Guiding Philosophy

Emacs is a tinkerers editor. Plain and simple. People whohack on Emacs do it because almost every facet of it isextensible. It is the original extensible, customizable, self-documenting editor. If you come from other text editors,the idea of being able to change anything may seem like anunnecessary distraction from your work and indeed, alot of Emacs hacking does happen at the expense of onesreal job but once you realize that you can shape youreditor to do what you want it to do, it opens up a world ofpossibilities.

That means you can truly rebind all of Emacss keys to yourliking; you are not hidebound by your s undocumentedand buggy nor the limitations that would follow if youdid change things such as your custom navigation keysnot working in, say, the search & replace window or in theinternal help les. Truly, in Emacs, you can change every-thing and people do. Vim users are migrating to Emacsbecause, well, Emacs is often a better Vim than Vim.

Emacs pulls you in. Once you start using Emacs for the edit-ing, you realize that using Emacs for , email, database ac-cess, command-line shells, compiling your code or surng

TheWay of Emacs

the Internet is just as easy as editing text and you get tokeep your key bindings, theme and all the power of Emacsand elisp to congure or alter the behavior of everything.And when everything is seamlessly tied together you avoidthe usual context switches of going from application to ap-plication: most Emacs users use little more than the editor,a browser and maybe a dedicated terminal application.

Emacss history

Emacss source code repository (now in Git)stretches back over years and has more than, commits and nearly committers.

If you want to modify Emacs, or any of the myriad pack-ages available to you, Emacs Lisp (also known informally aselisp) is what you will have to write. There have been a fewattempts to graft other languages onto elisp and Emacs butwith no lasting eect. As it turns out, is actually a per-fect abstraction for a very advanced tool like Emacs. Andmost modern languages wouldnt necessarily stand the testof time: was briey considered in the s as it was popu-lar at the time but that has the distinction of being evenmore obscure than , nowadays.

The only downside is that ddling with your Emacs cong-uration is something you will have to learn to live with (andin no less, but as I explain in the next part thats actuallya good thing.) Thats why I reinforced the point that its atinkerers editor. If you hate the idea of tweaking anythingand want everything out of the box, you have two optionsleft:

TheWay of Emacs

Use a starter kit There are many free starter kits that comeequipped with additional packages and what theauthor thinks are sensible default settings. They canbe a good way to start out but with the caveat thatyou dont know where Emacs ends and the starterkits added functionality begins.

I recommend you look at one of the following starterkits widely used:

Steve Purcells .emacs.dhttps://github.com/purcell/emacs.d

Bozhidar Batzovs Preludehttps://github.com/bbatsov/prelude

Use the defaults Certainly an option but Emacs, I wouldsay, is rather lacking out of the box. You are expectedto congure Emacs to your liking or use a starter kit.For an editor that is so radically dierent from main-stream editors, the maintainers are surprisingly conser-vative about changing the defaults for fear of upsettingthe old guard (who, of all people, should know how tocongure Emacs.)

LISP?

Emacs is powered by its own implementation calledEmacs Lisp or just elisp. Many are put o or intimidated bythis esoteric language; thats a shame, because its a practicaland fun way to learn in an editor built up around theidea of . Every part of Emacs can be inspected, evaluatedor modied because the editor is approximately percent

TheWay of Emacs

elisp and percent C code. Its also a practical way to learna radical paradigm: that code and data are interchangeableand malleable; that the language, owing to its simple syntax,is trivially extensible with macros.Unfortunately, theres no getting around learning elisp atsome point. In this book, I will talk about the Customize in-terface: a dynamically generated interface of customizableoptions in Emacs. However, something as simple as rebind-ing a key means youll have to interact with elisp. But itsnot all bad. Most of the problems youre likely to encounterhave already been solved by someone else a long time ago;its a simple matter of searching the Internet for a solutionto your problems.

Despite the relative unpopularity of elisp versus more mod-ern languages like Python, Ruby and JavaScript, I doubtEmacs would have had the same power of extensibility ifa more traditional imperative/object-oriented language hadbeen used. What makes such a fantastic language is thatsource code and data structures are intrinsically one and thesame: the source code you read as a human is almostidentical to how the code is manipulated as a data structureby the distinction between the questions What isdata? and What is code? are nil.

The data-as-code, the macro system and the ability to ad-vise arbitrary functions meaning you can modify the be-havior of existing code without copying and modifying theoriginal give you an unprecedented ability to alter Emacsto suit your needs. What would in most software projectsbe considered code smells or poor architecture is actually amajor benet in Emacs: you can hook, replace or alter exist-

TheWay of Emacs

ing routines in Emacs to suit your needs without rewritinglarge swathes of someone elses source code.

This book will not teach elisp in any great detail: Emacs hasa built-in elisp introduction3 and I highly recommend it ifyou are curious and honestly you should be. is funand this is a great way to learn and use a powerful languagein a practical environment. Dont let the parentheses scareyou; they are actually its greatest strength.

Emacs as an Operating System

When you run Emacs you are in fact launching a tiny Ccore responsible for the low-level interactions with your op-erating systems . That includes mundane things like le-system and network access; drawing things to the screen orprinting control codes to the terminal.

The cornerstone of Emacs though is the elisp interpreter without it, there is no Emacs. The interpreter is creaky andold; its struggling. Modern Emacs users expect a lot fromtheir humble interpreter: speed and asynchrony are the twomain issues. The interpreter runs in a single thread and inten-sive tasks will lock the thread. But there are workarounds;the issues, manifold though they are, do not deter peoplefrom writing ever-more sophisticated packages.

When you write elisp you are not just writing snippets ofcode run in a sandbox, isolated from everything you arealtering a living system; an operating system running on anoperating system. Every variable you alter and every func-

https://www.gnu.org/software/emacs/manual/eintr.html

TheWay of Emacs

tion you call is carried out by the very same interpreter youuse when you edit text.

Emacs is a hackers dream because it is one giant, mutablestate. Its simplicity is both a blessing and a curse. You canre-dene live functions; change variables left and right; andyou can query the system for its state at any time state thatchanges with every key stroke as Emacs responds to eventsfrom your keyboard to your network stack. Emacs is self-documenting because it is the document. There are no othereditors that can do that. No editor comes close.

And yet Emacs never crashes not really, anyway. Emacshas an uptime counter to prove that it doesnt (M-x emacs-uptime) multi-month uptimes are not uncommon.

So when you ask Emacs a question as I will show you howto do later you are asking your Emacs what its state is. Be-cause of this, Emacs has an excellent elisp debugger and un-limited access to every facet of Emacss own interpreter andstate so it has excellent code completion too. Any timeyou encounter a expression you can tell Emacs to evalu-ate it, and it will: from adding numbers to setting variablesto downloading packages.

Extensibility

Extensibility is important, but emphasizing that importanceis dicult if you dont know the scope of possibilities inEmacs. Ive included just a few examples of what Emacs cando or more importantly still, what Emacs can enable peopleto do here.

TheWay of Emacs

A speech interface for the blind For years, Emacs-peak4 has oered blind or visually impaired Emacsusers a way of interacting with Emacs, and the world,through a speech interface that understands the con-tent of what appears on your screen. Emacspeak willchange the voice characteristics of the speech engineto reect dierent syntactic elements in source code,or to emphasize layout, fonts or graphical icons. Forblind Emacs users, Emacspeak is a lifeline that hasenabled them to continue working by using Emacssmany tools, such as e-mail or web browsing.

The fact that this functionality has been around for years is in itself impressive, but Emacss ability to sup-port this sort of transformational software is beyondinspiring.

Remote le editing Emacss 5 seamlessly lets youedit remote les using a variety of network protocols,including , , rsync, and more, as though theles were local.

Shell access Emacs has a built-in -capable Terminal em-ulator; an Emacs wrapper around shells, such as bash;and a full-blown shell called Eshell written entirely inelisp.

ORGmode A to-do, agenda, project planner, literateprogramming, note-taking (and more!) application.It is widely considered the best text-based organizer ever

http://emacspeak.sourceforge.net/Transparent Remote (le) Access, Multiple Protocol

TheWay of Emacs

a feat only surpassed by the fact that people switchto Emacs just to use it.

And much more Ocial or unocial support for almostevery programming environment; built-in man pageand info reader; a very sophisticated directory and lemanager; seamless support for almost every major ver-sion control system; and thousands of other features,large or small.

Important Conventions

There are some important Emacs conventions that I need totalk about before we continue. Its quite important that youmemorize them or at least refer back to this page if yourein doubt. They will crop up again and again in the bookand elsewhere and knowing them is paramount if you wantto make use of Emacss extensive, internal documentation.This is not an exhaustive list of conventions used in Emacsor even in this book. I will introduce specic terms and con-cepts throughout the book, though some terms transcendspecic topics and are therefore important to know before-hand.

TheWay of Emacs

The Buer

Most text editors and s are le based: they display text froma le, and they save the text to a le. Thats it.In Emacs, all les are buers, but not all buers are les. Ifyou want a throw-away area to temporarily store snippetsfrom a log le, or manipulate text, or whatever your reason

you just create and name a new buer. Emacs wont hassleyou for a lename. The buer will exist in Emacs and onlyEmacs. You have to explicitly save it to a le on disk to makeit persist.

Emacs uses these buers for more than just editing text. Itcan also act like an / device and talk to another process,such as a shell like bash or even Python.Almost all of Emacss own commands act on buers. Sowhen you tell Emacs to, for example, search & replace it

TheWay of Emacs

will actually search and replace on a buer maybe the activebuer youre writing in, or perhaps a temporary duplicate and not an internal data structure like you might think.In Emacs, the buer is the data structure. This is an extremelypowerful concept because the very same commands youuse to move around and edit in Emacs are almost always thesame ones you use behind-the-scenes in elisp. So once youmemorize Emacss own user commands, you can use themin a simple function call to mimic what youd do by hand.

TheWindow and the Frame

When you look at a buer on the screen it is displayed ina window. But in Emacs, a window is just a tiled portion ofthe frame, which is what most window managers call a win-dow. In Emacs, it is the other way around; and yes, its veryconfusing.

If you look at the screenshot above, you will see two win-dows and one frame. Each frame can have one or more win-dows, and each window can have exactly one buer.So, a buer must be viewed in a window in order to be dis-played to the user, and for the window to be visible to theuser it must be in a frame.

Note

Think of it as a physical window having a frame,each frame made up of window panes.

In Emacs, you are free to create as many frames as you like,and in each frame youre free to split and tile that frame into

TheWay of Emacs

multiple windows. If you use a large screen monitor (andwho doesnt, these days), it is very benecial to use Emacsstiling system to show multiple buers on the screen.

Modeline, Echo Area, and Minibuer

The gure above is an example of a Terminal Emacs session.Emacs uses the modeline to communicate facts about Emacsand the buer youre in. The modeline looks like this:

-UUU:**--F3 *scratch* All L4 (Lisp Interaction) --

Theres a lot of information conveyed in a fairly small area.What you should care about to begin with are the name andmodes. In this case, the buer is named *scratch* and the ma-jor mode is Lisp Interaction. Most editors have a similar con-cept known as a status bar.

All sorts of optional information can be displayed in the mod-eline: laptop battery power, the current function or classyoure in, what source control revision or branch youre us-ing, and much more.

TheWay of Emacs

The minibuer is directly below the modeline and it iswhere errors and general information are shown:

-UUU:**--F3 *scratch* All L4 (Lisp Interaction) --M-x insert-hello-world

In this case, I have triggered Emacss extended command func-tionality indicated by the M-x symbol, a concept that I willtalk about in the chapter on keys and Ive typed the com-mand insert-hello-world into the M-x prompt.

The echo area and the minibuer share the same spot on thescreen. The minibuer is nearly identical to a normal buer:you can use most of your editing commands, and the one-line minibuer will expand to multiple lines if necessary. Itis how you communicate with Emacs: if you want to searchfor a string you write the string you want to search for inthe minibuer. It supports a variety of complex completionmechanisms to help you nd what you need and is a toolyou will use often.

The Point and Mark

The point is just another word for the caret or cursor. TheEmacs documentation is rather inconsistent in its use of pointor cursor; you will see both. Nevertheless, the point itself isyour current position in a buer. Its often represented (par-ticularly in Emacss doc strings and documentation) as -!-but in this book I will use to represent the point. Eachbuer tracks the position of the point separately, so if youswitch between buers the location of each point is remem-bered separately.

TheWay of Emacs

Note

In Emacs, we talk a lot about a current buer,which can mean two things only one of whichis interesting to us, at the present and that iswhichever buer has the point (the other case is ba-sically the same, but involves programmaticallychanging the buer in elisp.) A buer that has thepoint is the current buer because it is the one youwrite and move around in. Only one buer canever be the current buer at a time, and it is thisbuer that has the point.

The point, in Emacs, has more utility than just acting asa visual marker for where characters you type end up onthe screen. It is also one part of a duo called the point andmark. The point and mark represents the boundary for aregion, which is a contiguous block of text, usually, in thecurrent buer. In other editors, it is called the selection orthe highlight. Most editors dont have specic names for thebeginning and end of a region but in Emacs we do, and inSelections and Regions I will talk more about the reason.

Tip

Historically, Emacs did not show you the visibleregion on the screen but instead you had to men-tally visualize it. Emacs has supported visual re-gions for a very long time now, called the tran-sient mark mode (or just .) It is enabled by de-fault. Surprisingly, theres some value in not us-ing at all, but I will talk about that muchlater.

TheWay of Emacs

But like the point, the mark is more than what it seems. Itserves as a boundary for the region, yes, but it is also a beaconyou can use to return to from other parts in the buer. Themark is typically invisible.

Killing, Yanking and CUA

The rst and perhaps most abhorrent, to beginners de-viation from de-facto user interface standards is Emacss clip-board system. Cut, copy and paste are known, almost univer-sally, to most as Ctrl+x or Shift+Del; Ctrl+c or Ctrl+Ins; and

Ctrl+v or Shift+Ins, respectively.

In Emacs, the keys and the terminology dier greatly:killing is cutting; yanking is pasting; and copying isawkwardly known as saving to the kill ring (or just copy,informally.)

The reasons, as before, are historical. Most of the keys andterminology stem from IBMs Common User Access6 ()and Apple. But the was introduced in , many yearsafter Emacs had settled on its own terminology and stan-dards.

In Selection Compatibility Modes, I will explain how youcan switch to modern clipboard keys, with certain caveats,and why you shouldnt do that. Instead, Ill show you whyEmacss system is better for text editing.

http://en.wikipedia.org/wiki/IBM_Common_User_Access

TheWay of Emacs

.emacs.d, init.el, and .emacs

A favorite pastime of Emacs users is sharing with otherEmacs hackers little snippets of code or customizations thatmake their lives easier.

Historically, these settings were kept in a le called .emacs,but most keep their customizations in ~/.emacs.d/init.el onLinux and %HOME%\init.el on Windows. Since Emacs nowwrites several more les to your le system, they are keptin a directory called .emacs.d to avoid cluttering your homedirectory.

So, when people talk about their init le, or their .emacsle, or if they tell you to put something in said le, thatswhat theyre referring to. If you are new to Emacs, youshould use ~/.emacs.d/init.el. When you add somethingto the le you will need to tell Emacs to run it. Thereare many ways of doing this, and I will explain how inEvaluating Elisp Code, but my preferred recommendationfor beginners is to close Emacs and restart it.

Note

Starter kits in Emacs are very common now.Theyre community additions to Emacs thatbundle many changes and even entire third-party packages and if you use one, you shouldread their documentation for best practices onwhere to store your own changes.

Emacs will not save changes for you. If you want Emacs tokeep changes, you must do it through the Customize inter-face. That means it is your responsibility to save changes you

TheWay of Emacs

want to keep to init.el. Likewise, if you made a mistake andbroke something in Emacs or if you made changes you donot care for, simply quit and restart Emacs.

Major Modes and Minor Modes

Major modes in Emacs control how buers behave. So, ifyou want to edit Python code and you visit a le in Emacscalled helloworld.py, then Emacs will know, through a cen-tralized register that maps le extensions to major modes,that this is a Python le and it should use the Python majormode. Each buer will always have a major mode. The majormode may be basic and oer no font locking (syntax highlight-ing) and no specic functionality, or it may be the completeopposite and introduce font locking, an advanced indenta-tion engine, and specialized commands.

Note

Font Locking is the correct term for syntax high-lighting in Emacs, and in turn is made up of facesof properties (color, font, text size, and so on)that the font locking engines use to pretty-printthe text.

You are free to change a buers major mode at any time bytyping the command for another one. In addition to Emacssregister of le extensions and associated major modes, thereis another system for les with ambiguous (or no) le exten-sions at all: Emacs will scan the rst portion of the le andtry to infer the major mode from that. Rarely, Emacs willget it wrong and you will need to change it.

TheWay of Emacs

Its important to remember that each buer can have justone major mode. Minor modes, by contrast, are typicallyoptional add-ons that you enable for some (or all) of yourbuers. One example is yspell mode, a minor mode that spellchecks text as you write.

The major mode is always displayed in the modeline. Someminor modes are also displayed in the modeline, but usuallyonly the ones that alter the buer or how you interact withit in some way.

Chapter

First Steps

I use Emacs, which might be thought of as a ther-monuclear word processor.

Neal Stephenson, In the Beginning was theCommand Line.

Installing and Starting Emacs

Before I get into the nitty-gritty of installing Emacs, youshould check and see if its installed already. In most normalLinux distributions it is not; therefore, you have to be extravigilant if it is: it might be an ancient version.

Checking Emacss version

You can check Emacss version by typing emacs--version.

First Steps

As of the upcoming version is Emacs . If yourversion of Emacs is version .x or older upgrade. If its.x or newer, then thats ne. If youre still on .x you canget by with what you have, but my view is to always usethe latest release. Not so much for the bug xes (becauseEmacs is actually extremely stable) but for the features andthe fact that most package authors assume youre using thelatest version. (Having said that, if youre on a very obscureplatform it may not be possible for you to upgrade at all.)

If youre using XEmacs or another non- Emacs, you re-ally should switch. Ten or twelve years ago, XEmacs wasleading the pack but Emacs caught up and exceeded thecapabilities of XEmacs a long time ago.

Surprisingly, Emacs ran on some incredibly old platforms1

until Emacs . (released in July ), including the follow-ing: Tandem Integrity S; Apollo SR.x; the Acorn; theHarris Night Hawk Series and Series ; and aboutanother two or three dozen more obscure platforms.

Emacs does ocially support the usual avor of s andLinux, Mac , -, and Microsoft Windows.

I will not go into too great a detail on how to do this in thisbook. Emacs was made to be a cross platform but there arealways some trade-os if you dont run them on Linux. Mac, in particular, seems to attract a great deal of conictingadvice on how to best run Emacs; the best advice I can oeris to try out a few dierent approaches and nd one that tsyou.

http://www.gnu.org/software/emacs/MACHINES

First Steps

Microsoft Windows Emacs releases ocial builds for Mi-crosoft Windows on their ocial site.2 Extracting andrunning the executable is all it takes.

Most external tool support will not work on Win-dows. Functionality like built-in grep support requiresthe coreutils to be present. You can, however,run Emacs from Cygwin3 and get a Linux-like envi-ronment on Windows that way. Alternatively, thecross-compiled GnuWin4 project has almost everyLinux command line program that runs natively onWindows.

Mac OSX One approach (though there are several) isto use an unocial build of Emacs.5 There is alsoAquamacs but it diers from Emacs quite a bit.The topic itself is rather complex. Some prefer usinga package manager like homebrew and others donot. Generally, people who use homebrew often usethe homebrew version of Emacs also. EmacsWikisarticle6 on installing Emacs on Mac is a goodplace to start if you want to compile Emacs yourself.

Linux Emacs is almost always present in your distributionspackage manager. Some distros are slow to updateto new minor releases (which are rarely minor at all,adding a lot of new functionality and bug xes) so itmay be worth your while to build from source.

http://ftp.gnu.org/gnu/emacs/windows/http://www.cygwin.com/http://gnuwin.sourceforge.net/http://emacsformacosx.com/http://www.emacswiki.org/emacs/EmacsForMacOS

First Steps

On Ubuntu, its as easy as apt-get install emacs24.If you want to build your own version of Emacsfrom source, I recommend you use apt-get build-depemacs24 to build and install Emacss dependencies.From that point on its easy to follow the usualcongure, make, make install procedure.

Starting Emacs

Starting Emacs is as simple as running emacs from the com-mand line. If you run the command from a window man-ager, then Emacs will launch as Emacs as opposed toTerminal Emacs where Emacs is running inside a terminal.

You can force Emacs to run in a terminal, even in a windowmanager, by giving it the argument -nw, like so: emacs -nw.

Theres a host of command line switches you can pass toEmacs, but you only need four to get started:

Switch Purpose

--help Display the help-nw Forces Emacs to run in terminal mode-q Do not load an init le (such as init.el)-Q Does not load the site-wide startup le7, your

init le, nor X resources

If Emacs is giving you error messages when you start it, youcan use -q to prevent your init le from loading. If that xesthe errors then you have a broken init le and should take

The site-wide le is a global settings le like your own init le

First Steps

steps to remedy that: revert to an older version, commentout code until it works, or ask for help.

The Emacs binary follows the usual command line conven-tions: emacs [switches] [ file1, file2, ...].

The Emacs way is to keep it running and do all your edit-ing in a dedicated Emacs instance. Emacs will typically startslower than other editors (as it has a lot more packages andfeatures) as its designed for long-running sessions and notquick edits.

Emacs Client-Server

So, how do you deal with situations where youre whilingaway at the command line but have to edit a le? Maybeyoure writing an email from the command line or writinga commit message youd want to use Emacs, and ideallythe same instance of Emacs you already have running. Theanswer, ignoring the fact that Emacs has rst-class supportfor both email and source control systems, is Emacss client-server mode. (Yes, Emacs has a client-server architecture.)

Note

The client-server functionality is fantastic, but Iwouldnt spend too much time playing aroundwith it until youre comfortable with Emacs ba-sics.

The myriad advantages of Emacss server mode are:

First Steps

A persistent session means Emacs will re-use the same ses-sion instead of spawning a new, distinct copy of Emacsevery time.

It works well with $EDITOR by opening the les in yourshared Emacs session and automatically signalling thecalling program when the session nishes.

Fast le opening from the command line using theemacsclient binary. The Emacs client will connect tothe local Emacs server instance and instruct it to openthe le.

To use the client-server functionality, you must explicitlystart the server:

M-x server-start launches a server inside an already-runningEmacs instance. The instance turns into a server when youtype this; theres no visual feedback, per se, that its running.When you exit this Emacs instance, it will shut down theserver also so if you want a server daemon you need theoption below.

emacs --daemon will run Emacs as a daemon. It will callserver-start, as above, but will return control to yourterminal immediately and run in the background, waitingfor client requests.

If you go the server route, you cannot use the default emacs bi-nary any more. That binary will spawn standalone instancesonly. You must use the similarly-named emacsclient instead.Set your $EDITOR environment variable to emacsclient andthings should just work from then on.

First Steps

The emacsclient binary has its own set of switches youshould know about:

Switch Purpose

--help Displays the help.-c Creates a graphical frame (if X is available)

or a terminal frame if X is unavailable.-nw Creates a terminal frame.-n The client will return immediately instead of

waiting for you to save your changes.Useful if you just want to open a bunch of les.

When you launch an emacsclient instance, the client willwait for the le(s) to nish editing. Pressing C-x #will switchto the next buer youre editing through a client whenyouve done this for the le(s) you opened, Emacs will sig-nal to the client to exit and return control to the terminal.If youre using a tool like git that lets you use your $EDITORto edit commit messages when using other editors, git willwait until it receives the go-ahead from your editor that ithas saved the commit messages to a temporary le beforeresuming with the commit operation.

You can add the -n switch if you want the client to justopen the les and not wait. I nd this useful if Im doingexploratory work or if I want the les permanently openin Emacs.

First Steps

The Emacs Interface

When you rst launch Emacs, youre greeted with the splashscreen. Its probably one of the rst things most Emacs hack-ers disable, along with the scroll bars, the menu and tool bar.Until youre comfortable with Emacs I would recommendyou leave the elements enabled since they will provideyou with a quick way to access common functionality thatyou may not remember how to do o-hand, although theytake up valuable real estate on your screen.

First Steps

If youre using Emacs in the Terminal, you can still accessthe menu bar by pressing F10.

If you dont see a user interface similar to the gure above,its most likely due to customizations made to your init le.The quickest way to test this is to close Emacs and restartit with emacs -q. If that xes things, then its denitely cus-tomizations made to your Emacs. Most starter kits assumeyoure reasonably familiar with Emacs and they often disablethings like the menu bar and tool bar.

You are actually free to play around with Emacs now: thearrows keys will work ne and, combined with the menu bar,you can open and save les. Emacs will auto-detect most letypes and apply the correct major mode to it if it doesnt,you may have to install third-party packages, which I willtalk about later.

Keys

The most important subject in Emacs. Emacs is famous fortwo things: its obscure keyboard incantations and that itsthe kitchen sink editor that can do everything. The comicstrip xkcd8 humorously referenced that part of Emacs lore.A much older joke is that Emacs stands for Escape MetaAlt Control Shift.

Nevertheless, key modiers are a big part of day-to-dayEmacs use so being able to decode a string of keys isimportant.

http://xkcd.com//

First Steps

In Emacs, there are several modier keys you can use, eachwith its own character:

Modier Full Name

C- ControlM- Meta (Alt on most keyboards)S- Shift

Two more exist for historical reasons (Super and Hyper)but dont have dedicated keys on todays keyboards, but forconsistency with Space Cadet keyboards9 still exist inter-nally; another key (Alt) does exist on modern keyboards butis bound (and known by) as Meta in Emacs:

Modier Full Name

s- Super (not shift!)H- HyperA- Alt (redundant and not used)

Super and Hyper can still be used, and if youre the ownerof a Microsoft Windows-compatible keyboard with theStart and Application Context buttons, you can rebindthem to serve as Super and Hyper which is very useful.Emacs supports the modiers natively but you need to tellyour operating system or window manager to bind them.

Important

http://home.comcast.net/~mmcm/kbd/SpaceCadet.html

First Steps

Owing to the limitations of terminals, there aresome key bindings you simply cannot type ifyoure running Emacs in a terminal. My adviceis to run Emacs in a , if at all possible.

Knowing the modiers is only one half of the equationthough.

In Emacs, we formally dene a key sequence (or just key) tomean a sequence of keyboard (or mouse) actions and a com-plete key to mean one or more keyboard sequences that invokea command; if the sequence of keys is not a complete key, thenyou have a prex key. And if the key sequence is not recog-nized by Emacs at all it is invalid, and an error is displayedin the echo area.

Thats a rather dry denition, so lets look at a few examples.

C-d calls a command named delete-char. To invoke it, holddown control and press d. As the key is a complete key,it will call the command delete-char and immediatelydelete the character next to point.

C-M-d is similar to the example above, but this time you musthold down both control and meta before you press d.

Lets try a few prex keys. Prex keys are basically subdivi-sions a way of grouping keys and increasing the numberof possible key combinations. For instance, the prex keyC-x has several dozen keys bound to it. C-x is a prex keyyou will use all the time.

First Steps

C-x C-f in Emacs runs a command called find-file. The wayto interpret it is to rst hold down control and thenpress and release x. In your echo area, Emacs will dis-play after a small idle period of about a second C-x-(with a dash at the end) which is Emacss way of tellingyou that it expects additional keys. Finally, type C-fwhich should be easy for you to do now: hold down

control and press f.

To type C-x C-f, you dont have to release the controlkey between each key keeping control pressed helpsyou maintain something I call tempo, which I will talkabout later.

C-x 8 P has two prex keys: rst C-x and then 8, which is asubcategory to C-x. So 8 on its own wouldnt do any-thing (it would just print the number 8) nor would C-xor even C-x 8 both are still prex keys. The key iscomplete only when you nish with P.

We call sets of keys that belong to a particular prexkey key maps, which is how Emacs internally tracksthe mapping between a key and a command. In thiscase, the key map C-x 8 has a variety of utility charac-ters used in writing or mathematics but not bound onmost keyboards. For instance, C-x 8 P will insert theparagraph symbol .

C-M-% is a tricky one for beginners. Using what youvelearned above, hold down control and alt (and asyoull remember from the table above, Meta is Alt)but also shift. The % character is typically shared with

First Steps

a number on the keyboard number range and theimplication here is you must type shift also.

If you dont press shift, youre actually typing C-M-5(on a US keyboard, anyway.)

It bears mentioning that this particular key is boundto a popular command (M-x query-replace-regexp) andis an example of a key that you cannot type in TerminalEmacs because of the terminals technical limitations(and not Emacs.)

TAB, F1F12 and so on are occasionally written like this, butalso in angle brackets: , . Its important youdont confuse TAB with the characters T A B. I will onlyuse the former notation to avoid ambiguities.

Hint

If youre stuck, or in the unlikely event Emacshas seized up, or if you have typed in a partialcommand that you want to cancel press C-g.Thats the universal bail me out command inEmacs.

Caps Lock as Control

One of the most important modications you should maketo your environment is rebinding your caps lock key to con-trol. Youre going to use the control key a lot and to avoid theEmacs pinky I suggest you unbind your right control entirelyand instead use caps lock.

Yes, itll be an annoying transition but a worthwhile one(that will, incidentally, serve you well outside of Emacs.)

First Steps

This change is necessary because on older keyboards10 thecontrol key occupied the space now used by the caps lockkey so reaching the left control key could be done withoutstraining your left pinky.

On Windows, I recommend you use SharpKeys.11 OnUbuntu and Mac , its built-in; go to the Keyboardsettings and change it. If youre using another Linuxdistribution you may have to ddle with xmodmap.

M-x: Execute Extended Command

Only a small portion of available commands in Emacs arebound to actual keys. Most are not: they are rarely used, anddo not warrant a key binding; or maybe you have explicitlyoverridden the key it was bound to, leaving it unbound; orperhaps you forgot its key binding.

In essence, its common that you want to run seldom-usedcommands. To do this press M-x (pronounced mex, M x, ormeta x.) In your minibuer, a prompt will appear and youare free to input the name of a command you wish to run.

When Emacs users say something like run M-x lunar-phasesto see the lunar phases of the moon what theyre saying is:hold down meta and press x and the M-x prompt will appear inyour minibuer (thats the line at the very bottom of Emacs.)

At this point you can type in the name of the command. Tryit, enter lunar-phases and press RET. The lunar-phases com-mand will open a new window on your screen displaying

http://home.comcast.net/~mmcm/kbd/SpaceCadet.htmlhttp://sharpkeys.codeplex.com/

First Steps

the lunar phases from today onward. You can type C-x 1 tohide the buer.

Hint

If you enter M-x by mistake, remember you cantype C-g to exit out again.

Emacs has built-in auto completion support so pressing TABwill open a new window and list all the potential candidates.As you type and press TAB, Emacs will automatically narrowthe list of candidates. If your partially-typed match only hasone candidate left when you press TAB, Emacs will completethe whole name for you. You can also just press RET itcompletes like TAB but with the added benet of running thecommand if its the only candidate left.

You may think M-x is a special Emacs command but its actu-ally not. It, too, is written in elisp and bound to a key justlike everything else.

Commands and functions

When I talk about commands, Im talking abouta type of function that is accessible to the user.

For a function to be accessible to a user (notwith-standing the ability to evaluate any expressionin elisp) it must be interactive, which is an Emacsterm for a function that has additional propertiesassociated with it, rendering it usable throughthe execute extended command (M-x) interface andkey bindings.

First Steps

So if youre a package author, you have to chooseif a particular function is accessible to the end-user through the M-x interface. Marking it as in-teractive will make it accessible to end users.

In other words, if its not interactive, you cannotrun it from M-x nor can you bind it to a key.

Universal Arguments

Some commands have alternate states, and to access themyou need to give them a universal argument (also called a pre-x argument.) The universal argument is also known by itskey binding C-u. When you prex another key binding (thisincludes M-x by the way), youre telling Emacs to modify thefunctionality of that command. What happens next will de-pend on the command youre invoking: some have zero, oneor even more universal argument states. If a command hasN states, you simply type C-u up to N times.The universal argument is shorthand for the number . Ifyou type C-u a, Emacs will print aaaa on your screen. If youtype C-u C-u a, Emacs will display characters (because times equals ). Keep in mind that universal arguments ontheir own are totally inactive. When you type them, Emacswill, much like a prex key, wait until you give it a follow-up command and only then will Emacs apply the univer-sal arguments.

Understanding that Emacss command states are merelynumbers is a handy thing to know because you can also passarbitrary numbers to commands. A lot of Emacs hackers

First Steps

would write C-u 10 a to print characters, but theres amuch easier way.

By the way

When you press a key say the a button on yourkeyboard how does Emacs write it on yourscreen? The truth is theres a special commandcalled self-insert-command that, when invoked,will insert the last typed key. Having this com-mand adds symmetry to keys and commands: itmakes your regular keyboard characters behavein exactly the same way as all other commandsin Emacs.

And that also means keyboard characters, andhence self-insert-command, are subject to the ex-act same rules as all other commands. They canbe unbound, rebound, and otherwise modiedby you.

Bound to key binding C-0 to C-9 are the digit arguments. Buttheyre bound to more than just that row of keys to maintainwhat I personally call the tempo of typing but more ontempo below.

Here are the various ways you can pass digit arguments to acommand.

Key Binding Notes

C-u Digit argument C-u C-u Digit argument C-u C-u Digit argument n

First Steps

Key Binding Notes

M-0 to M-9 Digit argument to C-0 to C-9 Digit argument to C-M-0 to C-M-9 Digit argument to C-- Negative argumentM-- Negative argumentC-M-- Negative argument

Note

The negative argument commands are bound tothe minus key (-) even though its hard to makeout from the table above.

Theyre written as C-- instead of C- - because thelatter is an invalid Emacs key: you cannot press amodier key, C-, release it, and then press -. Thatwould just print - on your screen. Its the minusitself that is bound to several modiers. Whitespace matters.

So I mentioned the importance of tempo. Once youre com-fortable with Emacs, youll be ying across the screen, andnot having to take your ngers o the modiers to apply anegative or digit argument will help you do that. Ensuringthe digits and negative arguments are bound to the modiersC-, M-, and C-M-, three very common modier combinations,all but guarantees you wont have to move your ngers fromthe modiers before you follow them up with your intendedcommand.

Here are a few examples of what I mean.

First Steps

M-- M-d kills the previous word before point. WithoutM--, M-d would kill the word immediately followingpoint. The command has synergy with the negativeargument because you can keep your nger on themeta key and press - d.

This combination maintains your tempo.

C-- M-d does exactly the same but it will take you aboutthrice as long to type. You have to press C--, releasethe control key, and then press M- followed by d.

This combination breaks your tempo.

A lot of people never bother working the digit and neg-ative arguments into their workow, but I nd themimmensely useful. Things like changing the casing on aword I just typed are easily done by reversing the directionof a command by giving it a negative argument.

Maintain your tempo and avoid moving your ngers awayfrom the home row.12 Negative arguments add direc-tionality to commands; digits add repetition or changehow a command works.

Discovering and Remembering Keys

If you cant remember the exact command for something,then Emacs can help. Lets say you cant remember how toprint the paragraph character , but you do remember itssomewhere in the C-x 8 key map, then all you have to do is

If you touch type, a skill worth learning above all else.

First Steps

append C-h to any prex key to get a list of all bindings thatbelong to that key map.

Typing C-x 8 C-h will display a computer-generated list ofkeys and their commands. This interface is hyperlinked andpart of Emacss self-documenting help system.

Key Binding

C-x 8 " Prex CommandC-x 8 < C-x 8 > C-x 8 ? C-x 8 C C-x 8 L C-x 8 P C-x 8 R C-x 8 S C-x 8 Y

Above is a subset of the commands you see when you requestthe help page for C-x 8. If you see just a character in the Bind-ing column, that means itll print the character when youtype that key.

However, Emacs will also tell you if there are more prexkeys with further sub-levels; in this case, C-x 8 " has addi-tional keys bound to it.

All these keys, hidden away in the dusty depths of Emacs, allhaphazardly bound to all conceivable permutations of key-board characters, may seem like a strange thing particularlyif you come from modal editors like Vim.

First Steps

The legacy of a particular keyboard used in the early s isevident in the names Super, Hyper, and Meta.

Back then, most Emacs keys were bound to a larger range ofphysical keyboard modiers but when the keyboard maker(and the business that made the machines the keyboards wereplugged into) went bust, Emacs had to change with the times.Instead of undoing the cornerstone of Emacs, the developersshued the keys around and made them work on normal,boring keyboards.

So youre probably thinking its a daunting task indeed tomemorize all those keys but you dont have to. I memo-rize what I use frequently (as we are wont to do with ourhuman brains) and leave the rest for Emacs to remember forme.

Use Emacss help system if you forget a particular keycombination. You can always append C-h to a prexkey.

Conguring Emacs

Tinkering with Emacs is every Emacs hackers favorite pas-time. Go to Emacs meetups or talk to experienced Emacshackers and the conversation will inevitably drift towardssmall changes and hacks theyve made to make their liveseasier.

Its fun (and rewarding) knowing that, if theres an aspectof your editors behavior that you dont like that you cansimply change it indeed, a whole book could be writtenon the subject of changing Emacs.

First Steps

Throughout this book I will make suggestions of things tochange. Where possible I will use the Customize interface in-stead of the typical approach of suggesting elisp snippets.

If you want to change Emacs, you have two choices:

Use the Customize interface as its built-in and designedto be user friendly. I say that, but a lot of people nd itcumbersome and hard to use. I think thats a bit unfair:its utilitarian and has to support a lot of arbitrary waysof conguring fairly complicated features.

Not everything is supported by Customize. Since youneed to write elisp to change variables, and because ofthe data-as-code paradigm uses, you will nd thatCustomize can write elisp that its been shown how towrite, and then only for specic options. That makesit a virtual impossibility to generalize an interfaceacross all of Emacss many, many settings. But mostof Emacss built-in packages support the Customizeinterface and a lot of third-party packages do too.

I would strongly recommend you use the Customize in-terface, where possible, until youre comfortable writ-ing elisp.

Write elisp to alter what you want to customize. This is themost powerful option but also the most complicated.Youll have to learn elisp (its not too hard, and writingit is usually a lot of fun) to do this, but I think, in thelong run, its worth doing.

I still use the Customize interface myself when Ichange font faces. There are hundreds of font faces

First Steps

in Emacs; everything from font lock faces (syntaxhighlighting) to the color of the modeline, the fontsto use for the info manual, and more.

The Customize Interface

The Customize interface is divided into groups and sub groups.Each group typically represents one package, mode, or pieceof functionality. The top-level group is calledEmacs and con-tains, as you would expect, all other groups.

To access the customize interface, type M-x customize. Abuer called *Customize Group: Emacs* should appear witha list of groups. This is one part of Emacs where using amouse can be benecial; the interface has buttons, hyper-links and edit boxes much like a browser would. Clickaround explore the interface, and marvel at just howmuch stu there is to congure! And thats just the thingsexposed to the Customize interface.

hint

If youre using Emacs . or later, you can use theSearch bar at the top of the Customize interfaceto search for things by name.

First Steps

The Customize interface is rather byzantine but once youunderstand how it works, its quite easy to use. The gureabove shows one face: font-lock-string-face. Thats theactual elisp variable name for the face; the pretty-printedname is Font Lock String Face and what youll see in thegure above. To the immediate left is an arrow its tinybut itll hide/show each face. On a Terminal, its replacedwith the arguably more legible texts Hide or Show.As a quick aside, the Customize interface is made up oftwo things: faces and options. Options are a catch-all term forthings you can Customize that arent faces.

The font-lock-string-face governs the face for strings and what a string is depends on the mode in which it isused. For most programming major modes, itll be for actualliteral strings in the source code, but mode authors are free

First Steps

to use the font faces for whatever they please. Having saidthat, most adhere to the naming standard for each face.

My personal foreground face color is OrangeRed. But theresnothing stopping me from adding additional attributes asthe gure above shows.

First Steps

Indeed, Emacss renderer is quite advanced. In the exampleabove, Ive changed font-lock-string-face so it uses HoeerText and swash small caps.

Supported colors

If youre using Emacs in a , you are limitedonly by the color depth of the display andyou are free to pick any color from the RGBcolor space. I use named colors, and to seea list of supported names you can type M-xlist-colors-display. If youre on a Terminal,you will be shown the colors supported by yourTerminal usually only or .

Making the changes in the Customize isnt enough. Youhave to apply the changes and optionally save them also. Ifyou dont save them, the changes will not persist betweenEmacs sessions. Pressing the aptly named Apply and Applyand Save do just that. The Revert button is similar but hasa few more options. You only need Revert This Sessions Cus-tomizations if youre unhappy with the changes you have ap-plied. Keep in mind it will only revert the options you have inthe current buer not all the customizations made globally.

First Steps

Always remember that you can revert your changes untilyou save. After that, you have to manually go through andundo or use the Revert buttons Erase Customizations op-tion.

All Customizations are stored in your init le by default (orpossibly a separate custom le) and like the rest of Emacs thechanges are stored as elisp code, making it possible for youto go back and manually change the elisp.

Instead of navigating through the tree of groups, you canuse one of several shortcut commands:

M-x customize displays the Customize interface and all thegroups.

M-x customize-browse opens a tree group browser. Muchlike the regular Customize interface but without thegroup descriptions.

M-x customize-customized customizes options and faces thatyou have changed but not saved. Useful if you want totweak things.

M-x customize-changed displays all options changed since aparticular Emacs version. Good way to discover newfeatures and options.

M-x customize-face prompts for the name of a face toCustomize. I recommend you put your point onthe face you want to change. Itll ll in the nameautomatically.

M-x customize-group prompts for a group name (e.g., python)to Customize.

First Steps

M-x customize-mode customizes the major mode of your cur-rent buer. You should do this for every major modeyou use. Its a quick way to change things and gain anoverview of what your major mode can do.

M-x customize-saved Displays all your saved options andfaces. Extremely handy if you want to track downand disable errant changes.

M-x customize-themes Shows a list of installed themes youcan switch to.

I encourage you to use the Customize interface to congureEmacs. It only has a subset of things you can (or want) tochange, but its enough to get you started on the road topersonalizing Emacs.

As you continue to use and personalize Emacs you may even-tually reach a point where your init le is unmanageable.When that happens its common to split up your changesinto groups of related changes. However, this is a low prior-ity task until youre comfortable (and your init le splittingat the seams) with Emacs.

Evaluating Elisp Code

Frequently, you will nd or write snippets of elisp code onthe Internet and youll want to evaluate it closing andrestarting Emacs every time is a chore.

There are a number of dierent ways of doing this and I haveonly shown a few of the dierent methods available to you.

First Steps

You can read Evaluating Elisp in Emacs13 for a thorough studyof the subject.

Restarting Emacs is the simplest way, which I recommendif you have broken something in Emacs or if you wantto be sure things work in a fresh environment.

M-x eval-buffer will evaluate the entire buer youre in.This is what I use to evaluate something.

M-x eval-region evaluates just the region that you havemarked.

important

You must remember that not all things will be re-evaluated even if you tell Emacs to. This is one an-noying implementation detail that confuses peo-ple. Some things, like defvar and defcustom forms,are only set once. So, if you evaluate the buer,change a defvars default value, then re-evaluateit, itwont apply the changes made to defvar. Theonly way to force the change is to press C-M-xwith your point in each defvar or defcustom form.

If you dont know exactly what I mean by all ofthis, dont worry, you can just restart Emacs ifyou see any of those two forms in your snippet.

Naturally, this is just scratching the surface in using Emacs toevaluate your elisp code. You shouldnt need to know much

http://www.masteringemacs.org/article/evaluating-elisp-emacs

First Steps

more than this to deal with the odd bits of code you see andwant to try out. Dont be afraid to explore Emacss capabil-ities this way; read Emacss own Introduction to Elisp man-ual.

The Package Manager

Since version , Emacs has shipped with a package man-ager that seamlessly displays and installs packages from cen-tralized repositories. I credit this change, alongside sites likeGithub, with rejuvenating Emacss rd-party ecosystem and,in turn, Emacs itself.

Its not all roses though: there is no one repository you canuse for all your needs. Theres the ocial Emacs pack-age repository, 14, but its content is rather sparse, as youhave to physically sign over your copyrights to the to sub-mit to it, and most people cant or wont do that. Therefore,almost all packages appear on Melpa and Marmalade. Thank-fully, the package manager will merge all the dierent list-ings into one.

As the repositories are privately owned by volunteers, theymay go down temporarily or permanently so I wouldcheck the Emacs Wiki15 for a current list of repositories.

For now though, you can add this to your init le. It in-cludes the ocial repository and two unocial, community-maintained repositories.

(setq package-archives

The Emacs Lisp Package Archivehttp://www.emacswiki.org/emacs-en/ELPA

First Steps

'(("gnu" . "http://elpa.gnu.org/packages/")("marmalade" . "http://marmalade-repo.org/packages/")("melpa" . "http://melpa.milkbox.net/packages/")))

Now is a good time to make Emacs evaluate it. Execute thecommand M-x eval-buffer with your init le as the currentbuer.

Next, type M-x package-list-packages and Emacs should re-trieve the package listings from all three repositories above.When its done, a new buer will appear listing all the pack-ages. Like a lot of ancillary buers in Emacs, this one is alsohyperlinked. Have a browse you can one-click install thepackages you care about from the detail page of a package.

Hint

If you know the name of the package, youcan use the shortcut M-x package-install andenter the name in the minibuer. And likemost minibuer prompts, this one also has TABcompletion.

Color Themes

If you dislike the default color scheme in Emacs then good news, you can use a color theme. Type M-xcustomize-themes to see a list of your installed color themes.There are more available for free from Emacss packagemanager or sites like Github.

To install a theme with the package manager, open thepackage manager (M-x package-list-packages) and go look

First Steps

for themes; most will have the sux -theme, and they actand install like normal packages. Once youve installed thethemes you need, use the M-x customize-themes interface totry them out. You can override specic colors you dontlike by using the regular Customize interface described inThe Customize Interface. Changes made in the Customizeinterface take precedence over the themes.

I should mention that you can have multiple themes activeat the same time, so make sure you are aware of this.

Getting Help

As I mentioned earlier when I talked about keys, Emacs is asophisticated self-documenting editor. Every facet of Emacsis searchable or describable. Learning how to do this is abso-lutely essential to mastering Emacs. The utility of knowing howto nd the answers to questions is something I cannot over-state enough. I use Emacss self-documenting functionalityall the time; to jog my memory, or to seek answers to ques-tions I dont know.

I still havent talked about the actual core of Emacs yet(movement, editing, and so forth) because, although thatsobviously critical to mastering Emacs, they are specic skillsthat you could, with patience, acquire by using Emacssself-documenting help systems.

Knowing how to get help is critical because:

Emacs knows best Your Emacs conguration will dif-fer sometimes just a little bit, other times a lot

First Steps

from other peoples Emacs congurations. Asking aquestion on the Internet will only give you generalanswers. If you rebind keys, only your Emacs knowswhat the keys are.

You will discover more of Emacs I have stumbled uponmore cool features than I can count simply by explor-ing maybe a time saving command hidden away ina major mode, or a variable that changes the behaviorof a command I use frequently.

A lot of third-party packages may not have an adequateuser manual, forcing you to read the source or investi-gate the commands and variables exposed by the pack-age.

It will help you solve problems I help people with Emacsquestions all the time, but I dont know everything what I do know is where to look and how to read thedocumentation.

It gives you condence Not knowing how to do some-thing in Emacs is normal but also confusing. Butbeing able to say that oh, I dont know how to dothis but I do know where I can look for help yourcondence in Emacs will go up in step with yourknowledge.

Emacss help system is roughly divided into three parts andknowing which one you need and when will save you time.

First Steps

The Info Manual

Emacss own manuals (and indeed, all manuals in the ecosystem) are written in TeXinfo. If you have ever used thecommand line tool info, you will have interacted with theTeXinfo hypertext viewer. Emacs, obviously, has its owninfo viewer. Emacss info manual contains more than justtopics relating to Emacs. By default, the info browser willindex all the other info manuals installed on your system things like the coreutils manuals will also be present.

A lot of people dislike info and Im not sure why. It works inmuch the same way as a web browser, though the key bind-ings do dier.

To access Emacss info reader type M-x info or press C-h i.info, the documentation browser, will appear and you arefree to use your mouse to click on the hyperlinks, or usethis table of keyboard shortcuts to navigate:

Key Purpose

[ and ] Previous / next nodel and r Go back / forward in historyn and p Previous / next sibling nodeu Goes up one level to a parent nodeSPC Scroll one screen at a timeTAB Cycles through cross-references and linksRET Opens the active linkm Prompts for a menu item name and opens itq Closes the info browser

Because info manuals have hierarchies, in much the same

First Steps

way this and most other books do, youll want to use [ and] to navigate if youre reading an info manual end-to-end.Thats equivalent to reading a book starting from a chapter,moving through all the sub-chapters, sub-sub-chapters, andso forth, in the order they were laid out.

Everyday reading

For everyday reading, you want SPC for brows-ing and reading as it does what you want. Itthumbs through a page until it reaches the end.Then, it either picks the next sub node or thenext chapter. For browsing, use [ and ] to cycleback and forth through nodes.

If, instead, you want to jump to the next or previous siblingnode you should use n and p. To go back or forward in his-tory (much like a browser) use l and r.

The key u goes up one level to the parent; TAB cycles throughthe hyperlinks, and RET opens them.

Most info manuals are also published in versions on-line, so why use Emacss own reader? For one, you can useEmacss universal bookmark system (and more on that later.)You can bookmark almost everything in Emacs: info pages,les, directories, and more. The other advantage is that itsin Emacs, so keeping the info manual in a split window nextto you is particularly useful if youre reading Emacss excel-lent An Introduction to Programming in Emacs Lisp and writingcode alongside it.

If you want to read up on a specic Emacs functionality, youhave to open the Emacs manual rst. To do this, type C-h i

First Steps

followed by m. When prompted for a menu item, type Emacsfor the Emacs manual or Emacs Lisp Intro for the introduc-tion to elisp. As always, there is TAB completion. You can alsobrowse the master list of manuals and nd the one you wantto read.

You can look up the documentation for a command by typ-ing C-h F and at the prompt enter the name of a command.Emacs will jump to the correct place in the info manualwhere the command is described.

Apropos

Emacs has an extensive apropos system that works in muchthe same way as apropos does on the command line. Theapropos system is especially useful if youre not entirelysure what youre looking for. There is a variety of nichecommands that only search particular aspects of Emacssself-documenting internals.

Apropos is a useful tool to have in your toolbox. It shinesbecause you can narrow what youre looking for to a par-ticular area. If youre looking for a variable, you can use theapropos system that searches variables; if you are looking forcommands, you can search by command. And all of apropossupports regular expressions.

The most common one, bound to C-h a, is M-x apropos-command.apropos-command shows all commands (and just the commands,not functions) that match a given pattern.

For instance, you might be on the hunt for commands thatwork on words (but more on what a word actually meansin What Constitutes a Word?) so entering C-h a followed by

First Steps

-word$, is a good place to start. That will list all commandsthat end with -word.Heres a subset of the output you would see if you ran thatcommand:

Command Key Purpose

ispell-word M-$ Check spelling of word underor before the cursor.kill-word M-d Kill characters forward until

encountering the end of a word.left-word C- Move point N words to the left

(to the right if N is negative.)mark-word M-@ Set mark words away

from point.

As you can see, you get the name of the command, the keysbound to it (if any) and the purpose. Emacs has certain nam-ing conventions and once youre familiar with Emacs, youwill see certain patterns emerge. For instance, its commonto postx a command with the syntactic unit or context it op-erates on: -word for words, -window for windows, and so on.

Hint

Apropos can sort results by relevancy. To enablethis, add:

(setq apropos-sort-by-scores t)

to your init le.

First Steps

Theres a wide range of apropos commands you can use toquery Emacs. apropos-command is perhaps the most useful to abeginner. And itll let you search by pattern, which is greatif you only remember part of a commands name but not allof it. Its also a fantastic way to accidentally discover newfeatures in Emacs. Giving apropos-command the .+ pattern (tomatch everything) yields approximately , commandsthat Emacs knows about this amount however will varygreatly depending on the number of packages you haveloaded and the features in Emacs you have activated.

Emacs has a range of specialist apropos commands that youmight nd more suitable.

M-x apropos The thermonuclear option. This commandwill display all symbols that match a given pattern.Useful if youre trying to track down both variables,commands and functions relating to a pattern.

M-x apropos-command or C-h a As I explained above, this com-mand will list only the commands.

M-x apropos-documentation or C-h d Searches just the doc-umentation. In Emacs parlance, that means the docstring (documentation string) with which you cansupply symbols. Occasionally useful.

M-x apropos-library Lists all variables and functions denedin a library. This command can be useful if youre in-vestigating a new mode or package as it lists the all thefunctions and variables dened in it.

M-x apropos-user-option Shows user options availablethrough the Customize interface. This is one way to

First Steps

get the symbol names of Customize options, butif youre looking for ways to search the Customizeinterface, you are better o using the Search box inthe Customize interface as it lets you customize thematches as well. I never use it.

M-x apropos-value Searches all symbols with a particularvalue. If youre looking for a variable that holds aparticular value, this command may be of use to you.A potential use is if I know the value of a variable butnot the name or where its dened.

If youre unsure of what you are looking for maybe youonly have part of a name, or you just remember a bit of thedocumentation then apropos is a tool that can help you.I nd apropos indispensable; its a great way to list all thecommands that match certain patterns and an even greaterway to discover new commands.

The Describe System

What captures the beauty of Emacss self-documenting na-ture is the describe system of commands. If you know whatyoure looking for, then describe will explain what it is. Ev-ery facet of Emacs be it code written in elisp or the corelayer written is C is accessible and indexed through the de-scribe system. From keys, to commands, character sets, cod-ing systems, fonts, faces, modes, syntax tables and more its all there, neatly categorized.

The describe system is not static. Every time you query aparticular part of Emacs, it will fetch the required details

First Steps

through an internal introspection layer which itself queriesEmacss own internal data structures. Both the introspec-tion layer and internal data structures are queryable byyou through elisp. There are no secrets in Emacs sure, the documented layer is the recommended wayof accessing Emacss own internal state, but unlike othereditors and s you are not beholden to the package authoror Emacs maintainers. I think this embodiment of openness,beautifully captured by the describe system, is one of thebest features of Emacs.

You can nd the most important describe keys bound to theC-h prex key16; theres more, a lot more actually, but I thinkmost of them are of limited utility to all but elisp writers.

I use the describe system constantly. In writing this book, Ihave used both the info manual and apropos extensively, butthe describe system is what I use to double check that ev-erything I have written is correct. If you ever nd yourselfwondering what a symbol in Emacs does (be it a function, acommand, a variable or a mode) then describe will tell you.

The only slight downside to the doc string is that it assumes atechnical audience: the info manual generally does not. Itsnot all bad, you dont have to be an elisp expert to make senseof the description but it will take a bit of time to familiarizeyourself with the terminology used in the doc strings.

Remember, the describe system describes a living system your personalized Emacs.

As I mentioned in the Keys chapter, you can follow up a prex keywith C-h to list all the known bindings.

First Steps

You need to memorize four describe keys as they are themost important ones for day-to-day Emacs use.

M-x describe-mode or C-h m Displays the documentation forthe major mode (and any minor modes also enabled)along with any keybindings introduced by said modes.The describe command looks at your current buer.

This command should be your rst port of call whenyoure using a new major mode. You will discover a lotof Emacss functionality this way and it is absolutelyimperative that you use this command.

What it doesnt do is list mode-specic commands thatare not bound to any key: they are simply not shown.

M-x describe-function or C-h f Describes a function. An-other command on the critical path to masteringEmacs. Knowing what something does in Emacs (andhow to look it up) is useful but so is being able tojump to the part of the code where its declared.

Describing a function will give you the elisp functionsignature, the keys (if any) bound to it, a hyperlink towhere its declared, and a doc string.

If the function is a command, it will say it is interactive.

M-x describe-variable or C-h v Describes a variable. Likedescribe-function, this command is also important,but perhaps less so as changing variables is not alwayseasy to do for a beginner. Nevertheless, being able toread up on what a variable does is.

First Steps

M-x describe-key or C-h k Describes what a key bindingdoes. Of all the commands, this is one of the most use-ful ones to memorize, and like M-x describe-functionits a command you will use frequently. If youreunsure what a key binding does, simply enter thedescribe-key interface and re-type the key andEmacs will tell you what it does.

Its worth remembering that some keys come frommajor and minor modes and are not global. Therefore,you may get a dierent answer depending on thebuer in which you type the command.

Emacs does have a lot more describe commands but theyrenowhere near as practical or useful for day-to-day use.Knowing what you know now about the naming of de-scribe commands and how to nd commands by patterns, itshould be a trivial17 exercise to list all of them.

Hint: apropos-command is a good place to start.

Chapter

The Theory of Movement

Escape Meta Alt Control Shift

info.gnu.emacs

Getting around, and getting around eciently, is as impor-tant as knowing how to edit text quickly and eciently.But movement in Emacs is more than characters in abuer; theres a host of supplementary skills that make upnavigation, like understanding Emacss rather complicatedwindowing system.

I wouldnt expect you to remember and apply everythingyou learn here right away. Ive laid things out so you canstart at the beginning and work your way through, pickingup bits and pieces as you read. The most important part, asIve stressed many times, is to give it time and practice take a moment in your day-to-day life to ask yourself iftheres a better way of solving a problem with which youare faced.

The Theory of Movement

Movement in Emacs is local, regional or global. Local move-ment is what you do when you edit and move around textnear to the point. A syntactic unit a semi-formal term forcommands that operate on a group of characters is a char-acter, word, line, sentence, paragraph, balanced expression,and so forth. Regional and local movement are similar butregional movement involves whole functions or class de-nitions, if you are writing code; or chapters and such con-structs, if you are writing prose. Global movement is any-thing that takes you from one buer to another, or fromone window to the next.

The rst thing a beginner sees is Emacss penchant for creat-ing windows: when you view a help le, when you compilea le, or when you open a shell. If you have never used atiling window manager (for that is exactly what Emacs is),the idea of splitting and deleting windows may seem strange

in other editors you may use split panes but you almostnever change it to suit the task at hand.

In Emacs, windows are transient; they come and go as youneed them. You can save your window conguration (andthere are several ways of doing this) but they were nevermeant to be immutable, like so many editors set once andthen never changed again. You have to get used t