@device(imprint10) @make(report) @definefont(Userfont, 1=, 2=, 3=, 4=, 5=, 6=) @modify(hd2, font userfont, facecode 3, leftmargin -2) @modify(hd3, font userfont, facecode 4, leftmargin -2) @modify(copyrightnotice, flushright, fixed -1 inch) @modify(fileexample, above 1, below 1) @Style(Font computermodernroman11) @Style(spacing 1,indent 0) @Style(leftmargin 1.0inch) @Style(Linewidth 6.5inches) @pageheading( left="", center="", right="@b(Essential Emacs)") @pagefooting(left="@b(MIT Project Athena)", center="@value(page)", right="@b(Revision C: Sept. 8, 1986)") @Blankspace(1.4 inch) @begin(MajorHeading,Flushright,Font Userfont, FaceCode 1, below .3) Essential Emacs @end(Majorheading) @blankspace(.75 inch) @begin(flushright, Font Userfont, FaceCode 4) Linda B. Merims MIT Project Athena Revision C September 8, 1986 @end(flushright) @blankspace(3 inch) @heading(Note) @begin(text, leftmargin +5,rightmargin +5) Project Athena changed its default editor to GNU Emacs on August 4, 1986. All people new to the system should learn GNU Emacs. People who already know the old CCA Emacs dialect should switch to GNU Emacs. See the free document @i(GNU Emacs for CCA Emacs Users). @end(text) @copyrightNotice(Massachusetts Institute of Technology) @newpage @begin(heading, flushright, font userfont, facecode 2) Essential GNU Emacs @end(heading) @blankspace(1.2 inch) @section(Introduction) Learning how to use a system's text editor is the single most important tool you can acquire. You need to know the editor before you can use most of the other things you will want to do on Project Athena, including electronic mail, the Scribe text formatter, and programming. These few pages tell you the minimum facts you need to know to use the GNU Emacs text editor on MIT's Project Athena system. Basic mastery of any editor means knowing how to: @begin(itemize, spread 0) start the editor create new text (insert) move around the lines of text delete text you don't want get out of surprise situations leave the editor while saving your work @end(itemize) With just this information you may not be able to do anything fancy, but you will be able to accomplish something useful. @section(Two Kinds of Displays) Athena has two main kinds of video displays: plain video @p(terminals); and the oversized, black and white @p(workstation) displays. Emacs works the same on both types of display--@i(except when you first start it up). You have to do a few extra things to use Emacs on a workstation. The next section shows how to start Emacs on a plain video terminal. If you are using a workstation, see the Appendix, "Emacs on a Workstation." @section(To Get into Emacs on a Terminal) To enter the Emacs text editor, type this command in response to the system's @i(host%) prompt: @fileexample[ @i(host%) emacs @i(anyfilename)] Notice that the command, as with most commands on the Unix system, is entered in all lowercase. @i(anyfilename) can be either the name of an existing file that you want to edit, or a new filename that you invent on the spot for a new file. Do not omit the filename or Emacs will not save your work when you exit. @newpage @section(Buffers) All editing that you do with Emacs is performed in a @b(buffer). You are never modifying the actual file, but a working copy held in the Emacs buffer. If @i(anyfilename) was an already-existing file, then a copy of it is read into the Emacs buffer. If @i(anyfilename) was a new file, then you begin with an empty buffer. @begin(group) @verbatim[ emacs existingfile Emacs buffer ___________________ ____________________ | Your file full | | Your file full | | of text... | | of text... | | | -------> | | | | copy | | |_________________| |__________________| ] @end(group) @begin(group)@verbatim[ empty Emacs buffer ____________________ | | | | emacs newfile | | | | |__________________| ]@end(group) @section(The Screen) After you enter the @i(emacs) command, there will be a short pause, the screen will blank, and you will see a Emacs screen. (On a workstation, you will have to go through some extra steps. See the Appendix.) @blankspace(3 inch) If you are on a VT240 or VT125 graphics terminal, you will see a caution message that says that two Emacs commands (@b(C-s) and @b(C-q)) are different on your terminal. Press RETURN to remove the message. The Emacs screen is divided into three zones: @itemize{ Everything above the bar is your @b(buffer editing area). If you are editing an existing file, this is where it is displayed. If it is a new file, this area is blank. The bar -- usually displayed with black letters on a white background in so-called "reverse video" -- is the Emacs @b(mode line). Here Emacs displays status information about the editing session, such as the name of the file being edited. Most of this is unimportant to the beginner. The last few lines are the Emacs @b(echo area). Whenever Emacs needs to ask you a question ("prompt you" for information), it asks it down here.} @section(Entering Emacs Commands) Emacs commands look like this: @b(C-a, M-v, C-x i). The commands are made up of two pieces: a @b(prefix character) (like C-, M-, or C-x) followed by a @i(second character) (the a, v, i, or any keyboard character) that signals specifically what is to happen. (A "character" can actually have more than one keystroke in it.) There are six prefix characters. The two fundamental prefix characters are @b(Control) and @b(Meta). Control is also talked about in documentation as CTRL, C-, or ^. Meta is talked about in documentation as M-, or ESC. To enter a @b(Control) prefix command, for example, C-a (control-a): @itemize{ Find the CTRL key on your keyboard. It is on the left, near the shift lock key. Press the CTRL key, and while @i(still holding it down), press the A key. The principle is exactly the same as holding down the shift key to produce a capital A. You hold down the CTRL key to produce a control-a (or a control-c, or control-v, etc.) } @b(Meta) is slightly more involved. On @p(non-workstation) terminals, you use the @b(ESCape) key for Meta. To enter, for example, M-v: @itemize{ Find the ESC key on your terminal. On the VT125 terminals and PC/XT terminals, the ESC key is in the upper left-hand corner near the 1 key. On the other terminals, it is one of the line of keys across the top of the keyboard, labeled F11 (ESC). If your keys are unlabeled, it's the eleventh key from the left. Press the ESC key, then @i(release) it. Then press the V key. } On @p(workstation) keyboards, you enter @b(Meta) the same way that you enter Control: @itemize{Find the Meta key. It is to the left of the spacebar. On DEC workstations it is labeled "Symbol" or "Compose Character." On IBM workstations, it is labeled "ALT." Press the Meta key, and while @i(still holding it down), press the other key. Again, Meta works like a shift key.} The other prefix characters are: @begin(group) @fileexample{ C-x control-x C-c control-c C-h control-h "help prefix" C-M "control-meta" (Type ESC C-character on non-workstations) }@end(group) On VT125 and VT240 graphics terminals, the @b(C-s) and @b(C-q) commands have been changed to @b(C-~) and @b(C-\), respectively. You can remember C-~ because it is curved like C-s. If you do type @b(C-s) by mistake on one of these terminals, it will seem to freeze. Type @b(C-q) to unfreeze it. You will get a warning message about this when you start Emacs on one of these terminals. @section(To Get Out of Emacs) To leave Emacs, type the command: @fileexample{ C-x C-c } (i.e., enter a control-x followed by a control-c.) Down in its echo area at the bottom of the screen, Emacs asks you: @fileexample{ Save file /mit/y/o/you/yourfile? (y or n) } Emacs is asking you if you want it to copy the working buffer back out into the real file. In short, do you want to keep the work you've done (reply @I{yes}), or throw it away (reply @i{no})? Notice that Emacs doesn't wait for you to finish typing your reply. If you say "no", Emacs may ask again: @fileexample{ 1 modified buffer exists, do you really want to exit? (yes or no) } It is trying to make sure you aren't throwing changes away that you want. Think, and reply. If you havn't made any changes, Emacs just leaves without comment. @section(Trouble) Because there are so many command prefixes, it is easy to accidentally hit the wrong keys and find yourself in trouble. Here are some common problems and how to deal with them: @begin(itemize) To @b(undo) the command you last entered: @b(C-x u) (control-x, then just u). As you keep typing C-x u, it undoes earlier and earlier operations. To @b(cancel) a Emacs command: @b(C-g) (control-g). This is the "get me out of here" command. Try this when Emacs doesn't seem to be responding. Look on the bottom lines (the echo area). Is Emacs prompting you for information? C-g will cancel that, and most other uncomfortable situations. To @b(refresh) the screen because it's become garbled: @b(C-l) (control-l). @end(itemize) Perhaps the most confusing trouble you may encounter is if Emacs divides your screen in two to display long messages. The "Two Emacs Windows" section below explains how to deal with this. @section(Inserting Text) To insert text into the main buffer, @p(just type). Whatever you type is inserted @i(just before) where the cursor is. When you get to the end of the line, hit the @c(RETURN) key, just as you would on a typewriter, to get to the beginning of the next line. To insert a blank line, just hit @c(RETURN) twice. When you get to the bottom of the screen, Emacs automatically gives you more space to work with. You can correct the mistakes that you make while you type with the @c(DELETE) key, just as you do when typing commands to the Unix shell. You may notice two things as you type along. Every four or five lines, Emacs will say "Auto saving ... done" down in the bottom line echo area. This is a precaution to save your work in case the system crashes. It is @i(not) writing over your original file, but a backup copy called @b(#@p(filename)). If you type a closing parentheses ")", Emacs will hop the cursor over to the corresponding opening parentheses "(" briefly, then hop it back. This is because Emacs was written by programmers for whom matching up )'s with ('s is a major worry. @section(Moving the Cursor) The easiest way to move the cursor up, down, left, and right over your text is with the arrow keys. On the VT125 terminals, the arrow keys are in the upper right-hand part of the keyboard. On all other terminals, they are to the right of the main keyboard. Play with the arrow keys to get used to the peculiarities of their behavior. On a workstation, you can use the mouse cursor to move the emacs cursor. Point to a spot on the screen, then press the @i(middle mouse button). (On two-button mice, press both buttons.) Here is a summary of the common ways to move the cursor around: @begin(group) @begin(verbatim, font smallbodyfont) Move By Movement Command Character move right one character right arrow, or C-f move left one character left arrow, or C-b Lines move up one line up arrow, or C-p move down one line down arrow, or C-n jump to the end of the line C-e jump to be start of a line C-a Screens move to next screen of text C-v move to previous screen of text M-v (Escape-V) Buffers jump to the start of the buffer M-< (Escape-<) jump to the end of the buffer M-> (Escape->) Mouse cursor emacs cursor to mouse cursor middle mouse button @end(verbatim) @end(group) @section(Deleting and Killing Text) @blankspace(.1 incH) In Emacs parlance, @b(deleting) something means it is gone forever. @b(Killing) something means that it disappears from the buffer, but it can be @b(yanked) back again if you want it. Here are some common deletion commands: @begin(group) @begin(verbatim, font smallbodyfont) Unit Action Command Character delete the character before the cursor DELETE key delete the character the cursor is on C-d Lines kill a line forward from the cursor C-k kill the line and its trailing RETURN C-k C-k kill a complete line move to start of line enter two C-ks kill a line backward from the cursor enter C-u then 0 (zero) then C-k (C-u 0 C-k) @end(verbatim) @end(group) To @I(yank) back the last thing that you just killed, enter @b(C-y). @section(Two Emacs Windows) When Emacs wants to show you something that is too long to fit on its single-line echo area, it puts the text into a new @b(buffer), and displays the new buffer by dividing the screen into two @b(emacs windows). Many Emacs commands will do this, most notably the @b(help) command: @b(C-h). It looks like this when it happens: @blankspace(3 inch) This can be disconcerting the first few times it happens. It can be even more disconcerting when Emacs doesn't create a second window, but just displays the new buffer where it used to display your file. Your first reaction is "Oh no! My file's been overwritten!" No it hasn't. Everything's OK. You just have two buffers and windows where you used to have one. What you need to know is how to get back to where you started. This can always be accomplished by using from one to all of the following Emacs buffer/window commands: @begin(group) @begin(verbatim, font smallbodyfont) Return to one window mode, keeping the window the cursor is in: C-x 1 ("one") Move the cursor to the other window: C-x o ("oh") Display a buffer in the window the cursor is in: C-x b Show a list of all the buffers you have: C-x C-b @end(verbatim) @end(group) Notice that the most important thing to keep track of is @i(where the cursor is). @begin(enumerate) Try typing @b(C-g) (quit). It never hurts and sometimes helps. If your main buffer is showing on the screen, just make sure the cursor's in the main buffer window. If it isn't, then move it there with @b(C-x o) ("oh"). Type @b(C-x 1) to return to one window mode. If your main buffer isn't showing on the screen, you must get it on the screen. Type @b(C-x b) for "switch buffer." Emacs prompts: @example[switch to buffer: (default @i(something))] If @i(something) is the name of your main file, press RETURN. If it isn't, type the name of your main file and press RETURN. If you can't remember the name of your main file, @b(C-x C-b) will show you a list of all the buffers you have--while creating another buffer--like so: @blankspace(3 inch) Now type @b(C-x b) to switch to your main buffer. @end(enumerate) In any case, you can always just decide to leave Emacs with @b(C-x C-c). When it prompts with: @example[save file /mit/y/o/you/yourfile? (y or n)] type @b(y) and you won't have lost any work. @section(More Information) You should be able to create and edit files with just the information provided in @i(Essential Emacs). These are other GNU Emacs information sources: @begin(itemize) The Emacs help command @B(C-h) provides extensive assistance at the terminal. Its "apropos" subcommand @b(C-h a) is very useful. However, do not try it until you have read "Two Windows" above, or you may find that asking for help got you into more trouble than you started with. The @i(Emacs Quick Reference) card summarizes the information given here, plus many additional Emacs commands. Athena periodically teaches free Emacs minicourses. See the schedule in the clusters. The main @i(GNU Emacs Manual) describes all of Emacs in detail. It is available for reference in each cluster's manual racks. Copies are for sale for about $14 at the IS Publications Office in 11-209 (253-6325). There is an interactive tutorial that will try to teach you how to use Emacs. To use this tutorial, enter the C-h t command in Emacs, then just follow directions. You can get out of the tutorial at any time by entering C-x C-c, just as you would to exit any normal Emacs session. If it asks you to save "TUTORIAL", say @i(no). Decide for yourself if you want to save any other buffers it asks about. @end(itemize) @section(Appendix: Emacs on a Workstation) A @p(workstation) has an oversized, high-resolution, "bit-mapped" screen. This real screen can display multiple @p(windows), with something different happening in each one. The analogy is that your screen becomes like a desktop with many pieces of paper on it. The software that makes this happen is called the @p(X window system). When you use Emacs on a workstation, it creates a separate, new window for you to edit in. Beside the workstation is a little puck with two or three buttons on it called a @p(mouse). If you roll the mouse around on the tabletop, you'll see the @p(mouse cursor) move around on the screen. You use the mouse cursor to point to the window you want to type into. If the mouse cursor is outside @i(all) windows, the terminal seems dead. New window system users make this mistake frequently. Here is how to start Emacs on a workstation. @newpage @blankspace(3.25 inch) @tabclear @tabset(1.5 inch, 4.25 inch) @\@b(Mouse)@\@b(Workstation) @subsection(Start a Window Manager) Right after you login to the workstation, you should start a @p(window manager) program that will let you move and shuffle any windows that appear on your screen. Type: @example[xwm @b(&)] Don't forget the @b(&) before you hit RETURN. The system replies with something like: @example{[2] 15823} Which only means the window manager is now running. "Can't grab left mouse button" means you already have a window manager running and needn't start another. @subsection(The Ugly Part of the Story) The next two sections describe @i(Xhost) and @i(DISPLAY). @i(Xhost) and @i(DISPLAY) come into play when you @p(remote login) @i[(rlogin)] from one Unix system to another. If you are using a workstation in 4-035, 11-116, 37-xxx, 16-034, or one of the few private workstations, you @b(do not) have to worry about Xhost and DISPLAY @i(unless you @p(rlogin) to a timesharing system). If you do @i(rlogin) to a timesharing system (perhaps to send and read mail), then you must set both Xhost and DISPLAY. If you are using one of the older VAXstation-100 workstations in W20, 11-113, 1-142, 66, or 38 then you @b(do not) have to worry about Xhost, but you @b(do) always have to set DISPLAY. (The VAXstation-100s run the login server through which you remote login to a timesharing system.) If the next two sections seem a bit baroque and difficult to follow, it is because the procedure is, indeed, baroque and difficult to follow. All that is really happening is that you are telling both ends of a connection who's at the other end. Athena is trying to get rid of the necessity for these two steps. Xhost may be deactivated by mid-September 1986. @subsection(Set xhost Permission: XIO Broken Pipe) You only need to do this if you are on a workstation in 11-116, 4-035, 37-xxx, 16-034, or one of the few private workstations @b(and) you remote login @i[(rlogin)] to a timesharing host. Before you @i(rlogin) to the timesharing system, you must tell the workstation that it will be OK for that timesharing system to create windows on the workstation's display. If you don't, then you will get a message "XIO: Broken Pipe" when you try to start Emacs on the timesharing system. (The mail commands @i[comp] and @i[repl] start Emacs in passing.) Before you @i(rlogin), type this to the workstation: @example[xhost +@i(timesharinghost)] For example, @b(xhost +speaker) or @b(xhost +nessus). @i(xhost) is a security mechanism to prevent people from creating windows all over your workstation without your permission. Unfortunately, in practise it has served more to lock people out of their own workstations since most aren't aware that this mechanism is in play. You can put @i(xhost) commands in your workstation @i(.login) file for the timesharing systems you frequent. Typing @i(man xhost) will show more information. @subsection(Set the DISPLAY Environment Variable) Your @p(DISPLAY environment variable) has to be set correctly before you can start Emacs. As of September 8, 1986, you will have to set DISPLAY manually if you are using a VAXstation 100 in the W20, 11-113, 1-142, 66, and 38 timesharing clusters. The "real" workstations in 11-116, 4-035, 37-xxx, and 16-034 set DISPLAY correctly automatically when you login. You should not have to set it unless you subsequently @i(rlogin) to a timesharing system. Then you must set DISPLAY @i(on the timesharing system). If DISPLAY is not set, you will get an error message "DISPLAY environment variable must be set" when you try to start Emacs. If it is set incorrectly, you may get a message "No X," or you may not get any error, but the Emacs window never appears. To see how and if it's set, type: @example[printenv DISPLAY] No response except a system prompt means it is not set. If you need to set DISPLAY: @begin(enumerate) Before you login, look at the login banner @b(on the workstation). It will tell you the @i(hostname) and the @i(portnumber) of your display: @fileexample[Project Athena (@i{hostname}.MIT.EDU:ttyv@i{n} 5:36 p. on Mon 8 Sep 1986)] Write down what your workstation says. @i(hostname) may be something intelligible like @i(teela) or something that shows the host's location like @i(11-116-10). @i(n) is usually 0 or 1. Most workstations are also labeled with their hostname and portnumber. @begin(multiple) After you've logged in, type: @example[setenv DISPLAY @i(hostname:n)] Copy this carefully. "setenv" is all lowercase and all one word. "DISPLAY" is all uppercase. Replace @i(hostname:n) with the exact data for your display. (For example, @i{teela:1}, or @i{4-035-9:0}). If you are doing this because you've remote logged-in to a timesharing system, understand that you type this a) on the timesharing system, not the workstation, and b) you're giving the timesharing system the workstation's hostname. E.g., if you're on 4-035-9:0 and you @i(rlogin) to nessus, you DON'T type: @i(setenv DISPLAY nessus:0), you type: @i(setenv DISPLAY 4-035-9:0) @end(multiple) @end(enumerate) Setting DISPLAY tells a system where--on what machine and what port--to actually create the window. It is not practical to put the line in a @i(.login) file since you may be coming from any number of workstations. @subsection(Start Emacs) Now, to start Emacs, type: @example[emacs @i(anyfilename) @b(&)] This is the same as on a regular terminal, except you add the @b(&). Without the @b(&), you wouldn't be able to use your original login window for other things while you are in Emacs. There will now be a pause, and then you will see a spectral outline of an incipient window flickering from the mouse cursor. Move the mouse cursor to the upper left of the screen, leaving a few inches on the left, but flush at the top until the cursor won't go any higher. You are determining the upper left corner of the Emacs window. Now, incarnate the Emacs window in one of two sizes by pressing a mouse button: @itemize[ The @b(left) button will make a small, 80 column by 24 line Emacs window the same "size" as a regular terminal. The @b(right) button will make a large, 80 column by 65 line window the same size as your login window. ] See reverse. The middle button is for creating variable-size windows; see @i(Essential X). From here on, you use Emacs the same way as on a regular terminal. Exit with C-x C-c, and the Emacs window disappears. To shuffle a window to the "top," put the mouse cursor in that window and press Meta-right mouse button. You cannot use CTRL-z to suspend Emacs. (On a workstation, you don't need to; just move the mouse to a different window.) There are extra things you can do with Emacs and the mouse. See @i(man emacs) and the @i(Emacs Quick Reference) card. The window system is described in detail in the Athena document @i(Essential X) and briefly in the appendix to @i(Essential Unix) and on the @i(Unix Quick Refrence) card. @newpage @center[@b(A Big Window and Two Overlapping Small Windows)]