;;; -*- Package: USER; Base: 10; Mode: Text; Syntax: Common-lisp -*- ;;;> EXAMPLES-MESSAGE ;;;> ;;;>****************************************************************************************** ;;;> ;;;> Symbolics hereby grants permission to customer to incorporate ;;;> the examples in this file in any work belonging to customer. ;;;> ;;;>****************************************************************************************** INTRODUCTION ------------ You are looking at a ZMACS tutorial. Note: Press the Scroll key to see the next (and subsequent) pages. This tutorial is designed to help you become familiar with some of the basic Zmacs editing commands. It covers only a small subset of the commands available in Zmacs. Hopefully it will be enough to enable you to use Zmacs effectively. If you started the tutorial by typing Teach Zmacs in a Lisp Listener there are two special commands available to you. Pressing the — key (on the top row of the keyboard) will move you to the next section, and pressing • (to the left of —) will move you to the previous section. So if you already know the material in one section you can quickly skip over it and move to another section. The following sections are covered: 1. Introduction 9. Accessing Files 2. Basic Cursor Control 10. Editing Lisp Code 3. Inserting and Deleting 11. Compiling Lisp Code 4. Using the Kill History 12. Getting Help 5. Organization of the Screen 13. Regions 6. Searching 14. Using the Mouse 7. Extended Commands 15. Conclusion 8. Buffers Zmacs commands generally involve the CONTROL key or the META key or both keys held down simultaneously. Rather than write out META or CONTROL each time we want you to hold down one of those keys, we'll use the following abbreviations: c- means hold the CONTROL key and then press the character . Thus, c-F would be: hold the CONTROL key and type F. m- means hold the META key and press . c-m- means hold down both the CONTROL and META keys and press . c-sh- means hold down both the CONTROL and SHIFT keys and press . In this tutorial the characters ">>" at the left margin indicate directions for you to try using a command. For instance: >> Now type c-V (View next screen) to move to the next screen. From now on you'll be expected to do this whenever you have finished 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 c-V. To move backwards a screen, type m-V (press the META key and type V). >> Try typing m-V and then c-V to move back and forth a few times. The following commands are useful for viewing screenfuls: c-V Move forward one screenful m-V Move backward one screenful c-L Clear screen and redisplay everything putting the text near the cursor at the center. >> Find the cursor and remember what text is near it. Then type a c-L. Find the cursor again and see what text is near it now. >> Press the — key now to move to the next section. BASIC CURSOR CONTROL -------------------- From now on if you need Getting from screenful to screenful is useful, but how do you reposition the cursor within a given screen to a specific place? There are several ways you can do this. The most basic way is to use the commands previous, backward, forward and next. As you can imagine these commands (which are available in Zmacs as c-P, c-B, c-F, and c-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, c-P | Backward a character, c-B --- cursor --- Forward a character, c-F |  Next line, c-N 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 to you to learn them now. >> Do a few c-N's to bring the cursor down to this line. >> Move into the line with c-F's and then up with c-P's. Notice what c-P does when the cursor is in the middle of the line. >> Try to c-B at the beginning of a line. Do a few more c-B's. Then do c-F's back to the end of the line and beyond. When you go off the top or bottom of the screen, the text beyond the edge is shifted onto the screen so that your instructions can be carried out while keeping the cursor on the screen. >> Try to move the cursor off the bottom of the screen with c-N and see what happens. If moving by characters is too slow, you can move by words. m-F (Meta-F) moves forward a word and m-B moves back a word. >> Type a few m-F's and m-B's. Intersperse them with c-F's and c-B's. Notice the parallel between c-F and c-B on the one hand, and m-F and m-B on the other hand. Very often META 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). There is a similar parallel between lines and sentences: c-A and c-E move to the beginning or end of a line, and m-A and m-E move to the beginning or end of a sentence. >> Try a couple of c-A's, and then a couple of c-E's. Try a couple of m-A's, and then a couple of m-E's. Notice how repeated c-A's do nothing, but repeated m-A's keep moving farther. Two other simple cursor motion commands are m-< (Meta Less-than), which moves to the beginning of the file, and m-> (Meta 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 m-<. Otherwise, you would be typing m-, . Here is a summary of simple moving operations including the word and sentence moving commands: c-F Move forward a character c-B Move backward a character m-F Move forward a word m-B Move backward a word c-N Move to next line c-P Move to previous line c-A Move to beginning of line c-E Move to end of line m-A Move back to beginning of sentence m-E Move forward to end of sentence m-< Go to beginning of file m-> Go to end of file Most of these commands (and many others) are also recognized by other applications on the Lisp Machine, such as ZMAIL and CONVERSE. All except for m-A and m-E can be used in the Input Editor, which is used to take simple user input in virtually all programs on the Lisp Machine. >> Try all of these commands now a few times for practice. Since m-< and m-> will take you away from this screen, you can come back here with c-V's and m-V's. 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 Zmacs as text and inserted immediately. Type (the carriage-return key) to insert a line separator. You can delete the last character you typed by typing . 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, the line of text is "continued" onto a second screen line. The exclamation mark at the right margin indicates a line which has been continued. >> Use 's to delete the text until the line fits on one screen line again. The continuation line 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 continuation line. >> Type to insert the separator again. If you want to create a blank line in between two lines, move to the second of the two lines and type c-O. Notice what happens if you type c-O when the cursor is not at the beginning of a line. >> Try moving to a line and typing c-O now. >> Type c-D to delete the line separator inserted by c-O. You've now learned the most basic way of typing something in Zmacs and correcting errors. You can delete by words or lines as well. Here is a summary of the delete operations: Delete the character just before the cursor c-D Delete the character under the cursor m- Kill the word immediately before the cursor m-D Kill the next word after the cursor c-K Kill from the cursor position to end of line CLEAR-INPUT Kill from the cursor position to the beginning of the line Notice that and c-D vs m- and m-D extend the parallel started by c-F and m-F. USING THE KILL HISTORY ---------------------- Now suppose you kill something (with c-K for example), and then you decide that you want to get it back. Well, whenever you kill something bigger than a character, Zmacs saves it for you in what is called the Kill History. To yank it back, use c-Y. Note that you don't have to be in the same place to use c-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. >> Type c-N a couple of times to position the cursor at some line on the screen and kill that line with c-K. Note that a single c-K kills the contents of the line, and a second c-K kills the line itself and makes all the other lines move up. 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 c-Y. >> Try it; type c-Y to yank the text back. Think of c-Y as if you were yanking something back that someone took away from you. Notice that if you do several c-K's in a row the text that is killed is all saved together so that one c-Y will yank all of the lines. >> Do this now, type c-K several times. Now to retrieve that killed text: >> Type c-Y. Then move the cursor down a few lines and type c-Y again. You now see how to copy some text. What do you do if you have some text you want to yank back, and then you kill something else? c-Y would yank the more recent kill. But the previous text is not lost. You can get back to it using the m-Y command. After you have done c-Y to get the most recent kill, typing m-Y replaces that yanked text with the previous kill. Typing m-Y again and again brings in earlier and earlier kills. When you have reached the text you are looking for, you can just go away and leave it there. If you m-Y enough times, you come back to the starting point (the most recent kill). >> Kill a line, move around, kill another line. Then do c-Y to get back the second killed line. Then do m-Y and it will be replaced by the first killed line. Do more m-Y's and see what you get. Keep doing them until the second kill line comes back, and then a few more. ORGANIZATION OF THE SCREEN -------------------------- Zmacs divides its window into several areas: the editor window, the echo area, and the mode line, each of which contains its own type of information. Not surprisingly, the EDITOR WINDOW shows the text you are editing. The ECHO AREA is the area at the bottom of the screen where Zmacs displays the commands you have typed. The MINIBUFFER is an area within the echo area where you will be prompted for more information if it is needed. The line above the echo area is known as the MODE LINE. Its purpose is to display information about the current buffer. Right now the Mode Line should look something like this: ZMACS (Text) teach-zmacs-copy.text >username CASCADES: (1) * [More below] The word in parentheses indicates what mode Zmacs is in. If Zmacs is in Text Mode it is set up to edit lines of text only. If it is in Lisp Mode, Zmacs will do some things that are specifically related to editing Lisp code, like automatically indenting code correctly. To the right of the mode indicator is the buffer name. If the buffer is associated with a file the buffer name is rearranged with the filename first and the directory and host at the end. After the buffer name comes the buffer's version number (in parentheses). This is the version number of the file most recently visited or saved. An asterisk to the right of the version number means that the contents of the buffer have been modified. When you request some information from Zmacs or if Zmacs needs to display a warning message, it will display the information in a typeout window. The typeout window temporarily overlays the text in the editor window, using as much room as it needs. To get rid of the typeout window just press . >> Press the † key and then type an L. This will display the last 60 characters you typed in the typeout window. Press to remove the display. SEARCHING --------- Very often you will want to move to a portion of your buffer but you aren't quite sure where it is. It would be nice to be able to quickly search through the buffer to find the right place without having to use c-V's and m-V's to scroll through the pages. Zmacs has two commands to do just that, called Incremental Search (invoked by c-S) and Reverse Incremental Search (c-R). >> Move the cursor to the beginning of this line. Try searching backwards for the word "the". Type c-R to get the "Reverse I-Search: " prompt, and start typing "the". If you type it slowly you will notice that as soon as you type the "t" the cursor will move back to the first "t" it can find. When you type the "h" it will move back to the first occurrence of "th" and so on. Once you have finished typing the whole word, type c-R again. The cursor will move to the next occurrence of "the". You can type c-R any number of times. Type c-G to stop searching and return the cursor to where it was when you started. >> Move the cursor to this line. Try searching forward for the word "and". This time when you type c-S you will get a "I-Search: " prompt, and should type "and". Type c-S a few times to go to forward to the next occurrences of "and". Now, before typing c-G to stop searching, type c-R. You have now changed from doing an Incremental Search to a Reverse Incremental Search. Type c-R and c-S a few times and then type c-G to quit searching. Obviously you won't always want to return the cursor to where it was before you started searching. In such a case you should press the key when you have found the text you were searching for. >> Move the cursor to this line and search forward for "extend". Press the key to finish the search. Notice that alphabetic case has no effect on the searching commands. EXTENDED COMMANDS ----------------- There are many more commands in Zmacs than could possibly be remembered if they were all invoked via CONTROL and META characters. Zmacs gets around this by using extended commands. An example of this is Count Lines, which counts the number of lines in the buffer. When you type m-X, Zmacs prompts you in the minibuffer to type the name of the extended command; in this case, "Count Lines". Press and the command will be executed. >> Try it now. Type m-X. When you see the "Extended command:" prompt in the minibuffer type "count lines" (without the quotes). The answer will be printed in the echo area and the cursor will return to where it was before you typed m-X. Some Extended commands require that you give them more information to work with. In this case Zmacs will prompt you to enter more information after you have typed the name of the command and pressed . An example of a command that needs more input is Replace String. >> Move the cursor to the blank line two lines below this one. Then type m-X Replace String zebra giraffe Notice how the following sentence has changed: you've replaced the word z-e-b-r-a with the word giraffe wherever it occurs after the cursor. The ZEBRA is one of the tallest animals in the world! The more customary command for replacing strings is the Query Replace command, which has many options. [You can see a full description of how to use Query Replace by pressing the † key while in the middle of replacing some text.] Another whole set of commands are available in Zmacs by typing a sequence of two characters. The first character for this type of command is always c-X. After you type c-X, Zmacs will prompt you to enter the second character in the sequence. When the "Control-X: " prompt appears in the minibuffer you can enter the second character. c-X commands will be denoted by putting the two characters one after the other. For example c-X B or c-X c-S. >> Type c-X c-B. c-X c-B will display a list of all Zmacs buffers at the top of the screen. Press to get rid of the display. To get a list of all c-X commands type c-X †. BUFFERS ------- You do all your text editing in Zmacs buffers, which are temporary workspaces that can hold text. To keep any text permanently, you must save it in a file. Zmacs can accommodate any number of buffers. When you first enter Zmacs, it creates an empty buffer for you, usually called *Buffer-1*. To create other buffers, use the c-X c-F (Find File) command to create either an empty buffer or a buffer containing a file. Find File will ask you to enter a filename and will go off to look on the disk for that file. If it finds the file, it will read the contents of the file into a new buffer. If the file is not found, Zmacs will create an empty buffer with that file name associated with it. Since trying this command would involve leaving the tutorial don't try it now unless you know how to switch between buffers. c-X c-F is covered in the section called "Accessing Files". >> Display the list of buffers again with c-X c-B. There should be at least two buffers in the list, including this one and a buffer called something like *Buffer-1*. It's not uncommon for a programmer to have a list of ten or more buffers. The buffer at the top of the list is always the currently selected buffer. If you move the mouse over the list of buffers you will notice that they are mouse sensitive. The simplest way of selecting another buffer is to use c-X c-B and then click left on the buffer you want to select. >> Try switching between two buffers AFTER reading these instructions. 1. Type c-X c-B (or m-X List Buffers) 2. Move the mouse over *Buffer-1* and click left. 3. Type c-X c-B 4. Move the mouse over the buffer called "teach-zmacs-copy.text >user Cascades:" (or something very similar) and click left. If you can read this you made it! ACCESSING FILES --------------- After you are finished editing a file you will want to save it on disk again. It is also a good idea to occasionally save the file in case of a power failure or some other mishap. To save the contents of a buffer, use the command c-X c-S. If the current buffer is already associated with a file then the contents of the buffer will be saved onto that file, but if the buffer isn't associated with any file Zmacs won't know where to save it and will ask you for a filename. >> Save this file, using c-X c-S. If you haven't made any modifications to the buffer Zmacs will just inform you that "no changes need to be written". If you made some changes to the buffer, saving it will cause two changes in the mode line. The version number (in parenthesis) will increment by one so that it reflects the version of the file you are editing, and the asterisk will disappear until you make another change to the buffer. Often a person will read a file in to a Zmacs buffer, and after editing for a while, will decide that they want to save it to a different place. For example, they might decide to save it in a different directory or on a different host. The c-X c-W command does just that. Using c-X c-W tells Zmacs to ask you for a new filename before saving the buffer. In the next example you will save this buffer under a different filename. >> Type c-X c-W. Zmacs will prompt you for more information in the minibuffer while displaying a default filename. Just type "teach-zmacs-copy-2" (without the quotes) and press . Once the buffer has been saved, look at the mode line. Notice that the buffer name has changed to reflect the new filename. If you want to begin editing a file that you have on disk, use the command c-X c-F (Find File). Read through the next example before trying it. You will find a file (your init file) and then reselect this buffer. If you haven't tried this before you might want to write down the four steps below. >> Find a file and then return to this buffer. 1. Type c-X c-F. 2. At the prompt type "lispm-init.lisp" and press . 3. When your init file is displayed type c-X c-B to List Buffers. 4. Move the mouse over the buffer called "teach-zmacs-copy-2.text" and click left. EDITING LISP CODE ----------------- The first thing you should do before starting to edit Lisp code is to make sure that your buffer is in Lisp Mode. >> Type m-X Lisp Mode. Answer Y to the question it asks. Notice the change in the mode line to say (LISP) instead of (Text). When a Zmacs buffer is in Lisp Mode it will automatically do two things: 1. When the cursor is immediately to the right of a close parenthesis, the matching open parenthesis will blink. This can be extremely helpful, as Lisp code tends to contain many levels of parentheses. 2. Lisp code will be automatically indented in a standard way when you press either the or key instead of pressing at the end of a line. Here is an example of a function written while in Text Mode: (DEFUN FUNCTION-1 (NUMBER) (LET ((SUM 0)) (LOOP FOR I FROM 1 TO NUMBER DO (SETQ SUM (+ SUM I))) SUM)) Here is the same function written while in Lisp Mode: (DEFUN FUNCTION-2 (NUMBER) (LET ((SUM 0)) (LOOP FOR I FROM 1 TO NUMBER DO (SETQ SUM (+ SUM I))) SUM)) >> Move the cursor through FUNCTION-2 with c-F's and m-F's noticing which parentheses blink. (Make sure you are in Lisp Mode.) >> Move the cursor to the second line of FUNCTION-1. It should say "(LET ((SUM 0))". Press the key. >> Move to the end of the first line of FUNCTION-1 and press the key. This has the same effect as pressing and then pressing the key. It indents the line correctly. Zmacs has some commands that operate on Lisp forms. In general these commands involve holding down both the CONTROL and META keys. c-m-F moves the cursor "forward" one Lisp form and c-m-B moves "backward" a form. >> Move the cursor to the line below and type a few c-m-F's and c-m-B's. Intersperse them with some c-F's and c-B's. (foo) a-long-variable-name '() two words "this *or* that" (("foo bar baz")) COMPILING LISP CODE ------------------- Before testing any code you have written in the editor, you must compile it. The simplest way to compile your code is to use m-X Compile Buffer, but you probably don't want to try it now since this buffer contains mostly text and you would get a lot of error messages. One of the nice features of the Lisp Machine is incremental compilation. This means that if you make changes to only one part of your code, you don't have to recompile the whole program, only the part that has been changed. For example, to compile one definition, move the cursor onto that definition and type c-sh-C (Control-shift-C). >> Move the cursor into the middle of the following definition and type c-sh-C. In the echo area Zmacs will tell you that it is compiling the function TEST-1. (DEFUN TEST-1 () (LET ((LIST '(A B C D E F G))) (PRINC LIST))) If you make changes to several definitions and decide you want to compile them but you don't want to compile the entire buffer you can use the command m-sh-C (Meta-shift-C). This will compile only the definitions that have been modified in some way. If it is easier for you to remember extended commands, the same command can be invoked by typing m-X Compile Changed Definitions of Buffer (remember to take advantage of completion for this command). Again, don't try this command here since you will get many error messages. Summary of the compiling commands: c-sh-C Compile the current definition m-sh-C Compile changed definitions of buffer m-X Compile Buffer Compile the entire buffer GETTING HELP ------------ You can get help in Zmacs by pressing the † key. If you press the † key when Zmacs isn't currently executing a command, a list of characters for you to choose from will be displayed in the minibuffer. Zmacs will give you a different kind of help depending on which choice you make. >> Type † L to look at the last 60 characters you typed. (Type †, let go, then type L.) A common problem when learning Zmacs is knowing what you want to do but not knowing the best way to accomplish it. You can usually guess part of the name of a command by the action it performs. As an example, assume you want to make a hardcopy of the contents of a buffer. To get a listing of all commands that relate to making hardcopies you can type † A (also invoked by m-X Apropos) and then type in the word "hardcopy". This will display a list of commands in the typeout window with information about what the command does and how to invoke it. >> Type † A hardcopy. To get rid of the text that is displayed by this command just press . Try using † A on some other likely words such as "compile", "change", and "list". To show the long description of what a command does use † C. Even if you know what a command does, † C will often show other ways of using a command. It may also reveal that the command acts differently when given a numeric argument. >> Type † C. Then type c-V. † C also works on extended commands and c-X commands. It will first explain what m-X or c-X does and then will prompt you to enter the rest of the command. >> Use † C on the following commands. c-sh-C c-X c-F m-X Compile Buffer m-X Append To File If you type † when you are in the middle of entering an extended command, Zmacs will display all of the possible completions of the text you have typed. If you simply type m-X † Zmacs will offer to display a list of ALL extended commands (there are 248 of them). If you type c-X † a list of all c-X commands and what they do will be displayed. >> Begin entering the extended command m-X Count Lines, but before typing "lines" press the † key. This should display a list of all extended commands that begin with the word "count". Notice that the items in the list are mouse sensitive. If you point at one of the items and click the mouse, that command will be executed. Click on the command "Count Words". REGIONS ------- There are many Zmacs commands for operating on regions. A region consists of a block of text within the buffer that you want to manipulate as a single entity. Zmacs has two "buffer pointers" called POINT and MARK which keep track of the boundaries of the current region (if any). POINT is always the location under the cursor. MARK points to the other end of the region and is always invisible. A region is shown on the screen by underlining the text between POINT and MARK. You can create a region using either the mouse or the keyboard. How to create a region with the mouse is explained in the next section: Using the Mouse. To create a region with the keyboard press c- to mark the beginning of the region (recall POINT and MARK) and then move the cursor with any of the movement commands. As the cursor moves the region will grow or shrink to fit between the cursor (POINT) and the other end of the region (MARK). Now try these exercises with regions: >> Create a region with the keyboard. Type c- and then move the cursor down a few lines with c-N. Now type m-X Count Lines. Some commands act differently when there is a region. >> Type c-X c-X to exchange POINT and MARK, and enlarge the region in the other direction >> Create a region from the cursor to the beginning of the buffer by typing c-< (Control-shift-comma). >> Create a region from the cursor to the end of the buffer by typing c->. Other things to know about regions: - When creating a region via the keyboard you may find it useful to use the command c-X c-X to move the cursor to the other end of the region. That way you can extend (or shorten) the region in either direction. - Type c-G or ABORT to deactivate (un-underline) a region. Some common commands that use regions: - m-X Hardcopy Region - m-X Compile Region (or c-sh-C) - m-X Format Region - c-W (Kill Region, also called Wipe Region) - m-W (Save Region on kill history without deleting it) USING THE MOUSE --------------- Some operations are easier to perform with the mouse than with the keyboard. For example, to position the cursor anywhere on the screen just point the mouse at that location and click left. If you have to move the cursor more than a few lines then this can be especially useful. >> Use the mouse to move the cursor to here  . To create a region with the mouse simply point to the area where you would like the region to begin, click the left mouse button and hold it down while moving the mouse to the other end of the region, and let up the mouse button to finish specifying the region. This is the fastest (and probably most often used) way of creating a region, but it is limited in that it doesn't provide a convenient way to create a region that contains more text than will fit on one screen. >> Position the mouse somewhere in the middle of the screen. Now hold down the left button while moving the mouse to another location. Let up the mouse button to finish creating the region. Before doing anything else type c-X c-U to change your region to all uppercase characters. The middle mouse button can be used to mark (make into a region) the current thing the mouse is pointing at. What that "thing" is depends on the mode Zmacs is in. When in text mode clicking middle marks words, sentences, paragraphs and lines. When in Lisp mode clicking middle marks lisp forms. >> Make sure Zmacs is in Text Mode (if necessary use m-X Text Mode). Hold down the middle button and slowly move the mouse around the screen. Look carefully at what the mouse makes into a region. >> Now use m-X Lisp Mode to switch to Lisp Mode. Hold down the middle button again and move the mouse slowly over the example Lisp code below. Be sure to notice the differences between what happens with this command in Text Mode and in Lisp Mode. (si:hardcopy-text-file "F:>cwh>proposal.text" si:*default-hardcopy-device* :interpret-font-changes t :fonts '("timesroman10" "timesroman10b")) Clicking right produces a menu of commonly used commands. You may find it more convenient to use this menu than to invoke those commands via the keyboard. CONCLUSION ---------- Hopefully this tutorial has given you at least a basic knowledge of how to use the Zmacs editor. The commands covered here are only a small subset of the commands available to you in Zmacs. As you use the editor take time to explore new commands and try new things. The editor is one of the most commonly used tools on the Lisp Machine and learning to use it efficiently is worth the effort! A word to the wise: If you find yourself saying "I wish there was a way to do this faster", then there probably is. Only when you know that you're wasting time doing 30 c-F's in a row is it worth it to find out about c-E. The same thing is true with more advanced commands.