(gud-display-line): Use gdb-display-source-buffer
[bpt/emacs.git] / etc / TUTORIAL
CommitLineData
4873755c 1Emacs tutorial. See end for copying conditions.
f751376f 2
1869e50a
KH
3Emacs commands generally involve the CONTROL key (sometimes labeled
4CTRL or CTL) or the META key (sometimes labeled EDIT or ALT). Rather than
4a3142d2 5write that in full each time, we'll use the following abbreviations:
f751376f
JB
6
7 C-<chr> means hold the CONTROL key while typing the character <chr>
8 Thus, C-f would be: hold the CONTROL key and type f.
8a4aff68 9 M-<chr> means hold the META or EDIT or ALT key down while typing <chr>.
4a3142d2
KH
10 If there is no META, EDIT or ALT key, instead press and release the
11 ESC key and then type <chr>. We write <ESC> for the ESC key.
f751376f
JB
12
13Important note: to end the Emacs session, type C-x C-c. (Two characters.)
14The characters ">>" at the left margin indicate directions for you to
15try using a command. For instance:
39296e3a
RS
16<<Blank lines inserted around following line by help-with-tutorial>>
17[Middle of page left blank for didactic purposes. Text continues below]
f751376f 18>> Now type C-v (View next screen) to move to the next screen.
1e78d347 19 (go ahead, do it by holding down the CONTROL key while typing v).
82e312c7 20 From now on, you should do this again whenever you finish
f751376f
JB
21 reading the screen.
22
82e312c7
RS
23Note that there is an overlap of two lines when you move from screen
24to screen; this provides some continuity so you can continue reading
25the text.
f751376f 26
82e312c7
RS
27The first thing that you need to know is how to move around from place
28to place in the text. You already know how to move forward one screen,
29with C-v. To move backwards one screen, type M-v (hold down the META key
bec1289c 30and type v, or type <ESC>v if you do not have a META, EDIT, or ALT key).
f751376f 31
82e312c7 32>> Try typing M-v and then C-v, a few times.
f751376f
JB
33
34
26dc36e6
JB
35* SUMMARY
36---------
f751376f
JB
37
38The following commands are useful for viewing screenfuls:
39
40 C-v Move forward one screenful
41 M-v Move backward one screenful
82e312c7
RS
42 C-l Clear screen and redisplay all the text,
43 moving the text around the cursor
44 to the center of the screen.
1e78d347 45 (That's CONTROL-L, not CONTROL-1.)
f751376f 46
82e312c7
RS
47>> Find the cursor, and note what text is near it.
48 Then type C-l.
49 Find the cursor again and notice that the same text
50 is near the cursor now.
f751376f 51
3d9a3367
RS
52You can also use the PageUp and PageDn keys to move by screenfuls, if
53your terminal has them, but you can edit more efficiently if you use
54C-v and M-v.
49a8a2f5 55
f751376f 56
26dc36e6
JB
57* BASIC CURSOR CONTROL
58----------------------
f751376f 59
82e312c7
RS
60Moving from screenful to screenful is useful, but how do you
61move to a specific place within the text on the screen?
62
49a8a2f5
RS
63There are several ways you can do this. You can use the arrow keys,
64but it's more efficient to keep your hands in the standard position
65and use the commands C-p, C-b, C-f, and C-n. These characters
66are equivalent to the four arrow keys, like this:
177c0ea7 67
f751376f
JB
68 Previous line, C-p
69 :
70 :
71 Backward, C-b .... Current cursor position .... Forward, C-f
72 :
73 :
82e312c7 74 Next line, C-n
f751376f
JB
75
76>> Move the cursor to the line in the middle of that diagram
82e312c7
RS
77 using C-n or C-p. Then type C-l to see the whole diagram
78 centered in the screen.
f751376f 79
49a8a2f5
RS
80You'll find it easy to remember these letters by words they stand for:
81P for previous, N for next, B for backward and F for forward. You
82will be using these basic cursor positioning commands all the time.
f751376f
JB
83
84>> Do a few C-n's to bring the cursor down to this line.
85
86>> Move into the line with C-f's and then up with C-p's.
87 See what C-p does when the cursor is in the middle of the line.
88
5b85892b
RS
89Each line of text ends with a Newline character, which serves to
90separate it from the following line. The last line in your file ought
91to have a Newline at the end (but Emacs does not require it to have
92one).
82e312c7
RS
93
94>> Try to C-b at the beginning of a line. It should move to
95 the end of the previous line. This is because it moves back
96 across the Newline character.
f751376f 97
82e312c7 98C-f can move across a Newline just like C-b.
f751376f 99
82e312c7
RS
100>> Do a few more C-b's, so you get a feel for where the cursor is.
101 Then do C-f's to return to the end of the line.
102 Then do one more C-f to move to the following line.
f751376f 103
82e312c7
RS
104When you move past the top or bottom of the screen, the text beyond
105the edge shifts onto the screen. This is called "scrolling". It
106enables Emacs to move the cursor to the specified place in the text
107without moving it off the screen.
108
109>> Try to move the cursor off the bottom of the screen with C-n, and
f751376f
JB
110 see what happens.
111
112If moving by characters is too slow, you can move by words. M-f
1e78d347 113(META-f) moves forward a word and M-b moves back a word.
f751376f 114
82e312c7
RS
115>> Type a few M-f's and M-b's.
116
117When you are in the middle of a word, M-f moves to the end of the word.
118When you are in whitespace between words, M-f moves to the end of the
119following word. M-b works likewise in the opposite direction.
120
121>> Type M-f and M-b a few times, interspersed with C-f's and C-b's
122 so that you can observe the action of M-f and M-b from various
123 places inside and between words.
f751376f
JB
124
125Notice the parallel between C-f and C-b on the one hand, and M-f and
126M-b on the other hand. Very often Meta characters are used for
82e312c7
RS
127operations related to the units defined by language (words, sentences,
128paragraphs), while Control characters operate on basic units that are
129independent of what you are editing (characters, lines, etc).
130
131This parallel applies between lines and sentences: C-a and C-e move to
132the beginning or end of a line, and M-a and M-e move to the beginning
133or end of a sentence.
f751376f
JB
134
135>> Try a couple of C-a's, and then a couple of C-e's.
136 Try a couple of M-a's, and then a couple of M-e's.
137
82e312c7
RS
138See how repeated C-a's do nothing, but repeated M-a's keep moving one
139more sentence. Although these are not quite analogous, each one seems
140natural.
f751376f
JB
141
142The location of the cursor in the text is also called "point". To
143paraphrase, the cursor shows on the screen where point is located in
144the text.
145
82e312c7
RS
146Here is a summary of simple cursor-moving operations, including the
147word and sentence moving commands:
f751376f
JB
148
149 C-f Move forward a character
150 C-b Move backward a character
151
152 M-f Move forward a word
153 M-b Move backward a word
154
155 C-n Move to next line
156 C-p Move to previous line
157
158 C-a Move to beginning of line
159 C-e Move to end of line
160
161 M-a Move back to beginning of sentence
162 M-e Move forward to end of sentence
163
f751376f 164>> Try all of these commands now a few times for practice.
82e312c7
RS
165 These are the most often used commands.
166
1e78d347
PJ
167Two other important cursor motion commands are M-< (META Less-than),
168which moves to the beginning of the whole text, and M-> (META
82e312c7
RS
169Greater-than), which moves to the end of the whole text.
170
171On most terminals, the "<" is above the comma, so you must use the
172shift key to type it. On these terminals you must use the shift key
173to type M-< also; without the shift key, you would be typing M-comma.
174
175>> Try M-< now, to move to the beginning of the tutorial.
176 Then use C-v repeatedly to move back here.
177
178>> Try M-> now, to move to the end of the tutorial.
179 Then use M-v repeatedly to move back here.
180
181You can also move the cursor with the arrow keys, if your terminal has
182arrow keys. We recommend learning C-b, C-f, C-n and C-p for three
183reasons. First, they work on all kinds of terminals. Second, once
8806d20f 184you gain practice at using Emacs, you will find that typing these Control
82e312c7
RS
185characters is faster than typing the arrow keys (because you do not
186have to move your hands away from touch-typing position). Third, once
8806d20f 187you form the habit of using these Control character commands, you can
82e312c7
RS
188easily learn to use other advanced cursor motion commands as well.
189
190Most Emacs commands accept a numeric argument; for most commands, this
191serves as a repeat-count. The way you give a command a repeat count
192is by typing C-u and then the digits before you type the command. If
6f108a37 193you have a META (or EDIT or ALT) key, there is another, alternative way
bec1289c
KH
194to enter a numeric argument: type the digits while holding down the
195META key. We recommend learning the C-u method because it works on
973cefd2
RS
196any terminal. The numeric argument is also called a "prefix argument",
197because you type the argument before the command it applies to.
f751376f
JB
198
199For instance, C-u 8 C-f moves forward eight characters.
177c0ea7 200
82e312c7
RS
201>> Try using C-n or C-p with a numeric argument, to move the cursor
202 to a line near this one with just one command.
f751376f 203
973cefd2
RS
204Most commands use the numeric argument as a repeat count, but some
205commands use it in some other way. Several commands (but none of
206those you have learned so far) use it as a flag--the presence of a
207prefix argument, regardless of its value, makes the command do
208something different.
209
210C-v and M-v are another kind of exception. When given an argument,
211they scroll the screen up or down by that many lines, rather than by a
212screenful. For example, C-u 8 C-v scrolls the screen by 8 lines.
f751376f
JB
213
214>> Try typing C-u 8 C-v now.
215
82e312c7
RS
216This should have scrolled the screen up by 8 lines. If you would like
217to scroll it down again, you can give an argument to M-v.
f751376f 218
fc19ea9d
EZ
219If you are using a windowed display, such as X11 or MS-Windows, there
220should be a tall rectangular area called a scroll bar at the left hand
221side of the Emacs window. You can scroll the text by clicking the
222mouse in the scroll bar.
b0874bbd
RS
223
224>> Try pressing the middle button at the top of the highlighted area
82e312c7
RS
225 within the scroll bar. This should scroll the text to a position
226 determined by how high or low you click.
b0874bbd 227
82e312c7
RS
228>> Try moving the mouse up and down, while holding the middle button
229 pressed down. You'll see that the text scrolls up and down as
230 you move the mouse.
b0874bbd 231
f751376f 232
26dc36e6
JB
233* WHEN EMACS IS HUNG
234--------------------
f751376f 235
82e312c7
RS
236If Emacs stops responding to your commands, you can stop it safely by
237typing C-g. You can use C-g to stop a command which is taking too
238long to execute.
239
f751376f 240You can also use C-g to discard a numeric argument or the beginning of
82e312c7 241a command that you do not want to finish.
f751376f
JB
242
243>> Type C-u 100 to make a numeric arg of 100, then type C-g.
82e312c7
RS
244 Now type C-f. It should move just one character,
245 because you canceled the argument with C-g.
f751376f 246
82e312c7
RS
247If you have typed an <ESC> by mistake, you can get rid of it
248with a C-g.
335b1952 249
82e312c7
RS
250
251* DISABLED COMMANDS
252-------------------
253
254Some Emacs commands are "disabled" so that beginning users cannot use
255them by accident.
256
257If you type one of the disabled commands, Emacs displays a message
258saying what the command was, and asking you whether you want to go
259ahead and execute the command.
260
41835686
LK
261If you really want to try the command, type <SPC> (the Space bar) in
262answer to the question. Normally, if you do not want to execute the
263disabled command, answer the question with "n".
82e312c7 264
70f4a594 265>> Type C-x C-l (which is a disabled command),
82e312c7 266 then type n to answer the question.
f751376f
JB
267
268
26dc36e6
JB
269* WINDOWS
270---------
f751376f 271
82e312c7
RS
272Emacs can have several windows, each displaying its own text. We will
273explain later on how to use multiple windows. Right now we want to
274explain how to get rid of extra windows and go back to basic
275one-window editing. It is simple:
f751376f
JB
276
277 C-x 1 One window (i.e., kill all other windows).
278
1e78d347 279That is CONTROL-x followed by the digit 1. C-x 1 expands the window
82e312c7
RS
280which contains the cursor, to occupy the full screen. It deletes all
281other windows.
f751376f
JB
282
283>> Move the cursor to this line and type C-u 0 C-l.
1e78d347 284>> Type CONTROL-h k CONTROL-f.
f751376f 285 See how this window shrinks, while a new one appears
1e78d347 286 to display documentation on the CONTROL-f command.
f751376f
JB
287
288>> Type C-x 1 and see the documentation listing window disappear.
289
8806d20f 290This command is unlike the other commands you have learned in that it
1e78d347
PJ
291consists of two characters. It starts with the character CONTROL-x.
292There is a whole series of commands that start with CONTROL-x; many of
8806d20f
RS
293them have to do with windows, files, buffers, and related things.
294These commands are two, three or four characters long.
295
f751376f 296
26dc36e6
JB
297* INSERTING AND DELETING
298------------------------
f751376f 299
82e312c7
RS
300If you want to insert text, just type the text. Characters which you
301can see, such as A, 7, *, etc. are taken by Emacs as text and inserted
f751376f
JB
302immediately. Type <Return> (the carriage-return key) to insert a
303Newline character.
304
d6635fa1
RS
305You can delete the last character you typed by typing <Delback>.
306<Delback> is a key on the keyboard--the same one you normally use,
307outside Emacs, for deleting the last character you typed. It is
308normally a large key a couple of lines up from the <Return> key, and
309it is usually labeled "Delete", "Del" or "Backspace".
50d326a4 310
d6635fa1
RS
311If the large key there is labeled "Backspace", then that's the one you
312use for <Delback>. There may also be another key labeled "Delete"
313somewhere else, but that's not <Delback>.
314
315More generally, <Delback> deletes the character immediately before the
50d326a4 316current cursor position.
f751376f 317
82e312c7 318>> Do this now--type a few characters, then delete them
d6635fa1 319 by typing <Delback> a few times. Don't worry about this file
82e312c7
RS
320 being changed; you will not alter the master tutorial. This is
321 your personal copy of it.
322
323When a line of text gets too big for one line on the screen, the line
324of text is "continued" onto a second screen line. A backslash ("\")
bc2973c0
GM
325(or, if you're using a windowed display, a little curved arrow) at the
326right margin indicates a line which has been continued.
82e312c7
RS
327
328>> Insert text until you reach the right margin, and keep on inserting.
329 You'll see a continuation line appear.
330
d6635fa1 331>> Use <Delback>s to delete the text until the line fits on one screen
f751376f
JB
332 line again. The continuation line goes away.
333
82e312c7
RS
334You can delete a Newline character just like any other character.
335Deleting the Newline character between two lines merges them into
336one line. If the resulting combined line is too long to fit in the
337screen width, it will be displayed with a continuation line.
338
d6635fa1 339>> Move the cursor to the beginning of a line and type <Delback>. This
82e312c7
RS
340 merges that line with the previous line.
341
f751376f
JB
342>> Type <Return> to reinsert the Newline you deleted.
343
344Remember that most Emacs commands can be given a repeat count;
82e312c7
RS
345this includes text characters. Repeating a text character inserts
346it several times.
f751376f 347
82e312c7 348>> Try that now -- type C-u 8 * to insert ********.
f751376f
JB
349
350You've now learned the most basic way of typing something in
351Emacs and correcting errors. You can delete by words or lines
352as well. Here is a summary of the delete operations:
353
41835686
LK
354 <Delback> Delete the character just before the cursor
355 C-d Delete the next character after the cursor
f751376f 356
41835686
LK
357 M-<Delback> Kill the word immediately before the cursor
358 M-d Kill the next word after the cursor
f751376f 359
41835686
LK
360 C-k Kill from the cursor position to end of line
361 M-k Kill to the end of the current sentence
f751376f 362
d6635fa1
RS
363Notice that <Delback> and C-d vs M-<Delback> and M-d extend the parallel
364started by C-f and M-f (well, <Delback> is not really a control
f751376f
JB
365character, but let's not worry about that). C-k and M-k are like C-e
366and M-e, sort of, in that lines are opposite sentences.
367
41835686
LK
368You can also kill any part of the text with one uniform method. Move
369to one end of that part, and type C-@ or C-<SPC> (either one). (<SPC>
370is the Space bar.) Move to the other end of that part, and type C-w.
371That kills all the text between the two positions.
6f311043
KH
372
373>> Move the cursor to the Y at the start of the previous paragraph.
41835686 374>> Type C-<SPC>. Emacs should display a message "Mark set"
6f311043
KH
375 at the bottom of the screen.
376>> Move the cursor to the n in "end", on the second line of the
377 paragraph.
378>> Type C-w. This will kill the text starting from the Y,
379 and ending just before the n.
380
5b85892b
RS
381The difference between "killing" and "deleting" is that "killed" text
382can be reinserted, whereas "deleted" things cannot be reinserted.
383Reinsertion of killed text is called "yanking". Generally, the
384commands that can remove a lot of text kill the text (they set up so
385that you can yank the text), while the commands that remove just one
3d9a3367
RS
386character, or only remove blank lines and spaces, do deletion (so you
387cannot yank that text).
f751376f 388
82e312c7
RS
389>> Move the cursor to the beginning of a line which is not empty.
390 Then type C-k to kill the text on that line.
391>> Type C-k a second time. You'll see that it kills the Newline
392 which follows that line.
f751376f
JB
393
394Note that a single C-k kills the contents of the line, and a second
6f108a37 395C-k kills the line itself, and makes all the other lines move up. C-k
82e312c7
RS
396treats a numeric argument specially: it kills that many lines AND
397their contents. This is not mere repetition. C-u 2 C-k kills two
398lines and their newlines; typing C-k twice would not do that.
f751376f 399
5b85892b
RS
400Bringing back killed text is called "yanking". (Think of it as
401yanking back, or pulling back, some text that was taken away.) You
402can yank the killed text either at the same place where it was killed,
41835686
LK
403or at some other place in the text you are editing, or even in a
404different file. You can yank the same text several times; that makes
405multiple copies of it.
5b85892b
RS
406
407The command for yanking is C-y. It reinserts the last killed text,
408at the current cursor position.
f751376f
JB
409
410>> Try it; type C-y to yank the text back.
411
5b85892b
RS
412If you do several C-k's in a row, all of the killed text is saved
413together, so that one C-y will yank all of the lines at once.
f751376f
JB
414
415>> Do this now, type C-k several times.
416
417Now to retrieve that killed text:
418
419>> Type C-y. Then move the cursor down a few lines and type C-y
420 again. You now see how to copy some text.
421
422What do you do if you have some text you want to yank back, and then
423you kill something else? C-y would yank the more recent kill. But
424the previous text is not lost. You can get back to it using the M-y
425command. After you have done C-y to get the most recent kill, typing
bec1289c 426M-y replaces that yanked text with the previous kill. Typing M-y
82e312c7
RS
427again and again brings in earlier and earlier kills. When you have
428reached the text you are looking for, you do not have to do anything to
429keep it. Just go on with your editing, leaving the yanked text where
430it is.
431
432If you M-y enough times, you come back to the starting point (the most
433recent kill).
f751376f
JB
434
435>> Kill a line, move around, kill another line.
436 Then do C-y to get back the second killed line.
437 Then do M-y and it will be replaced by the first killed line.
438 Do more M-y's and see what you get. Keep doing them until
439 the second kill line comes back, and then a few more.
440 If you like, you can try giving M-y positive and negative
441 arguments.
442
443
26dc36e6
JB
444* UNDO
445------
f751376f 446
82e312c7
RS
447If you make a change to the text, and then decide that it was a
448mistake, you can undo the change with the undo command, C-x u.
449
450Normally, C-x u undoes the changes made by one command; if you repeat
451the C-x u several times in a row, each repetition undoes one
452additional command.
453
454But there are two exceptions: commands that do not change the text do
455not count (this includes cursor motion commands and scrolling
456command), and self-inserting characters are usually handled in groups
457of up to 20. (This is to reduce the number of C-x u's you have to
458type to undo insertion of text.)
f751376f
JB
459
460>> Kill this line with C-k, then type C-x u and it should reappear.
461
82e312c7
RS
462C-_ is an alternative undo command; it works just the same as C-x u,
463but it is easier to type several times in a row. The disadvantage of
464C-_ is that on some keyboards it is not obvious how to type it. That
465is why we provide C-x u as well. On some terminals, you can type C-_
8806d20f 466by typing / while holding down CONTROL.
f751376f 467
82e312c7 468A numeric argument to C-_ or C-x u acts as a repeat count.
f751376f 469
5b85892b
RS
470You can undo deletion of text just as you can undo killing of text.
471The distinction between killing something and deleting it affects
472whether you can yank it with C-y; it makes no difference for undo.
473
f751376f 474
26dc36e6
JB
475* FILES
476-------
f751376f
JB
477
478In order to make the text you edit permanent, you must put it in a
479file. Otherwise, it will go away when your invocation of Emacs goes
8806d20f
RS
480away. In order to put your text in a file, you must "find" the file
481before you enter the text. (This is also called "visiting" the file.)
82e312c7
RS
482
483Finding a file means that you see the contents of the file within
484Emacs. In many ways, it is as if you were editing the file itself.
485However, the changes you make using Emacs do not become permanent
486until you "save" the file. This is so you can avoid leaving a
487half-changed file on the system when you do not want to. Even when
488you save, Emacs leaves the original file under a changed name in case
489you later decide that your changes were a mistake.
f751376f
JB
490
491If you look near the bottom of the screen you will see a line that
3c72adf2
RS
492begins and ends with dashes, and starts with "--:-- TUTORIAL" or
493something like that. This part of the screen normally shows the name
494of the file that you are visiting. Right now, you are visiting a file
495called "TUTORIAL" which is your personal scratch copy of the Emacs
496tutorial. When you find a file with Emacs, that file's name will
497appear in that precise spot.
f751376f 498
8806d20f
RS
499One special thing about the command for finding a file is that you
500have to say what file name you want. We say the command "reads an
501argument from the terminal" (in this case, the argument is the name of
502the file). After you type the command
f751376f
JB
503
504 C-x C-f Find a file
505
82e312c7
RS
506Emacs asks you to type the file name. The file name you type appears
507on the bottom line of the screen. The bottom line is called the
508minibuffer when it is used for this sort of input. You can use
509ordinary Emacs editing commands to edit the file name.
510
511While you are entering the file name (or any minibuffer input),
512you can cancel the command with C-g.
f751376f
JB
513
514>> Type C-x C-f, then type C-g. This cancels the minibuffer,
515 and also cancels the C-x C-f command that was using the
516 minibuffer. So you do not find any file.
517
82e312c7
RS
518When you have finished entering the file name, type <Return> to
519terminate it. Then C-x C-f command goes to work, and finds the file
520you chose. The minibuffer disappears when the C-x C-f command is
521finished.
522
523In a little while the file contents appear on the screen, and you can
524edit the contents. When you wish to make your changes permanent,
525type the command
f751376f
JB
526
527 C-x C-s Save the file
528
82e312c7
RS
529This copies the text within Emacs into the file. The first time you
530do this, Emacs renames the original file to a new name so that it is
531not lost. The new name is made by adding "~" to the end of the
532original file's name.
f751376f 533
fafee579 534When saving is finished, Emacs displays the name of the file written.
f751376f
JB
535You should save fairly often, so that you will not lose very much
536work if the system should crash.
537
538>> Type C-x C-s, saving your copy of the tutorial.
fafee579 539 This should show "Wrote ...TUTORIAL" at the bottom of the screen.
f751376f 540
afb7440b
RS
541NOTE: On some systems, typing C-x C-s will freeze the screen and you
542will see no further output from Emacs. This indicates that an
543operating system "feature" called "flow control" is intercepting the
544C-s and not letting it get through to Emacs. To unfreeze the screen,
545type C-q. Then see the section "Spontaneous Entry to Incremental
546Search" in the Emacs manual for advice on dealing with this "feature".
547
82e312c7
RS
548You can find an existing file, to view it or edit it. You can also
549find a file which does not already exist. This is the way to create a
550file with Emacs: find the file, which will start out empty, and then
551begin inserting the text for the file. When you ask to "save" the
552file, Emacs will really create the file with the text that you have
553inserted. From then on, you can consider yourself to be editing an
554already existing file.
f751376f
JB
555
556
26dc36e6
JB
557* BUFFERS
558---------
f751376f
JB
559
560If you find a second file with C-x C-f, the first file remains
561inside Emacs. You can switch back to it by finding it again with
562C-x C-f. This way you can get quite a number of files inside Emacs.
563
82e312c7
RS
564>> Create a file named "foo" by typing C-x C-f foo <Return>.
565 Then insert some text, edit it, and save "foo" by typing C-x C-s.
566 Finally, type C-x C-f TUTORIAL <Return>
567 to come back to the tutorial.
568
73635959 569Emacs stores each file's text inside an object called a "buffer".
82e312c7 570Finding a file makes a new buffer inside Emacs. To see a list of the
73635959 571buffers that currently exist in your Emacs job, type
f751376f
JB
572
573 C-x C-b List buffers
574
575>> Try C-x C-b now.
576
8d60818b
RS
577See how each buffer has a name, and it may also have a file name for
578the file whose contents it holds. ANY text you see in an Emacs window
82e312c7 579is always part of some buffer.
f751376f
JB
580
581>> Type C-x 1 to get rid of the buffer list.
582
f458a8e0 583When you have several buffers, only one of them is "current" at any
8d60818b
RS
584time. That buffer is the one you edit. If you want to edit another
585buffer, you need to "switch" to it. If you want to switch to a buffer
586that corresponds to a file, you can do it by visiting the file again
587with C-x C-f. But there is an easier way: use the C-x b command.
588In that command, you have to type the buffer's name.
589
590>> Type C-x b foo <Return> to go back to the buffer "foo" which holds
591 the text of the file "foo". Then type C-x b TUTORIAL <Return>
592 to come back to this tutorial.
593
594Most of the time, the buffer's name is the same as the file name
595(without the file directory part). However, this is not always true.
596The buffer list you make with C-x C-b always shows you the name of
597every buffer.
598
599ANY text you see in an Emacs window is always part of some buffer.
600Some buffers do not correspond to files. For example, the buffer
601named "*Buffer List*" does not have any file. It is the buffer which
602contains the buffer list that you made with C-x C-b. The buffer named
603"*Messages*" also does not correspond to any file; it contains the
604messages that have appeared on the bottom line during your Emacs
605session.
606
607>> Type C-x b *Messages* <Return> to look at the buffer of messages.
ff7de4ee 608 Then type C-x b TUTORIAL <Return> to come back to this tutorial.
8d60818b 609
f751376f
JB
610If you make changes to the text of one file, then find another file,
611this does not save the first file. Its changes remain inside Emacs,
612in that file's buffer. The creation or editing of the second file's
613buffer has no effect on the first file's buffer. This is very useful,
614but it also means that you need a convenient way to save the first
615file's buffer. It would be a nuisance to have to switch back to
616it with C-x C-f in order to save it with C-x C-s. So we have
617
618 C-x s Save some buffers
619
82e312c7
RS
620C-x s asks you about each buffer which contains changes that you have
621not saved. It asks you, for each such buffer, whether to save the
622buffer.
f751376f 623
82e312c7
RS
624>> Insert a line of text, then type C-x s.
625 It should ask you whether to save the buffer named TUTORIAL.
626 Answer yes to the question by typing "y".
f751376f 627
5577e2b2 628
26dc36e6
JB
629* EXTENDING THE COMMAND SET
630---------------------------
f751376f
JB
631
632There are many, many more Emacs commands than could possibly be put
633on all the control and meta characters. Emacs gets around this with
634the X (eXtend) command. This comes in two flavors:
635
636 C-x Character eXtend. Followed by one character.
637 M-x Named command eXtend. Followed by a long name.
638
639These are commands that are generally useful but used less than the
41835686
LK
640commands you have already learned about. You have already seen a few
641of them: the file commands C-x C-f to Find and C-x C-s to Save, for
642example. Another example is the command to end the Emacs
643session--this is the command C-x C-c. (Do not worry about losing
644changes you have made; C-x C-c offers to save each changed file before
645it kills the Emacs.)
f751376f 646
e7662099
RS
647C-z is the command to exit Emacs *temporarily*--so that you can go
648back to the same Emacs session afterward.
649
82e312c7
RS
650On systems which allow it, C-z "suspends" Emacs; that is, it returns
651to the shell but does not destroy the Emacs. In the most common
652shells, you can resume Emacs with the `fg' command or with `%emacs'.
653
654On systems which do not implement suspending, C-z creates a subshell
655running under Emacs to give you the chance to run other programs and
656return to Emacs afterward; it does not truly "exit" from Emacs. In
657this case, the shell command `exit' is the usual way to get back to
658Emacs from the subshell.
e7662099
RS
659
660The time to use C-x C-c is when you are about to log out. It's also
661the right thing to use to exit an Emacs invoked under mail handling
82e312c7
RS
662programs and other miscellaneous utilities, since they may not know
663how to cope with suspension of Emacs. In ordinary circumstances,
664though, if you are not about to log out, it is better to suspend Emacs
665with C-z instead of exiting Emacs.
f751376f 666
82e312c7 667There are many C-x commands. Here is a list of the ones you have learned:
f751376f 668
41835686
LK
669 C-x C-f Find file
670 C-x C-s Save file
671 C-x s Save some buffers
672 C-x C-b List buffers
673 C-x b Switch buffer
674 C-x C-c Quit Emacs
675 C-x 1 Delete all but one window
676 C-x u Undo
f751376f
JB
677
678Named eXtended commands are commands which are used even less
82e312c7
RS
679frequently, or commands which are used only in certain modes. An
680example is the command replace-string, which globally replaces one
681string with another. When you type M-x, Emacs prompts you at the
682bottom of the screen with M-x and you should type the name of the
683command; in this case, "replace-string". Just type "repl s<TAB>" and
dcb14dc0 684Emacs will complete the name. (<TAB> is the Tab key, usually found
2f6e6410 685above the CapsLock or Shift key near the left edge of the keyboard.)
dcb14dc0 686End the command name with <Return>.
82e312c7
RS
687
688The replace-string command requires two arguments--the string to be
689replaced, and the string to replace it with. You must end each
690argument with <Return>.
f751376f
JB
691
692>> Move the cursor to the blank line two lines below this one.
693 Then type M-x repl s<Return>changed<Return>altered<Return>.
694
695 Notice how this line has changed: you've replaced
82e312c7
RS
696 the word c-h-a-n-g-e-d with "altered" wherever it occurred,
697 after the initial position of the cursor.
f751376f
JB
698
699
4a630427
RS
700* AUTO SAVE
701-----------
702
703When you have made changes in a file, but you have not saved them yet,
704they could be lost if your computer crashes. To protect you from
82e312c7
RS
705this, Emacs periodically writes an "auto save" file for each file that
706you are editing. The auto save file name has a # at the beginning and
707the end; for example, if your file is named "hello.c", its auto save
708file's name is "#hello.c#". When you save the file in the normal way,
709Emacs deletes its auto save file.
4a630427
RS
710
711If the computer crashes, you can recover your auto-saved editing by
712finding the file normally (the file you were editing, not the auto
73635959
KH
713save file) and then typing M-x recover file<Return>. When it asks for
714confirmation, type yes<Return> to go ahead and recover the auto-save
4a630427
RS
715data.
716
717
82e312c7 718* ECHO AREA
26dc36e6 719-----------
f751376f 720
e64159dd
RS
721If Emacs sees that you are typing multicharacter commands slowly, it
722shows them to you at the bottom of the screen in an area called the
723"echo area". The echo area contains the bottom line of the screen.
f751376f 724
f751376f 725
82e312c7
RS
726* MODE LINE
727-----------
728
e64159dd 729The line immediately above the echo area is called the "mode line".
82e312c7
RS
730The mode line says something like this:
731
41835686 732--:** TUTORIAL 63% L749 (Fundamental)-----------------------
82e312c7
RS
733
734This line gives useful information about the status of Emacs and
735the text you are editing.
f751376f
JB
736
737You already know what the filename means--it is the file you have
41835686
LK
738found. NN% indicates your current position in the text; it means that
739NN percent of the text is above the top of the screen. If the top of
740the file is on the screen, it will say "Top" instead of " 0%". If the
741bottom of the text is on the screen, it will say "Bot". If you are
742looking at text so small that all of it fits on the screen, the mode
743line says "All".
f751376f 744
dcf671d2
GM
745The L and digits indicate position in another way: they give the
746current line number of point.
747
f751376f 748The stars near the front mean that you have made changes to the text.
82e312c7
RS
749Right after you visit or save a file, that part of the mode line shows
750no stars, just dashes.
f751376f
JB
751
752The part of the mode line inside the parentheses is to tell you what
82e312c7 753editing modes you are in. The default mode is Fundamental which is
177c0ea7 754what you are using now. It is an example of a "major mode".
82e312c7
RS
755
756Emacs has many different major modes. Some of them are meant for
bec1289c 757editing different languages and/or kinds of text, such as Lisp mode,
82e312c7
RS
758Text mode, etc. At any time one and only one major mode is active,
759and its name can always be found in the mode line just where
760"Fundamental" is now.
761
762Each major mode makes a few commands behave differently. For example,
763there are commands for creating comments in a program, and since each
764programming language has a different idea of what a comment should
765look like, each major mode has to insert comments differently. Each
766major mode is the name of an extended command, which is how you can
bec1289c 767switch to that mode. For example, M-x fundamental-mode is a command to
82e312c7 768switch to Fundamental mode.
f751376f 769
ab380f51 770If you are going to be editing human-language text, such as this file, you
f751376f 771should probably use Text Mode.
41835686 772
73635959 773>> Type M-x text mode<Return>.
f751376f 774
e64159dd 775Don't worry, none of the Emacs commands you have learned changes in
82e312c7
RS
776any great way. But you can observe that M-f and M-b now treat
777apostrophes as part of words. Previously, in Fundamental mode,
778M-f and M-b treated apostrophes as word-separators.
f751376f 779
82e312c7
RS
780Major modes usually make subtle changes like that one: most commands
781do "the same job" in each major mode, but they work a little bit
782differently.
783
784To view documentation on your current major mode, type C-h m.
f751376f
JB
785
786>> Use C-u C-v once or more to bring this line near the top of screen.
787>> Type C-h m, to see how Text mode differs from Fundamental mode.
788>> Type C-x 1 to remove the documentation from the screen.
789
790Major modes are called major because there are also minor modes.
6f108a37 791Minor modes are not alternatives to the major modes, just minor
bec1289c
KH
792modifications of them. Each minor mode can be turned on or off by
793itself, independent of all other minor modes, and independent of your
794major mode. So you can use no minor modes, or one minor mode, or any
795combination of several minor modes.
f751376f 796
ab380f51
RS
797One minor mode which is very useful, especially for editing
798human-language text, is Auto Fill mode. When this mode is on, Emacs
799breaks the line in between words automatically whenever you insert
800text and make a line that is too wide.
82e312c7 801
48cc32f0 802You can turn Auto Fill mode on by doing M-x auto fill mode<Return>.
6f108a37 803When the mode is on, you can turn it off again by doing M-x
48cc32f0 804auto fill mode<Return>. If the mode is off, this command turns it on,
82e312c7
RS
805and if the mode is on, this command turns it off. We say that the
806command "toggles the mode".
f751376f 807
48cc32f0 808>> Type M-x auto fill mode<Return> now. Then insert a line of "asdf "
f751376f
JB
809 over again until you see it divide into two lines. You must put in
810 spaces between them because Auto Fill breaks lines only at spaces.
811
812The margin is usually set at 70 characters, but you can change it
813with the C-x f command. You should give the margin setting you want
814as a numeric argument.
815
816>> Type C-x f with an argument of 20. (C-u 2 0 C-x f).
817 Then type in some text and see Emacs fill lines of 20
818 characters with it. Then set the margin back to 70 using
819 C-x f again.
820
e64159dd 821If you make changes in the middle of a paragraph, Auto Fill mode
f751376f 822does not re-fill it for you.
1e78d347 823To re-fill the paragraph, type M-q (META-q) with the cursor inside
f751376f
JB
824that paragraph.
825
826>> Move the cursor into the previous paragraph and type M-q.
827
5577e2b2 828
26dc36e6
JB
829* SEARCHING
830-----------
f751376f
JB
831
832Emacs can do searches for strings (these are groups of contiguous
82e312c7
RS
833characters or words) either forward through the text or backward
834through it. Searching for a string is a cursor motion command;
835it moves the cursor to the next place where that string appears.
836
837The Emacs search command is different from the search commands
838of most editors, in that it is "incremental". This means that the
839search happens while you type in the string to search for.
840
841The command to initiate a search is C-s for forward search, and C-r
842for reverse search. BUT WAIT! Don't try them now.
843
844When you type C-s you'll notice that the string "I-search" appears as
845a prompt in the echo area. This tells you that Emacs is in what is
846called an incremental search waiting for you to type the thing that
8806d20f 847you want to search for. <Return> terminates a search.
f751376f
JB
848
849>> Now type C-s to start a search. SLOWLY, one letter at a time,
850 type the word 'cursor', pausing after you type each
851 character to notice what happens to the cursor.
82e312c7
RS
852 Now you have searched for "cursor", once.
853>> Type C-s again, to search for the next occurrence of "cursor".
d6635fa1 854>> Now type <Delback> four times and see how the cursor moves.
8806d20f 855>> Type <Return> to terminate the search.
f751376f
JB
856
857Did you see what happened? Emacs, in an incremental search, tries to
82e312c7
RS
858go to the occurrence of the string that you've typed out so far. To
859go to the next occurrence of 'cursor' just type C-s again. If no such
6f108a37
RS
860occurrence exists, Emacs beeps and tells you the search is currently
861"failing". C-g would also terminate the search.
f751376f 862
afb7440b
RS
863NOTE: On some systems, typing C-s will freeze the screen and you will
864see no further output from Emacs. This indicates that an operating
865system "feature" called "flow control" is intercepting the C-s and not
866letting it get through to Emacs. To unfreeze the screen, type C-q.
867Then see the section "Spontaneous Entry to Incremental Search" in the
868Emacs manual for advice on dealing with this "feature".
869
d6635fa1 870If you are in the middle of an incremental search and type <Delback>,
f751376f
JB
871you'll notice that the last character in the search string is erased
872and the search backs up to the last place of the search. For
82e312c7
RS
873instance, suppose you have typed "c", to search for the first
874occurrence of "c". Now if you type "u", the cursor will move
d6635fa1 875to the first occurrence of "cu". Now type <Delback>. This erases
82e312c7
RS
876the "u" from the search string, and the cursor moves back to
877the first occurrence of "c".
f751376f 878
3242b6f0
RS
879If you are in the middle of a search and type a control or meta
880character (with a few exceptions--characters that are special in
881a search, such as C-s and C-r), the search is terminated.
f751376f
JB
882
883The C-s starts a search that looks for any occurrence of the search
82e312c7
RS
884string AFTER the current cursor position. If you want to search for
885something earlier in the text, type C-r instead. Everything that we
886have said about C-s also applies to C-r, except that the direction of
887the search is reversed.
f751376f
JB
888
889
26dc36e6
JB
890* MULTIPLE WINDOWS
891------------------
e652a34a
JB
892
893One of the nice features of Emacs is that you can display more than one
894window on the screen at the same time.
895
1e78d347
PJ
896>> Move the cursor to this line and type C-u 0 C-l (that's CONTROL-L, not
897 CONTROL-1).
e652a34a
JB
898
899>> Now type C-x 2 which splits the screen into two windows.
900 Both windows display this tutorial. The cursor stays in the top window.
901
902>> Type C-M-v to scroll the bottom window.
41835686 903 (If you do not have a real META key, type <ESC> C-v.)
e652a34a
JB
904
905>> Type C-x o ("o" for "other") to move the cursor to the bottom window.
906>> Use C-v and M-v in the bottom window to scroll it.
907 Keep reading these directions in the top window.
908
909>> Type C-x o again to move the cursor back to the top window.
82e312c7 910 The cursor in the top window is just where it was before.
e652a34a
JB
911
912You can keep using C-x o to switch between the windows. Each
913window has its own cursor position, but only one window actually
914shows the cursor. All the ordinary editing commands apply to the
82e312c7 915window that the cursor is in. We call this the "selected window".
e652a34a
JB
916
917The command C-M-v is very useful when you are editing text in one
918window and using the other window just for reference. You can keep
82e312c7
RS
919the cursor always in the window where you are editing, and advance
920through the other window sequentially with C-M-v.
e652a34a 921
8a4aff68 922C-M-v is an example of a CONTROL-META character. If you have a real
8806d20f
RS
923META key, you can type C-M-v by holding down both CONTROL and META while
924typing v. It does not matter whether CONTROL or META "comes first,"
82e312c7 925because both of these keys act by modifying the characters you type.
8a4aff68 926
41835686
LK
927If you do not have a real META key, and you use <ESC> instead, the
928order does matter: you must type <ESC> followed by CONTROL-v, because
929CONTROL-<ESC> v will not work. This is because <ESC> is a character
930in its own right, not a modifier key.
8a4aff68 931
e652a34a
JB
932>> Type C-x 1 (in the top window) to get rid of the bottom window.
933
934(If you had typed C-x 1 in the bottom window, that would get rid
935of the top one. Think of this command as "Keep just one
936window--the window I am already in.")
937
82e312c7
RS
938You do not have to display the same buffer in both windows. If you
939use C-x C-f to find a file in one window, the other window does not
940change. You can find a file in each window independently.
e652a34a
JB
941
942Here is another way to use two windows to display two different
943things:
944
945>> Type C-x 4 C-f followed by the name of one of your files.
82e312c7 946 End with <Return>. See the specified file appear in the bottom
e652a34a
JB
947 window. The cursor goes there, too.
948
949>> Type C-x o to go back to the top window, and C-x 1 to delete
950 the bottom window.
951
952
26dc36e6
JB
953* RECURSIVE EDITING LEVELS
954--------------------------
f751376f
JB
955
956Sometimes you will get into what is called a "recursive editing
957level". This is indicated by square brackets in the mode line,
958surrounding the parentheses around the major mode name. For
959example, you might see [(Fundamental)] instead of (Fundamental).
960
41835686
LK
961To get out of the recursive editing level, type <ESC> <ESC> <ESC>.
962That is an all-purpose "get out" command. You can also use it for
963eliminating extra windows, and getting out of the minibuffer.
f751376f 964
41835686
LK
965>> Type M-x to get into a minibuffer; then type <ESC> <ESC> <ESC> to
966 get out.
f751376f 967
82e312c7
RS
968You cannot use C-g to get out of a recursive editing level. This is
969because C-g is used for canceling commands and arguments WITHIN the
970recursive editing level.
f751376f
JB
971
972
26dc36e6
JB
973* GETTING MORE HELP
974-------------------
f751376f
JB
975
976In this tutorial we have tried to supply just enough information to
977get you started using Emacs. There is so much available in Emacs that
978it would be impossible to explain it all here. However, you may want
82e312c7
RS
979to learn more about Emacs since it has many other useful features.
980Emacs provides commands for reading documentation about Emacs
981commands. These "help" commands all start with the character
1e78d347 982CONTROL-h, which is called "the Help character".
f751376f 983
82e312c7 984To use the Help features, type the C-h character, and then a
f751376f
JB
985character saying what kind of help you want. If you are REALLY lost,
986type C-h ? and Emacs will tell you what kinds of help it can give.
82e312c7 987If you have typed C-h and decide you do not want any help, just
3242b6f0 988type C-g to cancel it.
f751376f 989
1c71da93
RS
990(Some sites change the meaning of the character C-h. They really
991should not do this as a blanket measure for all users, so you have
992grounds to complain to the system administrator. Meanwhile, if C-h
993does not display a message about help at the bottom of the screen, try
8806d20f 994typing the F1 key or M-x help <Return> instead.)
1c71da93
RS
995
996The most basic HELP feature is C-h c. Type C-h, the character c, and
997a command character or sequence; then Emacs displays a very brief
f751376f
JB
998description of the command.
999
dcf671d2 1000>> Type C-h c C-p.
ff7de4ee
RS
1001
1002The message should be something like this:
f751376f
JB
1003
1004 C-p runs the command previous-line
1005
82e312c7
RS
1006This tells you the "name of the function". Function names are used
1007mainly for customizing and extending Emacs. But since function names
1008are chosen to indicate what the command does, they can serve also as
1009very brief documentation--sufficient to remind you of commands you
1010have already learned.
f751376f
JB
1011
1012Multi-character commands such as C-x C-s and (if you have no META or
bec1289c 1013EDIT or ALT key) <ESC>v are also allowed after C-h c.
f751376f 1014
82e312c7 1015To get more information about a command, use C-h k instead of C-h c.
f751376f 1016
dcf671d2 1017>> Type C-h k C-p.
f751376f 1018
10a4c11f
JB
1019This displays the documentation of the function, as well as its
1020name, in an Emacs window. When you are finished reading the
1021output, type C-x 1 to get rid of the help text. You do not have
1022to do this right away. You can do some editing while referring
82e312c7 1023to the help text, and then type C-x 1.
f751376f
JB
1024
1025Here are some other useful C-h options:
1026
1027 C-h f Describe a function. You type in the name of the
1028 function.
1029
1030>> Try typing C-h f previous-line<Return>.
fafee579 1031 This displays all the information Emacs has about the
3242b6f0 1032 function which implements the C-p command.
f751376f 1033
fafee579 1034A similar command C-h v displays the documentation of variables whose
ee31752e
EZ
1035values you can set to customize Emacs behavior. You need to type in
1036the name of the variable when Emacs prompts for it.
1037
f751376f
JB
1038 C-h a Command Apropos. Type in a keyword and Emacs will list
1039 all the commands whose names contain that keyword.
1e78d347 1040 These commands can all be invoked with META-x.
f751376f 1041 For some commands, Command Apropos will also list a one
bec1289c 1042 or two character sequence which runs the same command.
f751376f 1043
10a4c11f
JB
1044>> Type C-h a file<Return>.
1045
82e312c7
RS
1046This displays in another window a list of all M-x commands with "file"
1047in their names. You will see character-commands like C-x C-f listed
1048beside the corresponding command names such as find-file.
10a4c11f
JB
1049
1050>> Type C-M-v to scroll the help window. Do this a few times.
1051
1052>> Type C-x 1 to delete the help window.
f751376f 1053
ee31752e
EZ
1054 C-h i Read On-line Manuals (a.k.a. Info). This command puts
1055 you into a special buffer called `*info*' where you
1056 can read on-line manuals for the packages installed on
1057 your system. Type m emacs <Return> to read the Emacs
1058 manual. If you have never before used Info, type ?
1059 and Emacs will take you on a guided tour of Info mode
1060 facilities. Once you are through with this tutorial,
1061 you should consult the Emacs Info manual as your
1062 primary documentation.
1063
f751376f 1064
da40fe46
RS
1065* MORE FEATURES
1066---------------
1067
1068You can learn more about Emacs by reading its manual, either as a book
1069or on-line in Info (use the Help menu or type F10 h r). Two features
1070that you may like especially are completion, which saves typing, and
1071dired, which simplifies file handling.
1072
1073Completion is a way to avoid unnecessary typing. For instance, if you
1074want to switch to the *Messages* buffer, you can type C-x b *M<Tab>
1075and Emacs will fill in the rest of the buffer name as far as it can
1076determine from what you have already typed. Completion is described
1077in Info in the Emacs manual in the node called "Completion".
1078
1079Dired enables you to list files in a directory (and optionally its
1080subdirectories), move around that list, visit, rename, delete and
1081otherwise operate on the files. Dired is described in Info in the
1082Emacs manual in the node called "Dired".
1083
1084The manual also describes many other Emacs features.
1085
1086
26dc36e6
JB
1087* CONCLUSION
1088------------
f751376f
JB
1089
1090Remember, to exit Emacs permanently use C-x C-c. To exit to a shell
82e312c7 1091temporarily, so that you can come back to Emacs afterward, use C-z.
f751376f
JB
1092
1093This tutorial is meant to be understandable to all new users, so if
1094you found something unclear, don't sit and blame yourself - complain!
1095
1096
5577e2b2
KH
1097* COPYING
1098---------
f751376f
JB
1099
1100This tutorial descends from a long line of Emacs tutorials
1101starting with the one written by Stuart Cracraft for the original Emacs.
1102
1103This version of the tutorial, like GNU Emacs, is copyrighted, and
1104comes with permission to distribute copies on certain conditions:
1105
bfd6d01a 1106Copyright (C) 1985, 1996, 1998, 2001, 2002, 2003, 2004,
5b0d63bc 1107 2005, 2006 Free Software Foundation, Inc.
f751376f
JB
1108
1109 Permission is granted to anyone to make or distribute verbatim copies
1110 of this document as received, in any medium, provided that the
1111 copyright notice and permission notice are preserved,
1112 and that the distributor grants the recipient permission
1113 for further redistribution as permitted by this notice.
1114
1115 Permission is granted to distribute modified versions
1116 of this document, or of portions of it,
1117 under the above conditions, provided also that they
1118 carry prominent notices stating who last altered them.
1119
82e312c7
RS
1120The conditions for copying Emacs itself are more complex, but in the
1121same spirit. Please read the file COPYING and then do give copies of
1122GNU Emacs to your friends. Help stamp out software obstructionism
1123("ownership") by using, writing, and sharing free software!
ab5796a9
MB
1124
1125;;; arch-tag: a0f84628-777f-4238-8865-451a73167f55