Annotation of src/usr.bin/mg/tutorial, Revision 1.2
1.1 deraadt 1: Copyright (c) 1985 Richard M. Stallman. See end for copying conditions.
2:
3: You are looking at the Emacs tutorial.
4:
5: Emacs commands generally involve the CONTROL key or the META (ESC)
6: key. Rather than write out META or CONTROL each time we want you to
7: prefix a character, we'll use the following abbreviations:
8:
9: C-<chr> means hold the CONTROL key while typing the character <chr>
10: Thus, C-f would be: hold the CONTROL key and type f.
11: M-<chr> means type <ESC>, release it, then type the character <chr>.
12:
13: The characters ">>" at the left margin indicate directions for you to
14: try using a command. For instance:
15:
16: >> Now type C-v (View next screen) to move to the next screen.
17: (go ahead, do it by depressing the control key and v together).
18: From now on, you'll be expected to do this whenever you finish
19: reading the screen.
20:
21: Note that there is an overlap when going from screen to screen; this
22: provides some continuity when moving through the file.
23:
24: The first thing that you need to know is how to move around from
25: place to place in the file. You already know how to move forward a
26: screen, with C-v. To move backwards a screen, type M-v (type <ESC>v).
27:
28: >> Try typing M-v and then C-v to move back and forth a few times.
29:
30:
31: SUMMARY
32: -------
33:
34: The following commands are useful for viewing screenfuls:
35:
36: C-v Move forward one screenful
37: M-v Move backward one screenful
38: C-l Clear screen and redisplay everything
39: putting the text near the cursor at the center.
40: (That's control-L, not control-1.
41: There is no such character as control-1.)
42:
43: >> Find the cursor and remember what text is near it.
44: Then type a C-l.
45: Find the cursor again and see what text is near it now.
46:
47:
48: BASIC CURSOR CONTROL
49: --------------------
50:
51: Getting from screenful to screenful is useful, but how do you
52: reposition yourself within a given screen to a specific place? There
53: are several ways you can do this. One way (not the best, but the most
54: basic) is to use the commands previous, backward, forward and next.
55: As you can imagine these commands (which are given to Emacs as C-p,
56: C-b, C-f, and C-n respectively) move the cursor from where it
57: currently is to a new place in the given direction. It is also
58: possible to move the cursor with the arrow keys, but this requires you
59: move your hand from the keyboard, it is also not supported on other
60: machines that do support Emacs. Emacs runs on everything from a CP/M
61: machine to large mainframes. Here then, in a more graphical form are
62: the commands:
1.2 ! mickey 63:
1.1 deraadt 64: Previous line, C-p
65: :
66: :
67: Backward, C-b .... Current cursor position .... Forward, C-f
68: :
69: :
70: Next line, C-n
71:
72: >> Move the cursor to the line in the middle of that diagram
73: and type C-l to see the whole diagram centered in the screen.
74:
75: You'll probably find it easy to think of these by letter. P for
76: previous, N for next, B for backward and F for forward. These are
77: the basic cursor positioning commands and you'll be using them ALL
78: the time so it would be of great benefit if you learn them now.
79:
80: >> Do a few C-n's to bring the cursor down to this line.
81:
82: >> Move into the line with C-f's and then up with C-p's.
83: See what C-p does when the cursor is in the middle of the line.
84:
85: >> Try to C-b at the beginning of a line. Do a few more C-b's.
86: Then do C-f's back to the end of the line and beyond.
87:
88: When you go off the top or bottom of the screen, the text beyond
89: the edge is shifted onto the screen so that your instructions can
90: be carried out while keeping the cursor on the screen.
91:
92: >> Try to move the cursor off the bottom of the screen with C-n and
93: see what happens.
94:
95: If moving by characters is too slow, you can move by words. M-f
96: (ESC-f) moves forward a word and M-b moves back a word.
97:
98: >> Type a few M-f's and M-b's. Intersperse them with C-f's and C-b's.
99:
100: Notice the parallel between C-f and C-b on the one hand, and M-f and
101: M-b on the other hand. Very often Meta characters are used for
102: operations related to English text whereas Control characters operate
103: on the basic textual units that are independent of what you are
104: editing (characters, lines, etc). C-a and C-e move to the beginning or
105: end of a line.
106:
107: >> Try a couple of C-a's, and then a couple of C-e's.
108: See how repeated C-a's do nothing.
109:
110: Two other simple cursor motion commands are M-< (Meta Less-than),
111: which moves to the beginning of the file, and M-> (Meta Greater-than),
112: which moves to the end of the file. You probably don't need to try
113: them, since finding this spot again will be boring. On most terminals
114: the "<" is above the comma and you must use the shift key to type it.
115: On these terminals you must use the shift key to type M-< also;
116: without the shift key, you would be typing M-comma.
117:
118: The location of the cursor in the text is also called "point". To
119: paraphrase, the cursor shows on the screen where point is located in
120: the text.
121:
122: Here is a summary of simple moving operations including the word and
123: sentence moving commands:
124:
125: C-f Move forward a character
126: C-b Move backward a character
127:
128: M-f Move forward a word
129: M-b Move backward a word
130:
131: c-n Move to next line
132: C-p Move to previous line
133:
134: C-a Move to beginning of line
135: C-e Move to end of line
136:
137: M-< Go to beginning of file
138: M-> Go to end of file
139:
140: >> Try all of these commands now a few times for practice.
141: Since the last two will take you away from this screen,
142: you can come back here with M-v's and C-v's. These are
143: the most often used commands.
144:
145: Like all other commands in Emacs, these commands can be given
146: arguments which cause them to be executed repeatedly. The way you
147: give a command a repeat count is by typing C-u and then the digits
1.2 ! mickey 148: before you type the command.
1.1 deraadt 149:
150: For instance, C-u 8 C-f moves forward eight characters.
1.2 ! mickey 151:
1.1 deraadt 152: >> Try giving a suitable argument to C-n or C-p to come as close
153: as you can to this line in one jump.
154:
155: The only apparent exception to this is the screen moving commands,
156: C-v and M-v. When given an argument, they scroll the screen up or
157: down by that many lines, rather than screenfuls. This proves to be
158: much more useful.
159:
160: >> Try typing C-u 8 C-v now.
161:
162: Did it scroll the screen up by 8 lines? If you would like to
163: scroll it down you can give an argument to M-v.
164:
165:
166: WHEN EMACS IS HUNG
167: -----------------
168:
169: If Emacs gets into an infinite (or simply very long) computation which
170: you don't want to finish, you can stop it safely by typing C-g.
171: You can also use C-g to discard a numeric argument or the beginning of
172: a command that you don't want to finish.
173:
174: >> Type C-u 100 to make a numeric arg of 100, then type C-g.
175: Now type C-f. How many characters does it move?
176: If you have typed an <ESC> by mistake, you can get rid of it
177: with a C-g.
178:
179: WINDOWS
180: -------
181:
182: Emacs can have several windows, each displaying its own text.
183: At this stage it is better not to go into the techniques of
184: using multiple windows. But you do need to know how to get
185: rid of extra windows that may appear to display help or
186: output from certain commands. It is simple:
187:
188: C-x 1 One window (i.e., kill all other windows).
189:
190: That is Control-x followed by the digit 1.
191: C-x 1 makes the window which the cursor is in become
192: the full screen, by getting rid of any other windows.
193:
194: >> Move the cursor to this line and type C-l (Control-L).
195: >> Type M-x. The cursor will move to the bottom of the screen.
196: >> Type the words "describe-bindings" and hit return.
197: See how this window shrinks, while a new one appears
198: to display which functions are connected to which keys.
199:
200: >> Type C-x 1 and see the documentation listing window disappear.
201:
202:
203: INSERTING AND DELETING
204: ----------------------
205:
206: If you want to insert text, just type it. Characters which you can
207: see, such as A, 7, *, etc. are taken by Emacs as text and inserted
208: immediately. Type <Return> (the carriage-return key) to insert a
209: Newline character.
210:
211: You can delete the last character you typed by typing <DEL>. More
212: generally, <DEL> deletes the character immediately before the current
213: cursor position.
214:
215: >> Do this now, type a few characters and then delete them
216: by typing <DEL> a few times. Don't worry about this file
217: being changed; you won't affect the master tutorial. This is just
218: a copy of it.
219:
220: >> Now start typing text until you reach the right margin, and keep
221: typing. When a line of text gets too big for one line on the
222: screen, the line of text is "continued" off the edge of the screen.
223: The dollar sign at the right margin indicates a line which has
224: been continued.
225: >> Use <DEL>s to delete the text until the line fits on one screen
226: line again. The continuation mark goes away.
227:
228: >> Move the cursor to the beginning of a line and type <DEL>. This
229: deletes the newline before the line and merges the line onto
230: the previous line. The resulting line may be too long to fit, in
231: which case it has a continuation mark.
232: >> Type <Return> to reinsert the Newline you deleted.
233:
234: Remember that most Emacs commands can be given a repeat count;
235: this includes characters which insert themselves.
236:
237: >> Try that now -- type C-u 8 * and see what happens.
238:
239: You've now learned the most basic way of typing something in
240: Emacs and correcting errors. You can delete by words or lines
241: as well. Here is a summary of the delete operations:
242:
243: <DEL> delete the character just before the cursor
1.2 ! mickey 244: C-d delete the next character after the cursor
1.1 deraadt 245:
246: M-<DEL> kill the word immediately before the cursor
247: M-d kill the next word after the cursor
248:
249: C-k kill from the cursor position to end of line
250:
251: Notice that <DEL> and C-d vs M-<DEL> and M-d extend the parallel
252: started by C-f and M-f (well, <DEL> isn't really a control
253: character, but let's not worry about that).
254:
255: Now suppose you kill something, and then you decide that you want to
256: get it back? Well, whenever you kill something bigger than a
257: character, Emacs saves it for you. To yank it back, use C-y. You
258: can kill text in one place, move elsewhere, and then do C-y; this is
259: a good way to move text around. Note that the difference
260: between "Killing" and "Deleting" something is that "Killed" things
261: can be yanked back, and "Deleted" things cannot. Generally, the
262: commands that can destroy a lot of text save it, while the ones that
263: attack only one character, or nothing but blank lines and spaces, do
264: not save.
265:
266: For instance, type C-n a couple times to postion the cursor
267: at some line on this screen.
268:
269: >> Do this now, move the cursor and kill that line with C-k.
270:
271: Note that a single C-k kills the contents of the line, and a second
272: C-k kills the line itself, and make all the other lines move up. If
273: you give C-k a repeat count, it kills that many lines AND their
274: contents.
275:
276: The text that has just disappeared is saved so that you can
277: retrieve it. To retrieve the last killed text and put it where
278: the cursor currently is, type C-y.
279:
280: >> Try it; type C-y to yank the text back.
281:
282: Think of C-y as if you were yanking something back that someone
283: took away from you. Notice that if you do several C-k's in a row
284: the text that is killed is all saved together so that one C-y will
285: yank all of the lines.
286:
287: >> Do this now, type C-k several times.
288:
289: Now to retrieve that killed text:
290:
291: >> Type C-y. Then move the cursor down a few lines and type C-y
292: again. You now see how to copy some text.
293:
294:
295: FILES
296: -----
297:
298: In order to make the text you edit permanent, you must put it in a
299: file. Otherwise, it will go away when your invocation of Emacs goes
300: away. You put your editing in a file by "finding" the file. What
301: finding means is that you see the contents of the file in your Emacs;
302: and, loosely speaking, what you are editing is the file itself.
303: However, the changes still don't become permanent until you "save" the
304: file. This is so you can have control to avoid leaving a half-changed
305: file around when you don't want to.
306:
307: If you look near the bottom of the screen you will see a line that
308: begins and ends with dashes, and contains the string:
309: "Mg: TUTORIAL"
310: Your copy of the Emacs tutorial is called "TUTORIAL". Whatever
311: file you find, that file's name will appear in that precise
312: spot.
313:
314: The commands for finding and saving files are unlike the other
315: commands you have learned in that they consist of two characters.
316: They both start with the character Control-x. There is a whole series
317: of commands that start with Control-x; many of them have to do with
318: files, buffers, and related things, and all of them consist of
319: Control-x followed by some other character.
320:
321: Another thing about the command for finding a file is that you have
322: to say what file name you want. We say the command "reads an argument
323: from the terminal" (in this case, the argument is the name of the
324: file). After you type the command
325:
326: C-x C-f Find a file
327:
328: Emacs asks you to type the file name. It echoes on the bottom line of
1.2 ! mickey 329: the screen. When you type <Return> to end the file name it disappears.
1.1 deraadt 330:
1.2 ! mickey 331: >> Type C-x C-f, then type C-g. This cancels the C-x C-f command
1.1 deraadt 332: that was using the minibuffer. So you do not find any file.
333:
334: In a little while the file contents appear on the screen. You can
335: edit the contents. When you wish to make the changes permanent,
336: issue the command
337:
338: C-x C-s Save the file
339:
1.2 ! mickey 340: The contents of Emacs are written into the file.
1.1 deraadt 341:
342: When saving is finished, Emacs prints the name of the file written.
343: You should save fairly often, so that you will not lose very much
344: work if the system should crash.
345:
346: >> Type C-x C-s, saving your copy of the tutorial.
347: This should print "Wrote TUTORIAL" at the bottom of the screen.
348:
349: To make a new file, just find it "as if" it already existed. Then
350: start typing in the text. When you ask to "save" the file, Emacs
351: will really create the file with the text that you have inserted.
352: >From then on, you can consider yourself to be editing an already
353: existing file.
354:
355:
356: BUFFERS
357: -------
358:
359: If you find a second file with C-x C-f, the first file remains inside
1.2 ! mickey 360: Emacs. This way you can get quite a number of files inside Emacs.
1.1 deraadt 361:
362: The object inside Emacs which holds the text read from one file
363: is called a "buffer." Finding a file makes a new buffer inside Emacs.
364: To see a list of the buffers that exist in Emacs, type
365:
366: C-x C-b List buffers
367:
368: >> Try C-x C-b now.
369:
370: See how each buffer has a name, and it may also have a file name
371: for the file whose contents it holds. Some buffers do not correspond
372: to files. For example, the buffer named "*Buffer List*" does
373: not have any file. It is the buffer which contains the buffer
374: list that was made by C-x C-b. ANY text you see in an Emacs window
375: has to be in some buffer.
376:
377: >> Type C-x 1 to get rid of the buffer list.
378:
379: If you make changes to the text of one file, then find another file,
380: this does not save the first file. Its changes remain inside Emacs,
381: in that file's buffer. The creation or editing of the second file's
382: buffer has no effect on the first file's buffer. This is very useful,
383: but it also means that you need a convenient way to save the first
384: file's buffer. It would be a nuisance to have to switch back to
385: it with C-x C-f in order to save it with C-x C-s. So we have
386:
387: C-x s Save some buffers
388:
389: C-x s goes through the list of all the buffers you have
390: and finds the ones that contain files you have changed.
391: For each such buffer, C-x s asks you whether to save it.
392:
393:
394: EXTENDING THE COMMAND SET
395: -------------------------
396:
397: There are many, many more Emacs commands than could possibly be put
398: on all the control and meta characters. Emacs gets around this with
399: the X (eXtend) command. This comes in two flavors:
400:
401: C-x Character eXtend. Followed by one character.
402: M-x Named command eXtend. Followed by a long name.
403:
404: These are commands that are generally useful but used less than the
405: commands you have already learned about. You have already seen two
406: of them: the file commands C-x C-f to Find and C-x C-s to Save.
407: Another example is the command to tell Emacs that you'd like to stop
408: editing and get rid of Emacs. The command to do this is C-x C-c.
409: (Don't worry; it offers to save each changed file before it kills the
410: Emacs.)
411:
412: C-z is the usual way to exit Emacs, because it is always better not to
413: kill the Emacs if you are going to do any more editing. On systems
414: which allow it, C-z exits from Emacs to a CLI but does not destroy the
415: Emacs; you can resume editing by ending that CLI or depth arranging.
416:
417: You would use C-x C-c if you were running out of memory. You would
418: also use it to exit an Emacs invoked under mail handling programs and
419: other random utilities, since they may not believe you have really
1.2 ! mickey 420: finished using the Emacs if it continues to exist.
1.1 deraadt 421:
422: There are many C-x commands. The ones you know are:
423:
424: C-x C-f Find file.
425: C-x C-s Save file.
426: C-x C-b List buffers.
427: C-x C-c Quit Emacs.
428:
429: Named eXtended commands are commands which are used even less
430: frequently, or commands which are used only in certain modes. These
431: commands are usually called "functions". An example is the function
432: replace-string, which globally replaces one string with another. When
433: you type M-x, Emacs prompts you at the bottom of the screen with
434: M-x and you should type the name of the function you wish to call; in
435: this case, "query-replace". Just type "que<TAB>" and Emacs will
436: complete the name. End the command name with <Return>.
437: Then type the two "arguments"--the string to be replaced, and the string
438: to replace it with--each one ended with a Return.
439:
440: >> Move the cursor to the blank line two lines below this one.
441: Then type M-x repl s<Return>changed<Return>altered<Return>.
442:
443: Notice how this line has changed: you've replaced
444: the word c-h-a-n-g-e-d with "altered" wherever it occured
445: after the cursor.
446:
447:
448: MODE LINE
449: ---------
450:
451: If Emacs sees that you are typing commands slowly it shows them to you
452: at the bottom of the screen in an area called the "echo area." The echo
453: area contains the bottom line of the screen. The line immediately above
454: it is called the MODE LINE. The mode line says something like
455:
1.2 ! mickey 456: --**-Mg: TUTORIAL (fundamental)------------------------
1.1 deraadt 457:
458: This is a very useful "information" line.
459:
460: The stars near the front mean that you have made changes to the text.
461: Right after you visit or save a file, there are no stars, just dashes.
462:
463: The part of the mode line inside the parentheses is to tell you what
464: modes you are in. The default mode is fundamental which is what you
465: are in now. It is an example of a "mode". There are several modes in
466: Emacs for editing different styles of text, such as indent, bsmap,
467: fill, etc. Each mode makes a few commands behave differently.
468:
469: One mode which is very useful, especially for editing English text, is
470: Auto Fill mode. When this mode is on, Emacs breaks the line in
471: between words automatically whenever the line gets too long. You can
472: turn this mode on by doing M-x auto-fill-mode<Return>. When the mode
473: is on, you can turn it off by doing M-x auto-fill-mode<Return>.
474:
475: >> Type M-x auto-fill-mode<Return> now. Then insert a line of "asdf "
476: over again until you see it divide into two lines. You must put in
477: spaces between them because Auto Fill breaks lines only at spaces.
478:
479: The margin is usually set at 70 characters, but you can change it
480: with the C-x f command. You should give the margin setting you want
481: as a numeric argument.
482:
483: >> Type C-x f with an argument of 20. (C-u 2 0 C-x f).
484: Then type in some text and see Emacs fill lines of 20
485: characters with it. Then set the margin back to 70 using
486: C-x f again.
487:
488: If you make changes in the middle of a paragraph, Auto Fill mode
489: does not re-fill it for you.
490: To re-fill the paragraph, type M-q (Meta-q) with the cursor inside
491: that paragraph.
492:
493: >> Move the cursor into the previous paragraph and type M-q.
494:
495: SEARCHING
496: ---------
497:
498: Emacs can do searches for strings (these are groups of contiguous
499: characters or words) either forward through the file or backward
500: through it. To search for the string means that you are trying to
501: locate it somewhere in the file and have Emacs show you where the
502: occurrences of the string exist. This type of search is somewhat
503: different from what you may be familiar with. It is a search that is
504: performed as you type in the thing to search for. The command to
505: initiate a search is C-s for forward search, and C-r for reverse
506: search. BUT WAIT! Don't do them now. When you type C-s you'll
507: notice that the string "I-search" appears as a prompt in the echo
508: area. This tells you that Emacs is in what is called an incremental
509: search waiting for you to type the thing that you want to search for.
510: <ESC> terminates a search.
511:
512: >> Now type C-s to start a search. SLOWLY, one letter at a time,
513: type the word 'cursor', pausing after you type each
514: character to notice what happens to the cursor.
515: >> Type C-s to find the next occurrence of "cursor".
516: >> Now type <DEL> four times and see how the cursor moves.
517: >> Type <ESC> to terminate the search.
518:
519: Did you see what happened? Emacs, in an incremental search, tries to
520: go to the occurrence of the string that you've typed out so far. To go
521: to the next occurrence of 'cursor' just type C-s again. If no such
522: occurrence exists Emacs beeps and tells you that it is a failing
523: search. C-g would also terminate the search.
524:
525: If you are in the middle of an incremental search and type <DEL>,
526: you'll notice that the last character in the search string is erased
527: and the search backs up to the last place of the search. For
528: instance, suppose you currently have typed 'cu' and you see that your
529: cursor is at the first occurrence of 'cu'. If you now type <DEL>,
530: the 'u' on the search line is erased and you'll be repositioned in the
531: text to the occurrence of 'c' where the search took you before you
532: typed the 'u'. This provides a useful means for backing up while you
1.2 ! mickey 533: are searching.
1.1 deraadt 534:
535: If you are in the middle of a search and happen to type a control
536: character (other than a C-s or C-r, which tell Emacs to search for the
537: next occurrence of the string), the search is terminated.
538:
539: The C-s starts a search that looks for any occurrence of the search
540: string AFTER the current cursor position. But what if you want to
541: search for something earlier in the text? To do this, type C-r for
542: Reverse search. Everything that applies to C-s applies to C-r except
543: that the direction of the search is reversed.
544:
545:
546: GETTING MORE HELP
547: -----------------
548:
549: In this tutorial we have tried to supply just enough information to
550: get you started using Emacs. There is so much available in Emacs that
551: it would be impossible to explain it all here. However, you may want
552: to learn more about Emacs since it has numerous desirable features
1.2 ! mickey 553: that you don't know about yet.
1.1 deraadt 554:
555:
556: CONCLUSION
557: ----------
558:
559: Remember, to exit Emacs permanently use C-x C-c. To exit to a shell
560: temporarily, so that you can come back in, use C-z.
561:
562: This tutorial is meant to be understandable to all new users, so if
563: you found something unclear, don't sit and blame yourself - complain!
564:
565:
566: COPYING
567: -------
568:
569: This tutorial, like all of GNU Emacs, is copyrighted, and comes with
570: permission to distribute copies on certain conditions:
571:
572: Copyright (c) 1985 Richard M. Stallman
573:
574: Permission is granted to anyone to make or distribute verbatim copies
575: of this document as received, in any medium, provided that the
576: copyright notice and permission notice are preserved,
577: and that the distributor grants the recipient permission
578: for further redistribution as permitted by this notice.
579:
580: Permission is granted to distribute modified versions
581: of this document, or of portions of it,
582: under the above conditions, provided also that they
583: carry prominent notices stating who last altered them.
584:
585: The conditions for copying Emacs itself are slightly different
586: but in the same spirit. Please read the file COPYING and then
587: do give copies of GNU Emacs to your friends.
588: Help stamp out ownership of software by using, writing,
589: and sharing free software!
590:
591: Mg itself is public domain, and may be given away freely. See the
592: README file about differences from GNU emacs, and why Mg exists.
593:
594: *******************************************************************************
595: *** This document heavily cut by Randy M. Spencer to apply to ***
596: *** Mg written my Mike Meyer and gang. It was released ***
597: *** at the AAA users group meeting in Lafayette CA, an Amiga Users ***
598: *** Group. My profound thanks to Richard Stallman for his work, I ***
599: *** am proud to carry his initials. ***
600: *** Additional modifacations were done by Robert A. Larson for Mg ***
601: *** version 2a, mainly the name change from MicroGnuEmacs to Mg. ***
602: *******************************************************************************
603:
604: See other files accompanying this for more system specific information.