*** empty log message ***
[emacs.git] / etc / TUTORIAL
blob98e1243837ade487c8e35d0ada1cced717f7dbe2
1 Copyright (c) 1985 Free Software Foundation, Inc;  See end for conditions.
3 You are looking at the Emacs tutorial.
5 Emacs commands generally involve the CONTROL key (sometimes labelled
6 CTRL or CTL) or the META key (sometimes labelled EDIT).  Rather than
7 write out META or CONTROL each time we want you to prefix a character,
8 we'll use the following abbreviations:
10  C-<chr>  means hold the CONTROL key while typing the character <chr>
11           Thus, C-f would be: hold the CONTROL key and type f.
12  M-<chr>  means hold the META or EDIT key down while typing <chr>.
13           If there is no META or EDIT key, type <ESC>, release it,
14           then type the character <chr>.  "<ESC>" stands for the
15           key labelled "ALT" or "ESC".
17 Important note: to end the Emacs session, type C-x C-c.  (Two characters.)
18 The characters ">>" at the left margin indicate directions for you to
19 try using a command.  For instance:
20 <<Blank lines inserted here by startup of help-with-tutorial>>
21 >>  Now type C-v (View next screen) to move to the next screen.
22         (go ahead, do it by depressing the control key and v together).
23         From now on, you'll be expected to do this whenever you finish
24         reading the screen.
26 Note that there is an overlap when going from screen to screen; this
27 provides some continuity when moving through the file.
29 The first thing that you need to know is how to move around from
30 place to place in the file.  You already know how to move forward a
31 screen, with C-v.  To move backwards a screen, type M-v (depress the
32 META key and type v, or type <ESC>v if you don't have a META or EDIT
33 key).
35 >>  Try typing M-v and then C-v to move back and forth a few times.
38 SUMMARY
39 -------
41 The following commands are useful for viewing screenfuls:
43         C-v     Move forward one screenful
44         M-v     Move backward one screenful
45         C-l     Clear screen and redisplay everything
46                  putting the text near the cursor at the center.
47                  (That's control-L, not control-1.
48                   There is no such character as control-1.)
50 >> Find the cursor and remember what text is near it.
51    Then type a C-l.
52    Find the cursor again and see what text is near it now.
55 BASIC CURSOR CONTROL
56 --------------------
58 Getting from screenful to screenful is useful, but how do you
59 reposition yourself within a given screen to a specific place?
60 There are several ways you can do this.  One way (not the best, but
61 the most basic) is to use the commands previous, backward, forward
62 and next.  As you can imagine these commands (which are given to
63 Emacs as C-p, C-b, C-f, and C-n  respectively) move the cursor from
64 where it currently is to a new place in the given direction.  Here,
65 in a more graphical form are the commands:
67                           Previous line, C-p
68                                   :
69                                   :
70    Backward, C-b .... Current cursor position .... Forward, C-f
71                                   :
72                                   :
73                           Next line, C-n
75 >> Move the cursor to the line in the middle of that diagram
76    and type C-l to see the whole diagram centered in the screen.
78 You'll probably find it easy to think of these by letter.  P for
79 previous, N for next, B for backward and F for forward.  These are
80 the basic cursor positioning commands and you'll be using them ALL
81 the time so it would be of great benefit if you learn them now.
83 >> Do a few C-n's to bring the cursor down to this line.
85 >> Move into the line with C-f's and then up with C-p's.
86    See what C-p does when the cursor is in the middle of the line.
88 Lines are separated by Newline characters.  For most applications
89 there should normally be a Newline character at the end of the text,
90 as well, but it is up to you to make sure of this.  A file can
91 validly exist without a Newline at the end.
93 >> Try to C-b at the beginning of a line.  Do a few more C-b's.
94    Then do C-f's back to the end of the line and beyond.
96 When you go off the top or bottom of the screen, the text beyond
97 the edge is shifted onto the screen so that your instructions can
98 be carried out while keeping the cursor on the screen.
100 >> Try to move the cursor off the bottom of the screen with C-n and
101    see what happens.
103 If moving by characters is too slow, you can move by words.  M-f
104 (Meta-f) moves forward a word and M-b moves back a word.
106 >> Type a few M-f's and M-b's.  Intersperse them with C-f's and C-b's.
108 Notice the parallel between C-f and C-b on the one hand, and M-f and
109 M-b on the other hand.  Very often Meta characters are used for
110 operations related to English text whereas Control characters operate
111 on the basic textual units that are independent of what you are
112 editing (characters, lines, etc).  There is a similar parallel between
113 lines and sentences: C-a and C-e move to the beginning or end of a
114 line, and M-a and M-e move to the beginning or end of a sentence.
116 >> Try a couple of C-a's, and then a couple of C-e's.
117    Try a couple of M-a's, and then a couple of M-e's.
119 See how repeated C-a's do nothing, but repeated M-a's keep moving
120 farther.  Do you think that this is right?
122 Two other simple cursor motion commands are M-< (Meta Less-than),
123 which moves to the beginning of the file, and M-> (Meta Greater-than),
124 which moves to the end of the file.  You probably don't need to try
125 them, since finding this spot again will be boring.  On most terminals
126 the "<" is above the comma and you must use the shift key to type it.
127 On these terminals you must use the shift key to type M-< also;
128 without the shift key, you would be typing M-comma.
130 The location of the cursor in the text is also called "point".  To
131 paraphrase, the cursor shows on the screen where point is located in
132 the text.
134 Here is a summary of simple moving operations including the word and
135 sentence moving commands:
137         C-f     Move forward a character
138         C-b     Move backward a character
140         M-f     Move forward a word
141         M-b     Move backward a word
143         C-n     Move to next line
144         C-p     Move to previous line
146         C-a     Move to beginning of line
147         C-e     Move to end of line
149         M-a     Move back to beginning of sentence
150         M-e     Move forward to end of sentence
152         M-<     Go to beginning of file
153         M->     Go to end of file
155 >> Try all of these commands now a few times for practice.
156    Since the last two will take you away from this screen,
157    you can come back here with M-v's and C-v's.  These are
158    the most often used commands.
160 Like all other commands in Emacs, these commands can be given
161 arguments which cause them to be executed repeatedly.  The way you
162 give a command a repeat count is by typing C-u and then the digits
163 before you type the command.  If you have a META or EDIT key, you can
164 omit the C-u if you hold down the META or EDIT key while you type the
165 digits.  This is easier, but we recommend the C-u method because it
166 works on any terminal.
168 For instance, C-u 8 C-f moves forward eight characters.
169         
170 >> Try giving a suitable argument to C-n or C-p to come as close
171    as you can to this line in one jump.
173 The only apparent exception to this is the screen moving commands,
174 C-v and M-v.  When given an argument, they scroll the screen up or
175 down by that many lines, rather than screenfuls.  This proves to be
176 much more useful.
178 >> Try typing C-u 8 C-v now.
180 Did it scroll the screen up by 8 lines?  If you would like to
181 scroll it down you can give an argument to M-v.
184 WHEN EMACS IS HUNG
185 -----------------
187 If Emacs gets into an infinite (or simply very long) computation which
188 you don't want to finish, you can stop it safely by typing C-g.
189 You can also use C-g to discard a numeric argument or the beginning of
190 a command that you don't want to finish.
192 >> Type C-u 100 to make a numeric arg of 100, then type C-g.
193    Now type C-f.  How many characters does it move?
194    If you have typed an <ESC> by mistake, you can get rid of it
195    with a C-g.
197 If you type <ESC> <ESC>, you get a new window appearing on
198 the screen, telling you that M-ESC is a "disabled command"
199 and asking whether you really want to execute it.  The command
200 M-ESC is marked as disabled because you probably don't want to
201 use it until you know more about Emacs, and we expect it would
202 confuse you if it were allowed to go ahead and run.  If you really
203 want to try the M-ESC command, you could type a Space in answer
204 to the question and M-ESC would go ahead.  Normally, if you do
205 not want to execute M-ESC, you would type "n" to answer the question.
207 >> Type <ESC> <ESC>, then type n.
210 WINDOWS
211 -------
213 Emacs can have several windows, each displaying its own text.
214 At this stage it is better not to go into the techniques of
215 using multiple windows.  But you do need to know how to get
216 rid of extra windows that may appear to display help or
217 output from certain commands.  It is simple:
219         C-x 1   One window (i.e., kill all other windows).
221 That is Control-x followed by the digit 1.
222 C-x 1 makes the window which the cursor is in become
223 the full screen, by getting rid of any other windows.
225 >> Move the cursor to this line and type C-u 0 C-l.
226 >> Type Control-h k Control-f.
227    See how this window shrinks, while a new one appears
228    to display documentation on the Control-f command.
230 >> Type C-x 1 and see the documentation listing window disappear.
233 INSERTING AND DELETING
234 ----------------------
236 If you want to insert text, just type it.  Characters which you can
237 see, such as A, 7, *, etc. are taken by Emacs as text and inserted
238 immediately.  Type <Return> (the carriage-return key) to insert a
239 Newline character.
241 You can delete the last character you typed by typing <Rubout>.
242 <Rubout> is a key on the keyboard, which might be labelled "Delete"
243 instead of "Rubout" on some terminals.  More generally, <Rubout>
244 deletes the character immediately before the current cursor position.
246 >> Do this now, type a few characters and then delete them
247    by typing <Rubout> a few times.  Don't worry about this file
248    being changed; you won't affect the master tutorial.  This is just
249    a copy of it.
251 >> Now start typing text until you reach the right margin, and keep
252    typing.  When a line of text gets too big for one line on the
253    screen, the line of text is "continued" onto a second screen line.
254    The backslash at the right margin indicates a line which has
255    been continued.
256 >> Use <Rubout>s to delete the text until the line fits on one screen
257    line again.  The continuation line goes away.
259 >> Move the cursor to the beginning of a line and type <Rubout>.  This
260    deletes the newline before the line and merges the line onto
261    the previous line.  The resulting line may be too long to fit, in
262    which case it has a continuation line.
263 >> Type <Return> to reinsert the Newline you deleted.
265 Remember that most Emacs commands can be given a repeat count;
266 this includes characters which insert themselves.
268 >>  Try that now -- type C-u 8 * and see what happens.
270 You've now learned the most basic way of typing something in
271 Emacs and correcting errors.  You can delete by words or lines
272 as well.  Here is a summary of the delete operations:
274         <Rubout>     delete the character just before the cursor
275         C-d          delete the next character after the cursor
277         M-<Rubout>   kill the word immediately before the cursor
278         M-d          kill the next word after the cursor
280         C-k          kill from the cursor position to end of line
281         M-k          kill to the end of the current sentence
283 Notice that <Rubout> and C-d vs M-<Rubout> and M-d extend the parallel
284 started by C-f and M-f (well, <Rubout> isn't really a control
285 character, but let's not worry about that).  C-k and M-k are like C-e
286 and M-e, sort of, in that lines are opposite sentences.
288 Now suppose you kill something, and then you decide that you want to
289 get it back?  Well, whenever you kill something bigger than a
290 character, Emacs saves it for you.  To yank it back, use C-y.  You
291 can kill text in one place, move elsewhere, and then do C-y; this is
292 a good way to move text around.  Note that the difference
293 between "Killing" and "Deleting" something is that "Killed" things
294 can be yanked back, and "Deleted" things cannot.  Generally, the
295 commands that can destroy a lot of text save it, while the ones that
296 attack only one character, or nothing but blank lines and spaces, do
297 not save.
299 For instance, type C-n a couple times to position the cursor
300 at some line on this screen.
302 >> Do this now, move the cursor and kill that line with C-k.
304 Note that a single C-k kills the contents of the line, and a second
305 C-k kills the line itself, and make all the other lines move up.  If
306 you give C-k a repeat count, it kills that many lines AND their
307 contents.
309 The text that has just disappeared is saved so that you can
310 retrieve it.  To retrieve the last killed text and put it where
311 the cursor currently is, type C-y.
313 >> Try it; type C-y to yank the text back.
315 Think of C-y as if you were yanking something back that someone
316 took away from you.  Notice that if you do several C-k's in a row
317 the text that is killed is all saved together so that one C-y will
318 yank all of the lines.
320 >> Do this now, type C-k several times.
322 Now to retrieve that killed text:
324 >> Type C-y.  Then move the cursor down a few lines and type C-y
325    again.  You now see how to copy some text.
327 What do you do if you have some text you want to yank back, and then
328 you kill something else?  C-y would yank the more recent kill.  But
329 the previous text is not lost.  You can get back to it using the M-y
330 command.  After you have done C-y to get the most recent kill, typing
331 M-Y replaces that yanked text with the previous kill.  Typing M-y
332 again and again brings in earlier and earlier kills.  When you
333 have reached the text you are looking for, you can just go away and
334 leave it there.  If you M-y enough times, you come back to the
335 starting point (the most recent kill).
337 >> Kill a line, move around, kill another line.
338    Then do C-y to get back the second killed line.
339    Then do M-y and it will be replaced by the first killed line.
340    Do more M-y's and see what you get.  Keep doing them until
341    the second kill line comes back, and then a few more.
342    If you like, you can try giving M-y positive and negative
343    arguments.
346 UNDO
347 ----
349 Any time you make a change to the text and wish you had not done so,
350 you can undo the change (return the text to its previous state)
351 with the undo command, C-x u.  Normally, C-x u undoes one command's
352 worth of changes; if you repeat the C-x u several times in a row,
353 each time undoes one more command.  There are two exceptions:
354 commands that made no change (just moved the cursor) do not count,
355 and self-inserting characters are often lumped together in groups
356 of up to 20.  This is to reduce the number of C-x u's you have to type.
358 >> Kill this line with C-k, then type C-x u and it should reappear.
360 C-_ is another command for undoing; it is just the same as C-x u
361 but easier to type several times in a row.  The problem with C-_ is
362 that on some keyboards it is not obvious how to type it.  That is
363 why C-x u is provided as well.  On some DEC terminals, you can type
364 C-_ by typing / while holding down CTRL.  Illogical, but what can
365 you expect from DEC?
367 Giving a numeric argument to C-_ or C-x u is equivalent to repeating
368 it as many times as the argument says.
371 FILES
372 -----
374 In order to make the text you edit permanent, you must put it in a
375 file.  Otherwise, it will go away when your invocation of Emacs goes
376 away.  You put your editing in a file by "finding" the file.  What
377 finding means is that you see the contents of the file in your Emacs;
378 and, loosely speaking, what you are editing is the file itself.
379 However, the changes still don't become permanent until you "save" the
380 file.  This is so you can have control to avoid leaving a half-changed
381 file around when you don't want to.  Even then, Emacs leaves the
382 original file under a changed name in case your changes turn out
383 to be a mistake.
385 If you look near the bottom of the screen you will see a line that
386 begins and ends with dashes, and contains the string "Emacs: TUTORIAL".
387 Your copy of the Emacs tutorial is called "TUTORIAL".  Whatever
388 file you find, that file's name will appear in that precise
389 spot.
391 The commands for finding and saving files are unlike the other
392 commands you have learned in that they consist of two characters.
393 They both start with the character Control-x.  There is a whole series
394 of commands that start with Control-x; many of them have to do with
395 files, buffers, and related things, and all of them consist of
396 Control-x followed by some other character.
398 Another thing about the command for finding a file is that you have
399 to say what file name you want.  We say the command "reads an argument
400 from the terminal" (in this case, the argument is the name of the
401 file).  After you type the command
403         C-x C-f   Find a file
405 Emacs asks you to type the file name.  It echoes on the bottom
406 line of the screen.  You are using the minibuffer now!  this is
407 what the minibuffer is for.  When you type <Return> to end the
408 file name, the minibuffer is no longer needed, so it disappears.
410 >> Type C-x C-f, then type C-g.  This cancels the minibuffer,
411    and also cancels the C-x C-f command that was using the
412    minibuffer.  So you do not find any file.
414 In a little while the file contents appear on the screen.  You can
415 edit the contents.  When you wish to make the changes permanent,
416 issue the command
418         C-x C-s   Save the file
420 The contents of Emacs are written into the file.  The first time you
421 do this, the original file is renamed to a new name so that it
422 is not lost.  The new name is made by appending "~" to the end
423 of the original file's name.
425 When saving is finished, Emacs prints the name of the file written.
426 You should save fairly often, so that you will not lose very much
427 work if the system should crash.
429 >> Type C-x C-s, saving your copy of the tutorial.
430    This should print "Wrote .../TUTORIAL" at the bottom of the screen.
431    On VMS it will print "Wrote ...[...]TUTORIAL."
433 To make a new file, just find it "as if" it already existed.  Then
434 start typing in the text.  When you ask to "save" the file, Emacs
435 will really create the file with the text that you have inserted.
436 From then on, you can consider yourself to be editing an already
437 existing file.
440 BUFFERS
441 -------
443 If you find a second file with C-x C-f, the first file remains
444 inside Emacs.  You can switch back to it by finding it again with
445 C-x C-f.  This way you can get quite a number of files inside Emacs.
447 The object inside Emacs which holds the text read from one file
448 is called a "buffer."  Finding a file makes a new buffer inside Emacs.
449 To see a list of the buffers that exist in Emacs, type
451         C-x C-b   List buffers
453 >> Try C-x C-b now.
455 See how each buffer has a name, and it may also have a file name
456 for the file whose contents it holds.  Some buffers do not correspond
457 to files.  For example, the buffer named "*Buffer List*" does
458 not have any file.  It is the buffer which contains the buffer
459 list that was made by C-x C-b.  ANY text you see in an Emacs window
460 has to be in some buffer.
462 >> Type C-x 1 to get rid of the buffer list.
464 If you make changes to the text of one file, then find another file,
465 this does not save the first file.  Its changes remain inside Emacs,
466 in that file's buffer.  The creation or editing of the second file's
467 buffer has no effect on the first file's buffer.  This is very useful,
468 but it also means that you need a convenient way to save the first
469 file's buffer.  It would be a nuisance to have to switch back to
470 it with C-x C-f in order to save it with C-x C-s.  So we have
472         C-x s     Save some buffers
474 C-x s goes through the list of all the buffers you have
475 and finds the ones that contain files you have changed.
476 For each such buffer, C-x s asks you whether to save it.
479 EXTENDING THE COMMAND SET
480 -------------------------
482 There are many, many more Emacs commands than could possibly be put
483 on all the control and meta characters.  Emacs gets around this with
484 the X (eXtend) command.  This comes in two flavors:
486         C-x     Character eXtend.  Followed by one character.
487         M-x     Named command eXtend.  Followed by a long name.
489 These are commands that are generally useful but used less than the
490 commands you have already learned about.  You have already seen two
491 of them: the file commands C-x C-f to Find and C-x C-s to Save.
492 Another example is the command to tell Emacs that you'd like to stop
493 editing and get rid of Emacs.  The command to do this is C-x C-c.
494 (Don't worry; it offers to save each changed file before it kills the
495 Emacs.)
497 C-z is the usual way to exit Emacs, because it is always better not to
498 kill the Emacs if you are going to do any more editing.  On systems
499 which allow it, C-z exits from Emacs to the shell but does not destroy
500 the Emacs; if you use the C shell, you can resume Emacs with the `fg'
501 command (or, more generally, with `%emacs', which works even if your
502 most recent job was some other).  On systems where suspending is not
503 possible, C-z creates a subshell running under Emacs to give you the
504 chance to run other programs and return to Emacs afterward, but it
505 does not truly "exit" from Emacs.  In this case, the shell command
506 `exit' is the usual way to get back to Emacs from the subshell.
508 You would use C-x C-c if you were about to log out.  You would
509 also use it to exit an Emacs invoked under mail handling programs
510 and other random utilities, since they may not believe you have
511 really finished using the Emacs if it continues to exist.
513 There are many C-x commands.  The ones you know are:
515         C-x C-f         Find file.
516         C-x C-s         Save file.
517         C-x C-b         List buffers.
518         C-x C-c         Quit Emacs.
519         C-x u           Undo.
521 Named eXtended commands are commands which are used even less
522 frequently, or commands which are used only in certain modes.  These
523 commands are usually called "functions".  An example is the function
524 replace-string, which globally replaces one string with another.  When
525 you type M-x, Emacs prompts you at the bottom of the screen with
526 M-x and you should type the name of the function you wish to call; in
527 this case, "replace-string".  Just type "repl s<TAB>" and Emacs will
528 complete the name.  End the command name with <Return>.
529 Then type the two "arguments"--the string to be replaced, and the string
530 to replace it with--each one ended with a Return.
532 >> Move the cursor to the blank line two lines below this one.
533    Then type M-x repl s<Return>changed<Return>altered<Return>.
535    Notice how this line has changed: you've replaced
536    the word c-h-a-n-g-e-d with "altered" wherever it occurred
537    after the cursor.
540 MODE LINE
541 ---------
543 If Emacs sees that you are typing commands slowly it shows them to you
544 at the bottom of the screen in an area called the "echo area."  The echo
545 area contains the bottom line of the screen.  The line immediately above
546 it is called the MODE LINE.  The mode line says something like
548 --**--Emacs: TUTORIAL               (Fundamental)----58%-------------
550 This is a very useful "information" line.
552 You already know what the filename means--it is the file you have
553 found.  What the --NN%-- means is that NN percent of the file is
554 above the top of the screen.  If the top of the file is on the screen,
555 it will say --TOP-- instead of --00%--.  If the bottom of the file is
556 on the screen, it will say --BOT--.  If you are looking at a file so
557 small it all fits on the screen, it says --ALL--.
559 The stars near the front mean that you have made changes to the text.
560 Right after you visit or save a file, there are no stars, just dashes.
562 The part of the mode line inside the parentheses is to tell you what
563 modes you are in.  The default mode is Fundamental which is what you
564 are in now.  It is an example of a "major mode".  There are several
565 major modes in Emacs for editing different languages and text, such as
566 Lisp mode, Text mode, etc.  At any time one and only one major mode is
567 active, and its name can always be found in the mode line just where
568 "Fundamental" is now.  Each major mode makes a few commands behave
569 differently.  For example, there are commands for creating comments in
570 a program, and since each programming language has a different idea of
571 what a comment should look like, each major mode has to insert
572 comments differently.  Each major mode is the name of an extended
573 command, which is how you get into the mode.  For example,
574 M-X fundamental-mode is how to get into Fundamental mode.
576 If you are going to be editing English text, such as this file, you
577 should probably use Text Mode.
578 >> Type M-x text-mode<Return>.
580 Don't worry, none of the commands you have learned changes Emacs in
581 any great way.  But you can now observe that periods are no longer
582 part of words when you do M-f or M-b!  Major modes are usually like
583 that: commands don't change into completely unrelated things, but they
584 work a little bit differently.
586 To get documentation on your current major mode, type C-h m.
588 >> Use C-u C-v once or more to bring this line near the top of screen.
589 >> Type C-h m, to see how Text mode differs from Fundamental mode.
590 >> Type C-x 1 to remove the documentation from the screen.
592 Major modes are called major because there are also minor modes.
593 They are called minor because they aren't alternatives to the major
594 modes, just minor modifications of them.  Each minor mode can be
595 turned on or off by itself, regardless of what major mode you are in,
596 and regardless of the other minor modes.  So you can use no minor
597 modes, or one minor mode, or any combination of several minor modes.
599 One minor mode which is very useful, especially for editing English
600 text, is Auto Fill mode.  When this mode is on, Emacs breaks the line
601 in between words automatically whenever the line gets too long.  You
602 can turn this mode on by doing M-x auto-fill-mode<Return>.  When the
603 mode is on, you can turn it off by doing M-x auto-fill-mode<Return>.
604 If the mode is off, this function turns it on, and if the mode is on,
605 this function turns it off.  This is called "toggling".
607 >> Type M-x auto-fill-mode<Return> now.  Then insert a line of "asdf "
608    over again until you see it divide into two lines.  You must put in
609    spaces between them because Auto Fill breaks lines only at spaces.
611 The margin is usually set at 70 characters, but you can change it
612 with the C-x f command.  You should give the margin setting you want
613 as a numeric argument.
615 >> Type C-x f with an argument of 20.  (C-u 2 0 C-x f).
616    Then type in some text and see Emacs fill lines of 20
617    characters with it.  Then set the margin back to 70 using
618    C-x f again.
620 If you makes changes in the middle of a paragraph, Auto Fill mode
621 does not re-fill it for you.
622 To re-fill the paragraph, type M-q (Meta-q) with the cursor inside
623 that paragraph.
625 >> Move the cursor into the previous paragraph and type M-q.
627 SEARCHING
628 ---------
630 Emacs can do searches for strings (these are groups of contiguous
631 characters or words) either forward through the file or backward
632 through it.  To search for the string means that you are trying to
633 locate it somewhere in the file and have Emacs show you where the
634 occurrences of the string exist.  This type of search is somewhat
635 different from what you may be familiar with.  It is a search that is
636 performed as you type in the thing to search for.  The command to
637 initiate a search is C-s for forward search, and C-r for reverse
638 search.  BUT WAIT!  Don't do them now.  When you type C-s you'll
639 notice that the string "I-search" appears as a prompt in the echo
640 area.  This tells you that Emacs is in what is called an incremental
641 search waiting for you to type the thing that you want to search for.
642 <ESC> terminates a search.
644 >> Now type C-s to start a search.  SLOWLY, one letter at a time,
645    type the word 'cursor', pausing after you type each
646    character to notice what happens to the cursor.
647 >> Type C-s to find the next occurrence of "cursor".
648 >> Now type <Rubout> four times and see how the cursor moves.
649 >> Type <ESC> to terminate the search.
651 Did you see what happened?  Emacs, in an incremental search, tries to
652 go to the occurrence of the string that you've typed out so far.  To go
653 to the next occurrence of 'cursor' just type C-s again.  If no such
654 occurrence exists Emacs beeps and tells you that it is a failing
655 search.  C-g would also terminate the search.
657 If you are in the middle of an incremental search and type <Rubout>,
658 you'll notice that the last character in the search string is erased
659 and the search backs up to the last place of the search.  For
660 instance, suppose you currently have typed 'cu' and you see that your
661 cursor is at the first occurrence of 'cu'.  If you now type <Rubout>,
662 the 'u' on the search line is erased and you'll be repositioned in the
663 text to the occurrence of 'c' where the search took you before you
664 typed the 'u'.  This provides a useful means for backing up while you
665 are searching.
667 If you are in the middle of a search and happen to type a control
668 character (other than a C-s or C-r, which tell Emacs to search for the
669 next occurrence of the string), the search is terminated.
671 The C-s starts a search that looks for any occurrence of the search
672 string AFTER the current cursor position.  But what if you want to
673 search for something earlier in the text?  To do this, type C-r for
674 Reverse search.  Everything that applies to C-s applies to C-r except
675 that the direction of the search is reversed.
678 MULTIPLE WINDOWS
679 ----------------
681 One of the nice features of Emacs is that you can display more than one
682 window on the screen at the same time.
684 >> Move the cursor to this line and type C-u 0 C-l.
686 >> Now type C-x 2 which splits the screen into two windows.
687    Both windows display this tutorial.  The cursor stays in the top window.
689 >> Type C-M-v to scroll the bottom window.
691 >> Type C-x o ("o" for "other") to move the cursor to the bottom window.
692 >> Use C-v and M-v in the bottom window to scroll it.
693    Keep reading these directions in the top window.
695 >> Type C-x o again to move the cursor back to the top window.
696    The cursor is still just where it was in the top window before.
698 You can keep using C-x o to switch between the windows.  Each
699 window has its own cursor position, but only one window actually
700 shows the cursor.  All the ordinary editing commands apply to the
701 window that the cursor is in.
703 The command C-M-v is very useful when you are editing text in one
704 window and using the other window just for reference.  You can keep
705 the cursor always in the window where you are editing, and edit
706 there as you advance through the other window.
708 >> Type C-x 1 (in the top window) to get rid of the bottom window.
710 (If you had typed C-x 1 in the bottom window, that would get rid
711 of the top one.  Think of this command as "Keep just one
712 window--the window I am already in.")
714 You don't have to display the same buffer in both windows.  If
715 you use C-x C-f to find a file in one window, the other window
716 doesn't change.  You can pick a file in each window
717 independently.
719 Here is another way to use two windows to display two different
720 things:
722 >> Type C-x 4 C-f followed by the name of one of your files.
723    End with <RETURN>.  See the specified file appear in the bottom
724    window.  The cursor goes there, too.
726 >> Type C-x o to go back to the top window, and C-x 1 to delete
727    the bottom window.
730 RECURSIVE EDITING LEVELS
731 ------------------------
733 Sometimes you will get into what is called a "recursive editing
734 level".  This is indicated by square brackets in the mode line,
735 surrounding the parentheses around the major mode name.  For
736 example, you might see [(Fundamental)] instead of (Fundamental).
738 To get out of the recursive editing level, type
739   M-x top-level<Return>.
741 >> Try that now; it should display "Back to top level"
742    at the bottom of the screen.
744 In fact, you were ALREADY at top level (not inside a recursive editing
745 level) if you have obeyed instructions.  M-x top-level does not care;
746 it gets out of any number of recursive editing levels, perhaps zero,
747 to get back to top level.
749 You can't use C-g to get out of a recursive editing level because C-g
750 is used for discarding numeric arguments and partially typed commands
751 WITHIN the recursive editing level.
754 GETTING MORE HELP
755 -----------------
757 In this tutorial we have tried to supply just enough information to
758 get you started using Emacs.  There is so much available in Emacs that
759 it would be impossible to explain it all here.  However, you may want
760 to learn more about Emacs since it has numerous desirable features
761 that you don't know about yet.  Emacs has a great deal of internal
762 documentation.  All of these commands can be accessed through
763 the character Control-h, which we call "the Help character"
764 because of the function it serves.
766 To use the HELP features, type the C-h character, and then a
767 character saying what kind of help you want.  If you are REALLY lost,
768 type C-h ? and Emacs will tell you what kinds of help it can give.
769 If you have typed C-h and decide you don't want any help, just
770 type C-G to cancel it.
772 The most basic HELP feature is C-h c.  Type C-h, a c, and a
773 command character or sequence, and Emacs displays a very brief
774 description of the command.
776 >> Type C-h c Control-p.
777   The message should be something like
779         C-p runs the command previous-line
781 This tells you the "name of the function".  That is important in
782 writing Lisp code to extend Emacs; it also is enough to remind
783 you of what the command does if you have seen it before but did
784 not remember.
786 Multi-character commands such as C-x C-s and (if you have no META or
787 EDIT key) <ESC>v are also allowed after C-h c.
789 To get more information on the command, use C-h k instead of C-h c.
791 >> Type C-h k Control-p.
793 This displays the documentation of the function, as well as its
794 name, in an Emacs window.  When you are finished reading the
795 output, type C-x 1 to get rid of the help text.  You do not have
796 to do this right away.  You can do some editing while referring
797 to the help text and then type C-x 1.
799 Here are some other useful C-h options:
801    C-h f        Describe a function.  You type in the name of the
802                 function.
804 >> Try typing C-h f previous-line<Return>.
805    This prints all the information Emacs has about the
806    function which implements the C-P command.
808    C-h a        Command Apropos.  Type in a keyword and Emacs will list
809                 all the commands whose names contain that keyword.
810                 These commands can all be invoked with Meta-x.
811                 For some commands, Command Apropos will also list a one
812                 or two character sequence which has the same effect.
814 >> Type C-h a file<Return>.
816 This displays in another window a list of all M-x commands with
817 "file" in their names.  You will also see commands like C-x C-f
818 and C-x C-w, listed beside the command names find-file and
819 write-file.
821 >> Type C-M-v to scroll the help window.  Do this a few times.
823 >> Type C-x 1 to delete the help window.
826 CONCLUSION
827 ----------
829 Remember, to exit Emacs permanently use C-x C-c.  To exit to a shell
830 temporarily, so that you can come back in, use C-z.
832 This tutorial is meant to be understandable to all new users, so if
833 you found something unclear, don't sit and blame yourself - complain!
836 COPYING
837 -------
839 This tutorial descends from a long line of Emacs tutorials
840 starting with the one written by Stuart Cracraft for the original Emacs.
842 This version of the tutorial, like GNU Emacs, is copyrighted, and
843 comes with permission to distribute copies on certain conditions:
845 Copyright (c) 1985 Free Software Foundation
847    Permission is granted to anyone to make or distribute verbatim copies
848    of this document as received, in any medium, provided that the
849    copyright notice and permission notice are preserved,
850    and that the distributor grants the recipient permission
851    for further redistribution as permitted by this notice.
853    Permission is granted to distribute modified versions
854    of this document, or of portions of it,
855    under the above conditions, provided also that they
856    carry prominent notices stating who last altered them.
858 The conditions for copying Emacs itself are slightly different
859 but in the same spirit.  Please read the file COPYING and then
860 do give copies of GNU Emacs to your friends.
861 Help stamp out software obstructionism ("ownership") by using,
862 writing, and sharing free software!