Emacs Help

Purpose

This document is intended to assist those new to unix editors in learning emacs - a powerful (thus frightening) text editor.

Why learn an editor?

First, as a web author, you should know something about unix and be able to work in the unix environment. This means you should really know an editor or two. Much of your work will happen in a text editor, so it ought to be something that will help you. There are many other text editors available in the unix world. The three most popular are vi, pico, and emacs. There are several others (sed, vim, etc) but these are often either modifications of one of the 'big three' (vim is a variant of vi) or too complicated to be worth using (sed is a PAIN). Actually, I'm not too concerned which editor you use, but here's why I don't use the others.

Pico

This is the little text editor that comes packaged with pine. In fact it shares much of the command set with emacs. It is a lovely little editor, and is very easy to use. Unfortunately, you will outgrow it pretty quickly. It does not support such things as keyboard macros, multiple files, or quick HTML commands. The most frustrating part is the way it handles word wrap. Pico automatically inserts carriage returns at the end of each line. This is great when you are writing email, but very frustrating when programming. In programming languages, a carriage return at the wrong place can be deadly. Every semester somebody loses a couple night's sleep because they viewed a perl file in pico which then added all kinds of inappropriate carriage returns without any warning.

vi

Vi is better than pico in a sense, since it does have many of the features you might wish for in a higher-end editor. It is still a bit on the ugly side, as it has no online help, and the commands are a bit odd. Vi basically has an edit mode and a command mode. Pressing a key gives a different response in the different modes, and it is easy to forget which mode you are in. In one mode, pressing the "d" key means "put a d on the screen". In another mode, the same "d" means "delete the next character."

older versions of emacs

Some of the older versions of emacs were incredibly intimidating, since they did not supply any kind of on-line menuing system. You basically had to look up every command in online help when you wanted it. Fortunately, the help system was pretty good, if a bit clumsy.

So why emacs?

Emacs has a number of features that make it particularly well suited to web programming. We won't cover them all in this document, but this gives you a feel for what it can do:

Getting started

To get started with emacs, just go to the appropriate directory (usually where you want your file to be or where it already exists) and type emacs FILENAME where FILENAME is the name of the file you want to edit. Emacs will use the name of the file to guess a special mode (eg html) if it is appropriate.

Using the Menus

The online menus are ugly but quite servicable. You can use emacs without memorising a single keystroke sequence (although you'll find the keystrokes come naturally after a while.)
The trick to the menus is getting them started up. In most terminals, you can use the F10 key to start the menus. If that doesn't work, try Esc then the ` (accent character, NOT the ' single quote/apostrophe. On many keyboards this is on the same key as the ~ (tilde.)
Once you have used the menus a little bit, you will find they are great for finding new commands, but a little bit tedious for stuff you do a lot. The menu will show you a keystroke sequence that is a lot faster and more efficient. You will soon find yourself learning a lot of these sequences, and you will find them to be incredibly quick and efficient. At some point, you will discover you have pretty much left the menus altogether, and do most of your commands through these keystroke sequences. Later in this document we will give you a list of the most common commands and their keystroke equivalents.

Using keystroke sequences

In Emacs documentation, there is a special shortcut that is often used. Like many programs, emacs uses a control key to execute many commands. The problem is that emacs is so powerful, and there are so many such commands, that the control key with other keys will still not give you access to all the commands, or even all the most important ones. There's a couple of answers to this problem, and emacs uses several of these strategies.

Control commands

The control key works just as you would expect it to, and is almost always held down like the shift key as you press other keys. For example, to move one character to the right, you could press and hold the control key, then press the 'f' key. This combination is known in emacs documentation like this: C-f. The C stands for Control, and of course, f stands for the f key. Note that f can also mean forward. Many of the emacs commands have a mneumonic such as this, so they are not so difficult to memorise as you might think.

Get me out of here!!!

Probably the most important sequence in emacs is the one that lets you back out of trouble. Often you might have a bunch of wierd windows open, and you just don't know what's going on. This command usually helps: C-g. It means 'cancel current command' (I remember "g" for "get me outa here!") If you are having strange things happen in emacs, C-g is often a good bet.

More complex control commands

The control key does not really give you enough functionality on its own, so there are some commands that are a little longer. One command for saving a file looks like this: C-x s. To perform this command, you would press and hold the control key as you type the 'x' key, then release the control key as you press the 's.' It's really a lot simpler than it sounds. What this will do is act like a 'save as' command. It will prompt you for a file name. Another command to save a file looks like this: C-x C-s. That means you should do control X, then control s in rapid succession, and you will execute the save file command. The C-x part is a special command that says "housekeeping command coming" Most of the commands that deal with controlling emacs itself begin with C-x. The 'two control keys' combination such as this is often a more powerful version of the 'one control' command.

The meta key

Many computers have some kind of 'secondary' control key. This might be the 'alt' key on Windows-like machines, the 'Apple' key on Macs, or the diamond key on a Sun workstation. The problem is that emacs is usually accessed through terminals, and doesn't know what that secondary control key is. If your terminal program is configured perfectly (it almost never is), you can use this secondary control key to run a bunch of other emacs commands. Emacs calls this secondary key the meta key. In truth, the most common way to use the meta key is none of the alt/apple keys, but the Escape key. Nearly every terminal made has an escape key, so it is usually used as the meta key. If you are using Esc as the meta key, note that it is not used exactly like control. You don't hold the escape key down as you perform a sequence. This takes a bit of getting used to, but soon you'll have no problems.
In the documentation, you will see meta commands something like this: M-f. This means "press and release the escape key, then hit the 'f' key. What this will do is position the cursor one WORD (usually) to the right. Notice how this command relates to the C-f command (which was move one CHARACTER to the right.) You will frequently see this kind of relationship, where a meta sequence will simply be a more powerful version of the control sequence.

The M-x commands

Every command in emacs has a long, English-like name, usually with full words seperated by dashes. For example, the full name of C-f is 'forward-char'. M-f is 'forward-word'. C-x C-s is 'save-buffer'. These long names are harder to type, but easier to remember. If you want to run a particular command and you don't know its keystroke command, you can use M-x to run the command by its full name. This is how it works: Type in M-x, and the name of the command (assuming you know it). If you type part of the command and hit the enter or tab key, emacs will try to finish the command for you, or give you a menu of choices. For example, when I tried 'M-x save-' then hit the enter key, a window popped up with these choices in it: These are all interesting options, but save-buffer is the one I want, so I moved to it with my arrow keys or keyboard movement commands, and hit enter, then the buffer was saved, in the same way I normally do it with C-x C-s.
The advantage of this kind of command is that sometimes it's easier to remember commands this way. Also, some commands do not have a keystroke combination assigned to them.

Using the online help

In the unix world, online help is still a bit rare. Emacs is unique in offering a very powerful online help system. If anything, the online help in emacs is too powerful. It sometimes intimidates beginners with its power and complexity, as does emacs itself. I'll show you the most important ways to use this feature.

Running the tutorial

The best way to learn anything is by doing it. Emacs comes with a very good tutorial. To use it, enter emacs and type C-h t. This will load up a text file. You will learn how to move the cursor around, copy and paste text, save and load files, and a few of the other basics. You can get by just fine by knowing only what is on the tutorial. You can't hurt anything in this file.

The apropos command

C-h a calls the 'command-apropos' command. This works kind of like an index in a more traditional help system. It allows you to type in a word or phrase, then returns a list of commands that have that phrase in the name. You can then scroll through the list of commands that may be relevant. This is sometimes very useful, and sometimes not useful at all.

The describe-bindings command

This incredibly handy command pops up a list of all the keystroke commands that emacs currently recognizes. Note that the bindings can change, depending on how emacs is configured, and the type of file that is being edited. For example, if you are typing a plain text file, the command C-c 3 does nothing, but if you are working on an HTML document, emacs interprets this sequence as html-headline-3, which means 'make the HTML tags for a level three headline.' If all you need is a summary of the commands available, this is a pretty handy capability.

The info mode

The C-h i command calls up a special program called 'info' which is a little bit like a traditional help system. You can use your normal commands to move around in this mode and view the documentation. The online help available here is quite complete.

Describe function

The 'C-h f' sequence asks for the name of a function or command, then describes that command. The description is often a bit jargony, but it will work.

My favorite commands

Keyboard movement

Key command what it does
C-f (right arrow) forward-char move forward one character
C-b (left arrow) backward-char move backwards one character
C-p (up arrow) previous-line move up one line
C-n (down arrow) next-line move down one line
M-f forward-word move forward one word
M-b backward-word move backwards one word
C-v scroll-up move cursor DOWN one screen in the document
M-v scroll-down move cursor UP one screen in the document
M-< beginning-of-buffer Go to the beginning of the document
M-> end-of-buffer Go to the end of the document
C-a beginning-of-line go to beginning of line. (surprise.)
C-e end-of-line go to the end of the line

File and window handling commands

Key command what it does
C-x C-f find-file open a new or existing file
C-x C-s save-buffer save this file with it's existing name
C-x C-c save-buffers-kill-emacs exit emacs
C-x o other-window move to another window (if more than one is visible)
C-x 1 delete-other-windows make the current window the only window visible
C-x 2 split-window-vertically makes another window (full width of the screen)
C-x 3 split-window-horizontally makes another window (full height of the screen)
M-x shell shell make a unix command line in the current window

Editing commands

Key command what it does
C-g (M M M) keyboard-quit quit current command
C-@ (C-SPACE) set-mark set a boundary for copying or deleting
C-w kill-region cut from mark to here, keep in buffer
C-k kill-line cut from here to end of line, keep in buffer
C-y yank paste last thing put in buffer
M-y yank-pop paste previous buffer (C-y must happen first)
C-s isearch-forward prompts for a phrase, searches for it interactively
M-% query-replace do an interactive search and replace
M-x ispell-buffer ispell-buffer run an interactive spell-checker
C-x ( start-kbd-macro begins recording a macro
C-x ) end-kbd-macro stops recording the macro
C-x e call-last-kbd-macro replay the last macro
M-5 C-x e call-last-kbd-macro replay the macro 5 (or however many) times

help commands

Key command what it does
C-h ? help-for-help shows a list of the help commands
C-h t help-with-tutorial runs the online tutorial
C-h a command-apropos allows user to search for a command containing a word
C-h m describe-mode describes anything special about the current setup
C-h b describe-bindings gives a list of the current key commands
C-h i info runs the special info help system
M-` (F10) tmm-menubar opens the menu in text mode

HTML commands

(must be in html mode. Create a file with html extension.)
Key command what it does
C-c 1 html-headline-1 make <h1></h1> tags (C-c 2 makes <h2>, and so on)
C-c C-c i html-image make <img src="http:"> tag
C-c C-c h html-href-anchor make <a href="http:"></a> tags
C-c C-c u html-unordered-list make tags for a new unordered list
C-c C-c o html-ordered-list make tags for a new ordered list
C-c C-c l html-list-item add an <li> tag

directory editor

Key command what it does
C-x d dired start up the directory editor
up, down arrow keys (in dired) move to files
enter key (in dired) open file or directory
c (while cursor on a file name) copy the file
M (capital M) (in dired) Prompt for new permission
C-s isearch-forward search for a file

Try THIS in pico!!

Note: To learn more about these features, use C-h m to bring up a mode-specific help file.
Key command what it does
M-x blackbox blackbox mode A logic game (C-h m for help)
M-x doctor doctor mode Emacs has a built in psychotherapist(!)
M-x dunnet dunnet A text-only adventure game
M-x yow zippy the pinhead generate a completely meaningless random phrase
M-x spook spook generate anarchistic phrases
© Andy Harris
Indiana University / Purdue University, Indianapolis
email: aharris@klingon.cs.iupui.edu
homepage: www.cs.iupui.edu/~aharris