Chapter 1. Emacs Basics

Some of you out there are probably dying to get your hands on the keyboard and start typing. We won’t try to stop you; turn to the section called “Starting Emacs” and you can go ahead. But do read the beginning of this chapter later when you’re ready for a break. Emacs is much easier to learn if you understand some of the basic concepts involved, which we discuss in the following introduction.

Introducing Emacs!

GNU Emacs is one of the most commonly used text editors in the world today. Many users prefer Emacs to vi (Unix’s standard editor) or to other GUI text editors. Why is Emacs so popular? It isn’t the newest tool, and it’s certainly not the prettiest. But it may well be the most useful tool you’ll ever learn. We want to present what you need to know about Emacs to do useful work, in a way that lets you use it effectively. This book is a guide for Emacs users; it tries to satisfy the needs of many readers, ranging from casual users to programmers.

Our approach therefore isn’t to tell you absolutely everything that Emacs does. It has many features and commands that this book doesn’t describe. We don’t think that’s a problem; Emacs has a comprehensive online help facility that helps you figure out what these are. We focus our attention on describing how to get useful work done. After covering basic editing in the first three chapters, we describe how to use Emacs as a comprehensive working environment: how to boost productivity with multiple buffers and windows, how to give commands without leaving the editor, how to take advantage of special editing modes, how to use Emacs for editing special types of files (source files for various programming languages), and so on. We cover the most important commands and the most important editing modes. However, you should always keep one principle in mind: Emacs does many things well, but it isn’t important for that reason. Emacs is important because of the integration of different things you need to do.

What does integration mean? A simple example will help. Assume that someone sends you a mail message describing a special command for accessing a new printer. You can fire up an Emacs shell, paste the command into Emacs, and execute it directly. If it works, you can edit your startup file to create an alias for the command. You can do all this without leaving the editor and without having to retype the command once. That’s why Emacs is so powerful. It’s more than just an editor; it’s a complete environment that can change the way you work.

An initial word of advice, too. Many people think that Emacs is an extremely difficult editor to learn. We don’t see why. Admittedly, it has a lot of features, and you probably will never use all of them. But any editor, no matter how simple or complex, has the same basic functions. If you can learn one, you can learn any of them. We’ll give you the standard mnemonic devices that will help you remember commands (like "C-p means previous line”), but we really don’t think even these are necessary. They get you over an initial hump in the learning process but don’t make much difference in the long run. Learning to use an editor is basically a matter of learning finger habits: learning where to put your fingers to move to the previous line. If you experiment with Emacs and try typing a few of our examples, you’ll quickly acquire these finger habits. And after you’ve acquired these habits, you’ll never forget, any more than you’ll forget how to ride a bicycle. After using Emacs for a day or two, we never had to think, "C-p means previous line.” Our fingers just knew where to go. Once you’re at this point, you’re home. You can become creative with Emacs and start thinking about how to put its features to work for you. Emacs has extensive menus, but we still recommend learning the key bindings for commonly used commands. Good finger habits can make you an incredibly fast typist, and reaching from keyboard to mouse only slows you down.

The finger-habits approach also implies a different way of reading this book. Intellectually, it’s possible to absorb a lot from one reading, but you can form only a few new habits each day. (Unless, of course, they’re bad habits.) Chapter 2 covers most of the basic editing techniques you’ll use. You may need to read it several times, with a slightly different focus each time. For example, Emacs gives you many different ways to move forward: you can move forward one character, one word, one line, one sentence, one paragraph, one page, and so on. All of these techniques are covered in Chapter 2. Start by learning how to move forward and backward, then gradually add more complex commands. Similarly, Emacs provides many different techniques for searching through a file, covered in Chapter 3. Don’t feel obliged to learn them all at once; pick something, practice it, and move on to the next topic. No one will complain if you have to work through the first three chapters of our book several times before you’re comfortable. Time spent developing good habits is time well spent.

Understanding Files and Buffers

You don’t really edit files with Emacs. Instead, Emacs copies the contents of a file into a temporary buffer and you edit that. The file on disk doesn’t change until you save the buffer. Like files, Emacs buffers have names. The name of a buffer is usually the same as the name of the file that you’re editing. There are a few exceptions. Some buffers don’t have associated files—for example, *scratch* is just a temporary practice buffer, like a scratchpad; the help facility displays help messages in a buffer named *Help*, which also isn’t connected to a file.

A Word About Modes

Emacs achieves some of its famed versatility by having various editing modes in which it behaves slightly differently. The word mode may sound technical, but what it really means is that Emacs becomes sensitive to the task at hand. When you’re writing, you often want features like word wrap so that you don’t have to press Enter at the end of every line. When you’re programming, the code must be formatted correctly depending on the language. For writing, there’s text mode; for programming, there are modes for different languages, including C, Java, and Perl. Modes, then, allow Emacs to be the kind of editor you want for different tasks.

Text mode and Java mode are major modes. A buffer can be in only one major mode at a time; to exit a major mode, you have to enter another one. Table 1-1 lists some of the major modes, what they do, and where they’re covered in this book.

Table 1-1. Major modes

Mode

Function

Fundamental mode

The default mode (Chapter 6)

Text mode

For writing text (Chapter 2)

View mode

For viewing files but not editing (Chapter 4)

Shell mode

For running a shell within Emacs (Chapter 5)

Outline mode

For writing outlines (Chapter 7)

Indented text mode

For indenting text automatically (Chapter 7)

Paragraph indent text mode

For indenting the first line of each paragraph (Chapter 7)

Picture mode

For creating ASCII drawings using the keyboard (Chapter 7)

HTML mode

For writing HTML (Chapter 8)

SGML mode

For writing SGML and XML (Chapter 8)

LaTeX mode

For formatting files for TEX and LATEX (Chapter 8)

Compilation mode

For compiling programs (Chapter 9)

cc mode

For writing C, C++, and Java programs (Chapter 9)

Java mode

For writing Java programs (Chapter 9)

Perl mode and Cperl mode

For writing Perl programs (Chapter 9)

SQL mode

For interacting with databases using SQL (Chapter 9)

Emacs Lisp mode

For writing Emacs Lisp functions (Chapter 9 and Chapter 11)

Lisp mode

For writing Lisp programs (Chapter 9 and Chapter 11)

Lisp interaction mode

For writing and evaluating Lisp expressions (Chapter 9 andChapter 11)

Whenever you edit a file, Emacs attempts to put you into the correct major mode for what you’re going to edit. If you edit a file that ends in .c, it puts you into cc mode. If you edit a file that ends in .el, it puts you in Lisp mode. Sometimes it looks at the contents of the file rather than just its name. If you edit a file formatted for TEX, Emacs puts you in LaTeX mode. If it cannot tell what mode you should be in, it puts you in fundamental mode, the most general of all. Because Emacs is extensible, add-in modes are also available; we talk about some in this book, though we do not list them in Table 1-1.

In addition to major modes there are also minor modes. These define a particular aspect of Emacs’s behavior and can be turned on and off within a major mode. For example, auto-fill mode means that Emacs should do word wrap; when you type a long line, it should automatically make an appropriate line break. Table 1-2 lists some minor modes, what they do, and where they’re covered in this book.

Table 1-2. Minor modes

Mode

Function

Auto-fill mode

Enables word wrap (Chapter 2).

Overwrite mode

Replaces characters as you type instead of inserting them (Chapter 2).

Auto-save mode

Saves your file automatically every so often in a special auto-save file (Chapter 2).

Isearch mode

For searching (Chapter 3).

Flyspell mode

For flyspell spell-checker (Chapter 3).

Flyspell prog mode

For spell-checking programs with flyspell (Chapter 3).

Abbrev mode

Allows you to use word abbreviations (Chapter 3).

Paragraph indent text mode

For indenting the first line of each paragraph (Chapter 7).

Refill mode

A mode in which Emacs attempts to fill paragraphs as you edit them (a bit experimental; mentioned in Chapter 2).

Artist mode

For creating ASCII drawings using the mouse (Chapter 7).

Outline mode

For writing outlines (Chapter 7).

SGML name entity mode

For inserting special characters in HTML, SGML, and XML documents (Chapter 8).

ISO accents mode

For inserting accented characters in text files.

Font lock mode

For highlighting text in colors and fonts to improve readability (separating, for example, comments from code visually) (Chapter 9).

Compilation mode

For compiling programs (Chapter 9).

Enriched mode

For saving text attributes (Chapter 10).

VC mode

For using various version control systems under Emacs (Chapter 12).

Info mode

A mode for reading Emacs’s own documentation (Chapter 14).

You may have noticed that several modes, including paragraph indent text mode, outline mode, and compilation mode, are both major and minor modes. Each can be used alone—as a major mode—or with another major mode as a minor mode.

There are many other modes that we won’t discuss, including modes for some obscure but interesting programming languages (like Modula-2). There are also some other modes that Emacs uses itself, like Dired mode for the directory editing feature (described in Chapter 5).

In addition, if you’re good at Lisp programming, you can add your own modes. Emacs is almost infinitely extensible.

Starting Emacs

To start Emacs, simply click on the Emacs icon or type emacs on the command line and press Enter.[1]

Click on the Emacs icon or, from the command line, type: emacs Enter

image with no caption

Starting Emacs.

You’ll see a short message describing a few important menu items and the version of Emacs that you’re running. It may appear as a graphical splash screen (like the one shown here) or a text splash screen. This message disappears as soon as you type the first character. Emacs then puts you in an (almost) empty buffer called *scratch*, an ideal place for you to experiment.

About the Emacs Display

When you enter Emacs, you see a large workspace near the top of the window where you do your editing. (See Figure 1-1.)

Understanding the Emacs display
Figure 1-1. Understanding the Emacs display

A cursor marks your position. The cursor is also called point, particularly among people who are more familiar with Emacs and in the online help system; therefore, it’s useful to remember this term.

You don’t have to do anything special before you start typing. As long as you type alphanumeric characters and punctuation, Emacs inserts them into your buffer. The cursor indicates where Emacs inserts the new characters; it moves as you type. Unlike many editors (particularly vi), Emacs does not have separate modes for inserting text and giving commands. Try typing something right now, and you’ll begin to see how easy Emacs is to use. (If you get stuck for any reason, just press C-g.)

The Toolbar

The toolbar is a new feature in Emacs 21. Its basic icons and their functions are listed in Table 1-3. Note that the toolbar is context sensitive; in some modes, such as the Info mode for reading the Emacs manual, the toolbar changes to provide browsing help. We’ll discuss those icons when we cover the relevant modes.

Table 1-3. Icons on the Emacs toolbar

Icon

Function

Where to learn more

image with no caption

Find a file or create a new file (supplying the filename).

This chapter

image with no caption

Start the directory editor so you can manipulate files and folder.

Chapter 5

image with no caption

Kill the current buffer.

Chapter 4

image with no caption

Save current buffer in its associated file.

This chapter

image with no caption

Save current buffer as a different file.

This chapter

image with no caption

Undo.

Chapter 2

image with no caption

Cut text that comprises the current region.

Chapter 2

image with no caption

Copy text in current region.

Chapter 2

image with no caption

Paste cut or copied text.

Chapter 2

image with no caption

Search for a string.

Chapter 3

image with no caption

Print page (with headings).

Chapter 5

image with no caption

Customize using interactive interface.

Chapter 10

image with no caption

Start online help system.

Chapter 14

If you don’t like the toolbar, you can hide it using a menu option (Options Show/Hide Toolbar), and choosing Options Save Options. For more information, see Section 2.7 at the end of Chapter 2.

The Menus

The menu bar menu lists the options File, Edit, Options, Buffers, Tools, and Help; you can explore them to see what options are available.

In addition to navigating the menus using the mouse, Emacs now offers pop-up menus. In the Emacs window, hold down Ctrl and click the right mouse button to pop up the Edit menu.[2]

You can access menus without a mouse using the keyboard. In this case, using keyboard commands is much more efficient than menus, but for completeness, we’ll show you how to use the text-based menus. (If you prefer to use the mouse with Emacs but have access only to a text interface, see Chapter 13 to learn how to download and install a version of Emacs that runs graphically on Unix, Linux, Mac OS X, or Windows.)

If your mouse does not work with the menus, press F10 or M-` (a back quote, the single open quotation mark, located above the Tab key in the upper-left corner of many keyboards) to access them.

Press: F10

image with no caption

Using text-based menus (Emacs 21.2 on Mac OS X Terminal application).

You can select text-based menu options in three ways:

  • You can press Enter to select the default option that appears in the minibuffer. If you want a different one, press the up or down arrow key until the option you want appears and press Enter.

  • You can type the letter preceding the option in the *Completions* buffer. For example, type f to choose File.

  • You can press PgUp to move to the *Completions* buffer, then use the arrow keys to move to the option you want. Press Enter. (On Mac OS X, press Shift-PgUp instead.)

After you select a menu option, choices for that menu appear. Repeat the process until you find the option you’re looking for.

The Mode Line

Just above the bottom of the window (on the second-to-last line), Emacs prints a lot of information about what it’s doing. This line is called the mode line. At the beginning of the mode line, you may see some information about the coding system that Emacs is using for the file; usually you’ll see just --:, indicating that there is no unusual encoding scheme in place. Near the left edge of the mode line, you may see two asterisks (**). These asterisks indicate that you’ve modified whatever you’re editing. If you haven’t made any changes, the asterisks won’t be there. Next, Emacs prints the name of the buffer you are editing (*scratch*). Following this, Emacs shows where you are in the buffer—your position relative to the rest of the file and what line you are on (L5 for line 5 in Figure 1-1). If you’re at the beginning of the file, Emacs prints the word Top; if you’re at the end, it prints Bot; if you’re in the middle, it shows you a percentage (for example, 50% means you’re looking at the midpoint); and if the entire file is visible, Emacs prints the word All. In parentheses following this is the editing mode or modes you are in, in this case Lisp Interaction is the major mode (no minor modes are active). The scrollbar on the side of the window also indicates your position in the file.[3]

You will often work with several buffers simultaneously. In this case, each buffer has its own mode line, and when you switch buffers, the mode line reflects the state of the current buffer. Don’t worry about this for now; just remember that every buffer has a mode line to describe it.

The Minibuffer

Below the mode line is the minibuffer. This is the area where Emacs echoes the commands you enter and where you specify filenames for Emacs to find, values for search and replace, and so on. It is also where Emacs displays error messages. If you find yourself stuck in the minibuffer, press C-g to get out again.

Emacs Commands

You’re about to start learning some Emacs commands, so let’s discuss them a bit first. How do you give commands? Each command has a formal name, which (if you’re fastidious) is the name of a Lisp routine. Some command names are quite long; you usually wouldn’t want to type the whole thing. As a result, we need some way to abbreviate commands.

Emacs ties a command name to a short sequence of keystrokes. This tying of commands to keystrokes is known as binding. Even things you don’t normally think about as commands, such as inserting the characters that you type, are handled through the binding mechanism. Keys like “A” are bound to the Emacs command self-insert-command, which inserts them into the buffer you are editing.[4] Most actions that you would normally think of as editor commands are bound to keystroke sequences starting with Ctrl or Meta. Emacs also binds some commands to mouse clicks (alone or modified by Shift or Ctrl) and to options on menus.

The authors of Emacs try to bind the most frequently used commands to the key sequences that are the easiest to reach. Here are the varieties of key sequences you’ll encounter:

  • The most commonly used commands (such as cursor movement commands) are bound to C- n (where n is any character). To press C- n, press and hold the Ctrl key and press n, then release both keys.

  • Slightly less commonly used commands are bound to M- n. To press M- n, press and hold the Meta key (usually next to the space bar), then press n.

  • Other commonly used commands are bound to C-x something (C-x followed by something else—one or more characters or another control sequence). Among other types of commands, file manipulation commands, like the ones you are about to learn, are generally bound to C-x something.

  • Some specialized commands are bound to C-c something. These commands often relate to one of the more specialized modes, such as Java mode or HTML mode. You won’t encounter them until later in this book.

  • This list still doesn’t take care of all the possibilities. You can get at the remaining commands by typing M-x long-command-name Enter. (This works for any command really, but the keystrokes are usually easier to learn.)

You can define your own key bindings, too, and you should do so if you find yourself using the long form of a command all the time. More on this topic in Chapter 10.

You can also access common commands through menus, but for maximum productivity, we recommend you learn the keystrokes, often given in parentheses following the menu option.

Opening a File

You can open a file by specifying the filename when you start Emacs from the command line or by typing C-x C-f (the long command name is find-file).

The paper icon on the toolbar also runs this command. In some applications, a similar icon simply creates a new, unnamed file (e.g., Document1 in Word). Emacs expects you to provide a filename, as we’ll see in a moment.

Press: C-x C-f

image with no caption

Emacs prompts you for a filename.

To press C-x C-f, hold down Ctrl, press x and then press f. Now release Ctrl.

After you press C-x C-f, Emacs uses the minibuffer to ask you for the filename. Whenever Emacs wants input from you, it puts the cursor in the minibuffer. When you’re done typing in the minibuffer, press Enter.

Type: newfile Enter

image with no caption

Emacs starts another buffer with the new file in it.

What if you try to read the same file twice? Instead of creating a new buffer, Emacs just moves you to the buffer the file is in.

You can also open a file in Emacs by dragging and dropping it on an Emacs window or on the Emacs icon.

Now is a good time to try typing if you haven’t already done so. You may find yourself wanting to learn more about cursor movement and editing; that’s fine. Feel free to skim the rest of this chapter and go on to Chapter 2. We recommend that you read the sections on saving files and exiting Emacs. There’s also a table of commands at the end of this chapter for future reference. If you’d like to learn more about working with files as well as some shortcuts, stay with us through the rest of the chapter.

If You Read the Wrong File

If you happen to read the wrong file, an easy way to get the right file is by typing C-x C-v (for find-alternate-file). This command means “Read a different file instead of the one I just read.” After typing C-x C-v, Emacs puts the name of the current file in the minibuffer; you can then correct a typo or the path, the most common reasons for finding the wrong file. Make the correction and press Enter. Emacs replaces the buffer’s contents with the alternate file.

Letting Emacs Fill in the Blanks

Emacs has a very helpful feature known as completion. If you want an existing file, you need only type the first few letters of the name, enough to uniquely identify the filename. Press Tab, and Emacs completes the filename for you. For example, suppose you are trying to find a file called dickens.

Type: C-x C-f di

image with no caption

After C-x C-f, Emacs prompts you for the filename; type the first few letters.

Press: Tab

image with no caption

When you press Tab, Emacs fills in the rest of the filename.

Press: Enter

image with no caption

Emacs reads the file dickens.

If more than one file starts with di, Emacs displays a window with various files that start with that string. You select one by typing a few more characters (enough to identify your file as unique) and pressing Tab again. Or you can select one of the alternatives with the mouse or by pressing PgUp to move to the completions window, moving to the desired option, then pressing Enter.

Completion also works for long command names. It’s a wonderful Emacs feature that can save you time—and show you some commands you might not know existed in the process. Chapter 14 provides more details on the glories of completion.

Inserting and Appending Files

If you want to insert one file into another, you simply move to the appropriate location in the file and type C-x i. (Yes, we know, we haven’t told you how to move around in a file yet. Use the arrow keys for now and we’ll teach you the “real” Emacs cursor movement commands in Chapter 2.) To append a file, move to the end of the file (M->) and type C-x i. As with C-x C-f, Emacs prompts you for the filename in the minibuffer.

How Emacs Chooses a Default Directory

When you use any command that asks for a filename (such as C-x C-f), Emacs displays a default directory in the minibuffer and asks you to type the rest of the filename. How does Emacs choose the default directory? The default directory is taken from the buffer that the cursor is currently in. If you are editing a file in your home directory when you type C-x C-f, Emacs assumes you want to edit another file in your home directory. If you are editing the file /sources/macros/html.macs then Emacs makes the default directory /sources/macros. If you want to find a file in another directory, edit the default directory that Emacs displays.

Saving Files

To save the file you are editing, type C-x C-s. Emacs writes the file. To let you know that the file was saved, it puts the message Wrote filename in the minibuffer. If you haven’t made any changes to the file, Emacs puts the message No changes need to be saved in the minibuffer. You can also get to this option by pressing the diskette on the toolbar or choosing Save (current buffer) from the File menu.

If you decide to save something you’ve typed in the *scratch* buffer by typing C-x C-s, Emacs asks you for a filename. After you give it a filename, Emacs changes the mode line accordingly.

A related command is write-file (C-x C-w). It is the Emacs equivalent of the Save As option found on many applications’ File menus. The write-file command asks you to type a new filename in the minibuffer. However, if you just press Enter instead of typing a new filename, write-file saves the file with its old name—just as C-x C-s would have done. (It does ask if you want to replace the current file with the one in this buffer, however.)

The write-file command is useful for editing files that you do not have permission to change. Use the find-file command to get the file you want into a buffer, and then use write-file to create your own private version, with a different name or path. This maneuver allows you to copy the file to one that you own and can change. Of course, the original file is not affected.

Leaving Emacs

To quit Emacs, type C-x C-c or close it like you would any other application. If you have made changes to a buffer, Emacs asks you if you want to save them.[5] If you type y, Emacs writes the file, then exits. If you type n, Emacs asks you to confirm that you want to abandon the changes you made by typing yes or no in full. If you type no, your normal Emacs session continues just as if you never attempted to exit. If you type yes, you exit Emacs and the changes you made during this session do not become permanent. Leaving without saving changes can be useful if you make changes you didn’t intend to make.

By the way, Emacs is picky about whether you type y or yes. Sometimes it wants one, sometimes the other. If it asks for a y, you can sometimes get away with typing yes but not vice versa. If it beeps and displays, Please answer yes or no, you didn’t enter the whole word and it wants you to.

Getting Help

Emacs has extensive online help, which is discussed further in Chapter 14. You can enter help through the lifesaver icon on the toolbar or through the Help menu. Either method will show you a help menu, described later in this section. To enter help using the keyboard, press C-h. Pressing C-h ? gives you a list of options. Pressing C-h t starts a tutorial that is an excellent introduction to Emacs.

To get information about the meaning of a keystroke combination, press C-h k for describe-key. For example, if you type C-h k C-x i, Emacs displays a description of the insert-file command, which is bound to C-x i. Pressing C-h f (for describe-function) asks Emacs to describe a function (really just a command name, such as find-file). Essentially, C-h k and C-h f give you the same information; the difference is that with C-h k, you press a key whereas with C-h f, you type a command name.

Assume you want to find out about what C-x i does.

Type: C-h k

image with no caption

Asking for help about a keyboard command.

Type: C-x i

image with no caption

Emacs splits the screen to display help.

A few things to notice: the window is now split into two parts because you’re looking at two separate buffers. Each buffer has its own mode line. The lower buffer is the *Help* buffer; it contains the information about the insert-file command. Emacs keeps the cursor in the dickens buffer because there’s no good reason for you to edit the *Help* buffer.

You might also notice that in the text describing this command, Emacs calls the cursor point. This term is used throughout Emacs to refer to the cursor; you’re bound to encounter it.

To make the *Help* buffer disappear, press C-x 1 (we cover this command in Chapter 4).

The Help Menu

You can also use the Help menu to access help commands quickly, and you can get there either through the menu or through the lifesaver on the toolbar. On this menu, you find options we’ve discussed here: Emacs Tutorial, Describe Describe Key, and Describe Describe Function. It includes a host of interesting options, including access to the Emacs frequently asked questions (FAQ) file, a new search feature, and even an Emacs psychiatrist (you might tell it something like “Emacs is driving me over the edge today”). There’s an interface to Info, Emacs’s online documentation. Simply choose Read the Emacs Manual to start Info.

In this section, we’ve given a very brief introduction to a few of the paths you can take in the help system. There are many more help facilities; they are described thoroughly in Chapter 14. The help features we’ve described here should be enough to get you started; if you want to learn more, jump ahead to Chapter 14.

Summary

Now you know the basic commands for starting and stopping Emacs and for working with files. Chapter 2 builds on these commands to give you the skills you need for editing with Emacs. Table 1-4 summarizes the commands we covered in this chapter.

Table 1-4. File handling commands

Keystrokes

Command name

Action

C-x C-f File Open File

find-file

Find file and read it in a new buffer.

C-x C-v

find-alternate-file

Read an alternate file, replacing the one read with C-x C-f.

C-x iFile Insert File

insert-file

Insert file at cursor position.

C-x C-sFile Save (current buffer)

save-buffer

Save file.

C-x C-wFile Save Buffer As

write-file

Write buffer contents to file.

C-x C-cFile Exit Emacs

save-buffers-kill-emacs

Exit Emacs.

C-h

help-command

Enter the online help system.

C-h fHelp Describe Function

describe-function

Gives online help for a given command name.

C-h kHelp Describe Key

describe-key

Gives online help for a given keystroke sequence.

C-h tHelp Emacs Tutorial

help-with-tutorial

Start the Emacs tutorial.

C-h iHelp Browse Manuals

info-goto-emacs-command-node

Start the Info documentation reader.

Problems You May Encounter

  • Emacs doesn’t do what this book says or look like our screenshots. Make sure that you have GNU Emacs 21.3.5 or later running by typing M-x version Enter or selecting Help About Emacs. Read the section “Making Emacs Work the Way You Want” in Chapter 2. You may need to install a graphical version of Emacs if you are running in a terminal window; see Chapter 13 for details.

  • The toolbar icons are completely different. The icons changed between Emacs 21.3.1 and Emacs 21.3.5. The older icons do the same thing; the newer ones are substantially better looking and more intuitive. Upgrade Emacs using instructions in Chapter 13.

  • You can’t access menus using the mouse. Use the text-based menus instead by pressing F10 or M-`. Better yet, install a graphical version of Emacs using the instructions in Chapter 13.

  • PgUp doesn’t work properly when using text-based menus. PgUp is probably bound to some application-specific function, such as scrolling in the Mac OS X Terminal application. Press Shift-PgUp, F10, or M-` to access the menus.

  • You can’t see a mode line or minibuffer. Your Emacs window is bigger than your display. See Chapter 10 for information on how to get Emacs to start with a reasonable window size. As a temporary workaround, resize the window. (On some Windows systems, maximizing the window ironically makes it smaller, solving the problem.)



[1] How you start Emacs may vary by platform. Linux has no icon on the desktop by default; Windows and Mac OS X do (if you’ve installed Emacs on these platforms). Note that Mac OS X comes with a version of GNU Emacs installed in /usr/bin, and that is what runs by default when you start up Emacs using the Terminal application. You won’t be able to use the mouse at all if you run Emacs in the Terminal application, and there are a number of other limitations as well. Better versions of GNU Emacs are available to you; see Chapter 13 for details.

[2] Emacs works best with a three-button mouse (more buttons are okay, too).

[3] The scrollbar’s location depends on the platform and windowing system you’re using. Linux puts scrollbars on the left while Mac OS X and Windows put them on the right by default. Note also that the order of the information in the mode line is different if you run Emacs in a terminal window.

[4] In certain special editing modes, such as dired-mode for viewing and manipulating directories on your computer, the normal typing keys don’t insert themselves. They are instead bound to special commands that do things like opening and renaming files. This flexibility in defining and changing keymaps, while it might seem somewhat arbitrary and overwhelming at first, is one of the great sources of power in Emacs.

[5] One exception to this rule is the *scratch* buffer. It’s a scratchpad and Emacs assumes you were doodling, not doing serious artwork, so to speak. If you do any serious work in the *scratch* buffer, you must save it explicitly.

Get Learning GNU Emacs, 3rd Edition now with the O’Reilly learning platform.

O’Reilly members experience live online training, plus books, videos, and digital content from nearly 200 publishers.