You are looking at the EMACS tutorial. This file is TUTORIAL.TXT. For best effect, you should read this from inside EMACS. To start EMACS inside Forth, type edit . To start EMACS from the destop, double-click the EMACS.TOS icon. Once EMACS is running, type ^X^V tutorial.txt . The next paragraph tells what ^X^V means. EMACS commands generally involve the Control key or the Esc key (Esc stands for Escape). Rather than write out ESCAPE or CONTROL each time we want you to prefix a character, we'll use the following abbreviations: ^ means hold the Control key while typing the character Thus, ^F would be: hold the Control key and type F ESC- means type , release it, then type the character Important note: if you must exit at some point, type ^X^A. The characters ">>" at the left margin indicate directions for you to try using a command. For instance: >> Now type ^V (View next screen) to move to the next screen. (go ahead, do it by depressing the Control key and V together). From now on, you'll be expected to do this whenever you finish reading the screen. Note that there is an overlap when going from screen to screen; this provides some continuity when moving through the file. The first thing that you need to know is how to move around from place to place in the file. You already know how to move forward a screen, with ^V. To move backwards a screen, type ESC-v. >> Try typing ESC-v and then ^V to move back and forth a few times. NOTE: In EMACS, ESC-v and ESC-V are two different commands. They may do the same thing, or they may not. All of the ESC- commands listed in this tutorial use the lower case form of the command. However, CONTROL characters do not come in separate lower case and upper case forms, so there is no distinction between ^v and ^V. Conventionally, CONTROL characters are written using the upper case letter, as in ^V or ^X, but you need not hold down the shift key to type a CONTROL character. SUMMARY ------- The following commands are useful for viewing screenfuls: ^V Move forward one screenful ESC-v Move backward one screenful ^L Clear screen and redisplay everything. ^L is used to fix the screen display if it gets messed-up for some reason. BASIC CURSOR CONTROL -------------------- Getting from screenful to screenful is useful, but how do you reposition yourself within a given screen to a specific place? There are several ways you can do this. One way (not the best, but the most basic) is to use the commands previous, backward, forward, and next. As you can imagine, these commands (which are given to EMACS as ^P, ^B, ^F, and ^N respectively) move the cursor from where it currently is to a new place in the given direction. Here, in a more graphical form are the commands: Previous line, ^P (or up-arrow) : : Backward, ^B .... Current cursor position .... Forward, ^F (or left-arrow) : (or right-arrow) : Next line, ^N (or down-arrow) You'll probably find it easy to think of these by letter: P for previous, N for next, B for backward and F for forward. These are the basic cursor positioning commands and you'll be using them ALL the time so it would be of great benefit if you learn them now. You can use the arrow keys if you prefer (but the control keys can be typed without moving your hands!). >> Do a few ^N's to bring the cursor down to this line. >> Move into the line with ^F's and then notice what ^P does when the cursor is in the middle of the line. EMACS pretends that lines are separated by a single Linefeed character, although the Atari system actually stores a Carriage Return, Linefeed pair at the end of each line in a file. >> Try to ^B at the beginning of a line. Do a few more ^B's. Then do ^F's back to the end of the line and beyond. On some systems, you can also use the arrow keys to move around. If your keyboard has arrow keys, try them out now. When you go off the top or bottom of the screen, the text beyond the edge is shifted onto the screen so that the cursor is always visible. >> Try to move the cursor off the bottom of the screen with ^N and see what happens. If moving by characters is too slow, you can also move by words. ESC-f moves forward a word and ESC-b moves back a word. Remember that ESC has to be typed and released, rather than being held down like with the CONTROL key. >> Type a few ESC-f's and ESC-b's. Intersperse them with ^F's and ^B's. Notice the parallel between ^F and ^B on the one hand, and ESC-f and ESC-b on the other hand. Very often Escape characters are used for operations related to English text whereas Control characters operate on the basic textual units that are independent of what you are editing (characters, lines, etc). Two other simple cursor motion commands are ESC-< (Escape Less-than), moves to the beginning of the file, and ESC-> (Escape Greater-than), which moves to the end of the file. You probably don't need to try them, since finding this spot again will be boring. If you need the shift key to type a "<", then you must also use the shift key to type ESC-<. Otherwise, you would be typing ESC-,. The location of the cursor in the text is also called "point" or "dot". To paraphrase, the cursor shows on the screen where point is located in the text. Here is a summary of simple moving operations including the word and sentence moving commands: ^F Move forward a character ^B Movard a character ESC-f Move forward a word ESC-b Move backward a word ^N Move to next line ^P Move to previous line ^A Move to beginning of line ^E Move to end of line ^X^P Scroll window back, showing previous line ^X^N Scroll window forward, showing next line ESC-, Go to beginning of window ESC-. Go to end of window ESC-< Go to beginning of file ESC-> Go to end of file >> Try all of these commands now a few times for practice. Since the last two will take you away from this screen, you can come back here with ESC-v's and ^V's. These are the most often used EMACS commands. Like most other commands in EMACS, these commands can be given arguments which cause them to be executed repeatedly. The way you give a command a repeat count is by typing a ^U and then the number before you type the command. Typing ^U without any digits will give a multiple of 4. That is, one ^U gives an argument of 4, two ^U's gives an argument of 16, etc. For instance, ^U 8 ^F moves forward eight characters, while ^U ^U ^F moves forward sixteen characters. >> Try giving a suitable argument to ^N or ^P to come as close as you can to this line in one jump. QUITTING FROM COMMANDS ---------------------- The character used in EMACS to quit out of all commands which request input is ^G. For example, you can use ^G to discard a numeric argument or the beginning of a command that you don't want to finish. >> Type ^U 100 to make a numeric arg of 100, then type ^G. Now type ^F. How many characters does it move? If you have typed an by mistake, you can get rid of it with a ^G. ERRORS ------ Sometimes you may do something which EMACS doesn't allow. If it is something simple, such as typing a control key sequence which is not associated with any command, EMACS will just beep at you. Otherwise, EMACS will also display an informative error message. INSERTING AND DELETING ---------------------- If you want to type text, just do it. Characters which you can see, such as A, 7, *, etc. are taken by EMACS as text and inserted immediately. The key may also be typed as a ^H. More generally, deletes the character immediately before the current cursor position. >> Do this now, type a few characters and then delete them by typing a few times. Don't worry about this file being changed; you won't affect the master tutorial. This is just a copy of it. >> Now start typing text until you reach the right margin, and keep typing. When a line of text gets too big for one line on the screen, a dollar sign at the right edge indicates that there are more characters to the right of the screen. >> Use 's to delete the text until the line fits on one screen line again. The dollar sign goes away. >> Move the cursor to the beginning of a line and type . This deletes the line separator before the line and merges the line onto the previous line. The resulting line may be too long to fit, in which case it has a dollar sign at the right margin. >> Type to insert the separator again. Remember that most EMACS commands can be given a repeat count; Note that this includes characters which insert themselves. >> now -- type ^U 8 * and see what happens. If you want to create a blank line in between two lines, move to the second of the two lines and type ^O. >> Try moving to a line and typing ^O now. You've now learned the most basic way of typing something in EMACS and correcting errors. You can delete by words or lines as well. Here is a summary of the delete operations: ^H () delete the character just before the cursor ^D delete the next character after the cursor ESC-h kill the word immediately before the cursor ESC-d kill the next word after the cursor ^K kill from the cursor position to end of line Notice that ^H and ^D vs. ESC-h and ESC-d extend the parallel started by ^F and ESC-f. Now suppose you kill something, and then you decide that you want to get it back? Well, whenever you kill something with ^K, EMACS saves it for you. To yank it back, use ^Y. Note that you don't have to be in the same place to do ^Y; This is a good way to move text around. Also note that the difference between "Killing" and "Deleting" something is that "Killed" things can be yanked back, and "Deleted" things cannot. For instance, type ^N a couple times to postion the cursor at some line on this screen. >> Do this now, move the cursor and kill that line with ^K. Note that a single ^K kills the contents of the line, and a second ^K kills the line itself, and make all the other lines move. The text that has just disappeared is saved so that you can retrieve it. To retrieve the last killed text and put it where the cursor currently is, type ^Y. >> Try it; type ^Y to yank the text back. Think of ^Y as if you were yanking something back that someone took away from you. Notice that if you do several ^K's in a row the text that is killed is all saved together so that one ^Y will yank all of the lines. >> Do this now, type ^K several times. Now to retrieve that killed text: >> Type ^Y. Then move the cursor down a few lines and type ^Y again. You now see how to copy some text. The region doesn't have to fit all on one screen. You can set the mark somewhere, then move anywhere else in the file and the mark will still be where you set it. REGIONS ------- Suppose that you want to move a whole bunch of lines from one place to another. You could use a lot of ^K's to kill the lines and then yank them back somewhere else with ^Y, but that could get tiresome if you really have a lot of lines to move. There is a better way. Emacs has a thing called the "region". The region is everything between the cursor and another place in the buffer. The other place is called the "mark". To set the mark, you use ^, i.e. hold down the CONTROL key and type the space bar. >> Try typing ^ . Notice the "[Mark set]" at the bottom. Now if you move the cursor somewhere else, the mark will stay at the place where the cursor was when you typed the ^ . You can find out where the mark is with ^X^X . ^X^X swaps the cursor and the mark. >> Move the cursor a few spaces forward and then type ^X^X several times. Notice how the cursor jumps back and forth. The region is everything between the cursor and the mark. It doesn't matter which is first; the cursor can be either before or after the mark. You can kill the region with ^W . >> Type ^X^X to remind yourself where the region is, then type ^W and watch it disappear. Type ^Y to yank it back. As with ^K, you can yank killed text back at some place other than where you killed it. If you kill the region with ESC-w instead of ^W, the region won't disappear, but you will still be able to yank it back somewhere else. This is a good way to make several copies of something. Just grab the region with ESC-w, then put a copy of it somewhere else with ^Y. If you want several copies, just keep typing ^Y. Here is a summary of the region operations: ^ set the mark ^X^X exchange the mark and the cursor ^W kill the region (between the mark and the cursor) ESC-w kill the region without making it go away FILES ----- In order to make the text you edit permanent, you must put it in a file. Otherwise, it will go away when your invocation of EMACS goes away. You put your editing in a file by "visiting" the file. What visiting means is that you see the contents of the file in your EMACS; and, loosely speaking, what you are editing is the file itself. However, the changes still don't become permanent until you "save" the file. This is so you can avoid leaving a half-changed or incorrect file around when you don't want to. If you look near the botton of the screen you will see a line that looks like " -- ForthEMACS -- tutorial.txt -- File: tutorial.txt". The "tutorial.txt" refers to the name of the buffer that you are currently using, your own temporary copy of the text of the EMACS tutorial. The "File: tutorial.txt" refers to the name of the file that is associated with the buffer. This is the disk file that will be written if you "save" the file. The buffer name is not necessarily the same as the file name; for instance, it is possible to read a different file into an already-exiting buffer. The commands for visiting and saving files are unlike the other commands you have learned in that they start with a different character. They both start with the character Control-X. There is a whole series of commands that start with Control-X; many of them have to do with files, buffers, and related things, and all of them consist of Control-X followed by some other character. Another thing about the command for visiting a file is that you have to say what file name you want. We say the command "reads an argument from the terminal" (in this case, the argument is the name of the file). After you type the command ^X^V Visit a file EMACS will ask you for the file name. You should end the name with the Return key. After this command, you will see the contents of the file in your EMACS. You can edit the contents. When you wish to make the changes permanent, issue the command ^X^S Save the file A new version of the file will be created. When the operation is finished, EMACS displays a message. If you forget to save a file, then visit a different file, EMACS will not throw away the changes you have made to the first file. You can go back to the first file and save it whenever you want. GETTING OUT AND QUITTING ------- --- --- -------- The command to tell EMACS that you'd like to stop editing is ^Z. This puts you back in Forth where you can do whatever you want. You can then get back into EMACS by typing "edit", which will put you back in EMACS just where you left off. ^Z automatically saves the file your are editing. If you do not want your file to be saved before you go back to Forth, you can use ^X^A instead of ^Z. If you want to save your file and stay in EMACS, you can use ^X^S. If you want EMACS to really go away (giving back its memory), but you want to stay in Forth, you can use the Forth command "unload-emacs". This doesn't automatically save any files. MODE LINE --------- At the bottom of the screen is an area called the echo area or mini-buffer. The echo area contains the bottommost line of the screen. The line immediately above them is called the MODE LINE. The mode line says something like: -* ForthEMACS -- tutorial.txt -- File: tutorial.txt This is a very useful "information" line. The star means that you have made changes to the text. Right after you visit or save a file, there is no star. The first name "tutorial.txt" is the name of this buffer. It is usually (but not always) the same as the name of the file you are editing. "File: tutorial.txt" means that this buffer is associated with the file named "tutorial.txt". A buffer does not have to be associated with a file. EDITING TWO FILES AT ONCE ------- --- ----- -- ---- You don't have to get in and out of EMACS every time that you want to edit another file. Just use ^X ^V to visit the next file. If you want to look at 2 files at the same time, you can split the screen in half with ^X 2 . To get back to just one window, type ^X 1 . >> Type ^X 2 to split the screen into 2 windows. Once you have 2 windows, you can switch back and forth between them with ^X n . >> Type ^X n several times to switch between the windows. Try using ^V and ESC v in one of the windows. Note that they scroll independently of one another. Once you have 2 windows, you can look at a different buffer in each window. To switch to a different buffer, use ^X ^O . Pieces of text may be moved from one window to another using the ^K , ^W , and ^Y commands that you have already learned. Just kill the text in one window, switch windows using ^X n , then yank the text back into the other window. You can have more than 2 windows if you want. Try typing ^X 2 inside a window that has already been split. >> Type ^X 1 to get back to one window. RUNNING OUT OF MEMORY ------- --- -- ------ Sometimes when you have been editing for a long time, EMACS will run out of memory. When this happens you can get some back with a command which allows you to throw away buffers that you are not using anymore. Another command allows you to see which buffers you have. >> Type ^X ^B to see which buffers you have. This will split the screen into 2 windows; remember the ^X 1 command to get back to 1 window. You can throw away a buffer with ^X k . You will be asked which buffer you want to throw away. You can't throw away a buffer that is currently being displayed on the screen, so you may need to first use ^X ^O to switch to a different buffer. Unfortunately, if you have already run out of memory, sometimes ^X^B won't work (it needs memory too). If so, switch to the buffer "main" with ^X ^O main , then use ^X k to throw away the buffer you were viewing when Emacs ran out of memory. If you have made changes to that buffer and you don't want to lose them, throw out some other buffer instead (remember the name of a file you have recently edited and toss it). GETTING HELP ------- ---- The file EMACS.REF contains a complete list of EMACS commands grouped by function. CONCLUSION ---------- Remember, to exit use ^X^A. You'll probably find that if you use EMACS for a few days you won't be able to give it up. Initially it may give you trouble. But remember that this is the case with any editor, especially one that can do as many things as EMACS. ACKNOWLEDGEMENTS ---------------- Over the years, versions of EMACS have been written for many different machines. Many, many people have contributed to the development of EMACS. In particular, Richard Stallman wrote the very first version. The EMACS used in File Forth is derived from a version called MicroEMACS, which was written by Dave Conroy.