Using Emacs

a brief introduction

What is Emacs?

Emacs is a text editor, used to create and edit documents such as program source code, techinical documentation, or anything else you feel like. Emacs is probably the most common and easy-to-use editor for UNIX systems (if you grow to like Emacs, it is also available on Windows NT and Windows 95 systems). Emacs is also the most powerful and flexible editor you're ever likely to use. The engine behind emacs is a Lisp interpreter, which allows users to code their own routines to enhance and customize the Emacs environment. The key to getting started with Emacs is to just pretend "what I don't know won't hurt me" and use what you find useful. The more you use it, the more you'll learn. If you need to accomplish something and can't figure it out, feel free to ask.

Notation

When talking about Emacs, we'll use the notation C- to indicate that a key should be pressed while holding down the control key (Emacs requires this a lot). For example C-h means hit h while holding down the control key. Similarly, M- means use the Meta key. If you don't have a key called "Meta" on your keyboard, then usually the "Alt" or "Alt Function" key is what you should use. If your keyboard has no Alt or Meta key, then you can use the "Escape" key but do not hold it down as you would an Alt or Meta key. For example, M-x means hit x while holding down the Meta key.

Lots of Emacs functions take two keystrokes to complete. For example, to exit Emacs, use C-x C-c (Control-X followed by Control-C).

Running Emacs

Emacs can be run in two modes. In console mode, Emacs will work on any sort of character terminal and makes very few assumptions about what your hardware set-up is. You could run Emacs from home on a VT-100 in this mode, for example. The other mode assumes that you have a device that supports the X window system. The X-Terminals in Sieg 329, for example, meet this criteria. There are software packages (such as Hummingbird's Exceed product) that allow you to run an X window enviroment on a standard PC running Windows 95 or Windows NT. Running Emacs in an X window allows you to do fun stuff like use the mouse for cut and paste, use the mouse to access pull-down menus, etc... This mode is recommended whenever it's available to you -- it's much easier to use.

After logging onto your account, you run Emacs by simply typing:

emacs

If you haven't set up your DISPLAY environment variable, Emacs will run in console mode within the window you're typing in. The command to exit from Emacs is C-x C-c.

To run Emacs in X window mode, you may need to do some setup. If you're logged in directly to one of the CSE instructional machines (sanjuan or orcas) through an X-Terminal in 329, then Emacs ought to start up in X window mode automatically. If not, then you must first tell your display that it's OK for the machine you're running from to use its display. This is done using xhost + followed by the name of the machine that you'll be running Emacs on. For example, if you are sitting at a machine named mingus.cs.washington.edu, and you want to run Emacs from sanjuan.cs.washington.edu, you would type:

xhost +sanjuan.cs.washington.edu

Next, you have to tell the machine that you're running from which display you're at using setenv DISPLAY followed by your display name and 0.0. For example in the above situation, from a shell window on sanjuan, you would type:

setenv DISPLAY mingus.cs.washington.edu:0.0

Now when you run Emacs, it should show up in its own window on your display, and you should be able to use the mouse and such. We'll assume this mode of operation for the remainder of this document.

Emacs Orientation

When you start up Emacs, it will come up with an empty buffer. At the top of the window are some pull-down menus which contain some of the common operations. At the right side is a scroll bar. Near the bottom is a status bar. Just below that is a line called the mini-buffer.


Figure 1 A small Emacs window

The status bar tells you what you about the buffer you're looking at. The double asterisk (**) indicates that the buffer has been modified since it was created or last saved to disk (in this case because the word "test" was just typed in it). Sometimes, you'll see "%%" there. That means the current buffer is read-only, and that you can't type into it. Next, the bar says "Emacs:" and tells the name of the buffer "*scratch*" -- this is the default buffer when starting up. Next, it tells the mode that this buffer is operating in -- Lisp Interaction mode is the default when starting up. Then it tells what part of the buffer you're looking at. In this case, it contains only the word test, so we are seeing "All" of it.

The minibuffer is a small buffer which Emacs uses to report error conditions to you, and to prompt you for information when necessary.

The cursor indicates where your text will appear when you type. You can reposition it using the mouse, or using the arrow keys.

Buffers are the basic unit in Emacs. Each file you edit has its own buffer. There can also be buffers for other purposes -- for example the minibuffer is used for interactions between Emacs and the user; you can have a buffer in which you're running a Lisp interpreter; etc. At any given time, your Emacs session will have multiple buffers around, although only a few may be visible at any given time.

Each buffer has an associated mode with it which controls the behavior of everything you do in it. For example, if you edit a file with the .c extension, Emacs will realize that this is a C file, and will put you in C mode, which knows how C programs should be indented. Similarly, if you open a .pl file, the buffer will be in Perl-mode. and know the syntax of that language. In addition to the indentation rules changing based on the buffer's mode, key sequences may perform different actions, additional pull-down menus may be added, and different sorts of syntax checks will be done for you (such as balancing the braces in C).

The *scratch* buffer is just that -- scratch space for you to type anything you want without associating a file with it.

Cancelling and Exiting

The two most important key sequences to know in Lisp are C-g and C-x C-c. C-g is used to cancel an action that you've started, and can be an excellent way to get out of mysterious features that you accidentally got yourself into by typing the wrong thing. A good rule of thumb is: when in doubt, use C-g. Sometimes use it several times in a row, just to make sure. :-)

The other thing you'll want to know is how to exit. Use C-x C-c. Lisp will prompt you if you haven't saved all of your buffers, or if you've left any processes (such as a Lisp interpreter or a debugger) running.

The Pull-down menus

Recent versions of Emacs (starting with version 19) come with pull-down menus, after years of only providing Control-key sequences to get things done. This document only describes the key sequences, but many of the things that are explained here are also available through the menus.

Reading and Writing Files

To load a file from disk or start editing a new file, use C-x C-f (find file). In the minibuffer, you'll be prompted for a filename. If the file already exists on disk, it will be loaded into Emacs. Otherwise, Emacs will create a new file for you. If you're not sure of the filename, you can hit the SPACE key at any time to get a list of those files which match what you've typed up to that point. Or you can use the TAB key for file completion.

To save a file, use C-x C-s. If there have been any changes, the file will be written to disk. To save it under a different filename, use C-x C-w (write file). You'll be prompted for a new name, and the buffer will be renamed (although the original file will still exist on disk).

Moving Around

Most of the time, you can move the Emacs cursor around using the arrow keys or the mouse. Sometimes, however, they won't work, and you'll have to use the keys: C-f, C-b, C-p, C-n to move forwards, back, to the previous line, and to the next line, respectively.

To jump to the beginning of a screen line use C-a (First letter in the alphabet). To jump to the end of the line, use C-e.

To move more quickly, use C-v to move down a screenful, and M-v to move up a screenful. Use C-< to move to the beginning of a buffer and C-> to move to the end.

Emacs also provides commands to navigate paragraphs, sentences, and words. You can use C-{ to move up a paragraph and C-} to move down a paragraph; M-a to move to the beginning of the previous sentence and M-e to move to the end of the next sentence. M-b to move back a word and M-f to move forward a word (Or M-left and M-right).

Marking a Region

If you can use a mouse with Emacs, you can mark a region of text the way you would on any system: clicking and dragging. The highlight tends to disappear after you let go of the button, but the region will still be marked.

Otherwise, you have to mark the region by moving to one end of it and hitting C-SPACE. Emacs will respond with "Mark set". Then move to the other end and do whatever operation you want. This is important: Emacs always has a notion of where the last mark was set (lots of operations set "the mark" wherever the cursor was when the operation was initiated). Thus, it always has a notion of the current region: namely, everything between "the mark" and your cursor. This can be a problem if you accidentally hit "delete" for example, because half of your file will disappear without you understanding why. Fortunately, Emacs provides an undo function described below.

Cutting, Copying, and Pasting

One way to cut text in Emacs is to use C-k (kill). This is often the easiest way to remove moderate amounts of text. C-k takes out the text between the cursor and the end of the line. If there is no text, then it takes out the linefeed and moves the next line up. Lines that you kill accumulate to be pasted.

A more conventional way of cutting would be to highlight and use C-w (wipe out). If you're on a machine where you can't use a mouse, set the region as described above. Pasting is done using C-y (yank). Copying can be done in the X windows way: namely, highlight a region with the mouse and then click the middle mouse button to paste. Or you can use M-w.

Undoing

Emacs has a phenomenal undo feature: C-x u. You can undo until your fingers turn blue, slowly undoing lots and lots of recent keystrokes, commands, and what-have-you. It remembers quite a lot of what you've recently done.

Working with Buffers

When you start Emacs up, you'll typically only see one buffer and the minibuffer. You can split the screen to view multiple buffers at once. This can be useful for viewing multiple files simultaneously, or even different portions of the same file. C-x 2 will divide a buffer window in half vertically giving you two buffers, each with their own status bar. Move between the buffers using C-x C-o or the mouse. Similarly, you can cut a buffer horizontally using C-x 3.

To hide the buffer your cursor is in, use C-x 0. Or to make the buffer your cursor is in fill up the whole window again, use C-x 1. To view all the buffers in an Emacs session, use C-x C-b. To switch to a different buffer, use C-x b and Emacs will prompt you for its name.

Normally when you are not viewing a buffer, it's still there though it's not visible. To really drop one from your Emacs session, use C-x k and supply the name. If it's modified, Emacs will check with you before killing it. This can be useful if you need to get rid of a bunch of changes to a file.

You'll notice that Emacs uses buffers to report information to you. These are typically surrounded with *'s to show that they don't have files associated with them. You can switch between them or kill them just like any other buffer.

Functions/Key Bindings

Almost every function in Emacs is implemented somewhere using a Lisp routine. The common routines are bound to Control- and Meta- key sequences as we've been describing. Emacs lets you bind any function to any key sequence, which is part of the way in which it's so customizable.

You can also call functions that are unbound by using M-x. This allows you to type the name of the function, which will then be executed. For example, C-v is bound to the "scroll-up" function. You could therefore also scroll up using M-x scroll-up.

Searching/Replacing

To search forward for a string, use C-s. To search backwards (reverse), use C-r. Emacs will prompt you in the minibuffer for the string to search for.

To replace all occurrences of a string in a buffer, use M-x replace-string. To replace some instances of a string, use M-x query-replace and you'll be prompted at every location of the string.

On-line help

Emacs has a lot of help available to you using C-h. You can then follow it with a single letter indicating what sort of help you want. ? gives you a list of options. a takes a string and lists all the Emacs functions related to that string. k lets you type a key sequence, and explains briefly what function that key is bound to. f lets you type the name of a function, and it will describe it in detail. m gives you information about the mode of the current buffer (e.g. Common Lisp mode, C-mode, etc.). t takes you through a tutorial which is not highly recommended.

Conclusions

There is a summary of much of the above information (as well as some other Emacs fuctionality) on the Emacs Quick Reference page. Feel free to ask if you want something in this page clarified, or if you need to accomplish something that isn't explained here.