![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to emacs.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / emacs / man|
Return to emacs.tex CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / emacs / man |
1.1 root 1: \input texinfo @c -*-texinfo-*-
2: @setfilename ../info/emacs
3: @ifinfo
4: This file documents the GNU Emacs editor.
5:
6: Copyright (C) 1985 Richard M. Stallman.
7:
8: Permission is granted to make and distribute verbatim copies of
9: this manual provided the copyright notice and this permission notice
10: are preserved on all copies.
11:
12: @ignore
13: Permission is granted to process this file through Tex and print the
14: results, provided the printed document carries copying permission
15: notice identical to this one except for the removal of this paragraph
16: (this paragraph not being relevant to the printed manual).
17:
18: @end ignore
19: Permission is granted to copy and distribute modified versions of this
20: manual under the conditions for verbatim copying, provided also that the
21: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU Emacs
22: General Public License'' are included exactly as in the original, and
23: provided that the entire resulting derived work is distributed under the
24: terms of a permission notice identical to this one.
25:
26: Permission is granted to copy and distribute translations of this manual
27: into another language, under the above conditions for modified versions,
28: except that the sections entitled ``The GNU Manifesto'', ``Distribution''
29: and ``GNU Emacs General Public License'' may be included in a translation
30: approved by the author instead of in the original English.
31: @end ifinfo
32: @c
33: @setchapternewpage odd
34: @settitle GNU Emacs Manual
35: @c
36: @titlepage
37: @sp 6
38: @center @titlefont{GNU Emacs Manual}
39: @sp 4
40: @center Fourth Edition, Emacs Version 17
41: @sp 1
42: @center February 1986
43: @sp 5
44: @center Richard Stallman
45: @page
46: @vskip 0pt plus 1filll
47: Copyright @copyright{} 1985 Richard M. Stallman.
48:
49: Permission is granted to make and distribute verbatim copies of
50: this manual provided the copyright notice and this permission notice
51: are preserved on all copies.
52:
53: Permission is granted to copy and distribute modified versions of this
54: manual under the conditions for verbatim copying, provided also that the
55: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU Emacs
56: General Public License'' are included exactly as in the original, and
57: provided that the entire resulting derived work is distributed under the
58: terms of a permission notice identical to this one.
59:
60: Permission is granted to copy and distribute translations of this manual
61: into another language, under the above conditions for modified versions,
62: except that the sections entitled ``The GNU Manifesto'', ``Distribution''
63: and ``GNU Emacs General Public License'' may be included in a translation
64: approved by the author instead of in the original English.
65: @end titlepage
66: @page
67: @ifinfo
68: @node Top, Distrib,, (DIR)
69:
70: The Emacs Editor
71: ****************
72:
73: Emacs is the extensible, customizable, self-documenting real-time
74: display editor. This Info file describes how to edit with Emacs
75: and some of how to customize it, but not how to extend it.
76:
77: @end ifinfo
78: @menu
79: * Distrib:: How to get the latest Emacs distribution.
80: * License:: The GNU Emacs General Public License gives you permission
81: to redistribute GNU Emacs on certain terms; and also
82: explains that there is no warranty.
83: * Intro:: An introduction to Emacs concepts.
84: * Glossary:: The glossary.
85: * Manifesto:: What's GNU? Gnu's Not Unix!
86:
87: Indexes, nodes containing large menus
88: * Key Index:: An item for each standard Emacs key sequence.
89: * Command Index:: An item for each command name.
90: * Variable Index:: An item for each documented variable.
91: * Concept Index:: An item for each concept.
92:
93: Important General Concepts
94: * Screen:: How to interpret what you see on the screen.
95: * Characters:: Emacs's character sets for file contents and for keyboard.
96: * Keys:: Key sequences: what you type to request one editing action.
97: * Commands:: Commands: named functions run by key sequences to do editing.
98: * Entering Emacs:: Starting Emacs from the shell.
99: * Exiting:: Stopping or killing Emacs.
100: * Basic:: The most basic editing commands.
101: * Undo:: Undoing recently made changes in the text.
102: * Minibuffer:: Entering arguments that are prompted for.
103: * M-x:: Invoking commands by their names.
104: * Help:: Commands for asking Emacs about its commands.
105:
106: Important Text-Changing Commands
107: * Mark:: The mark: how to delimit a ``region'' of text.
108: * Killing:: Killing text.
109: * Yanking:: Recovering killed text. Moving text.
110: * Accumulating Text::
111: Other ways of copying text.
112: * Rectangles:: Operating on the text inside a rectangle on the screen.
113: * Registers:: Saving a text string or a location in the buffer.
114: * Display:: Controlling what text is displayed.
115: * Search:: Finding or replacing occurrences of a string.
116: * Fixit:: Commands especially useful for fixing typos.
117:
118: Larger Units of Text
119: * Files:: All about handling files.
120: * Buffers:: Multiple buffers; editing several files at once.
121: * Windows:: Viewing two pieces of text at once.
122:
123: Advanced Features
124: * Major Modes:: Text mode vs. Lisp mode vs. C mode ...
125: * Indentation:: Editing the white space at the beginnings of lines.
126: * Text:: Commands and modes for editing English.
127: * Programs:: Commands and modes for editing programs.
128: * Running:: Compiling, running and debugging programs.
129: * Abbrevs:: How to define text abbreviations to reduce
130: the number of characters you must type.
131: * Picture:: Editing pictures made up of characters
132: using the quarter-plane screen model.
133: * Sending Mail::Sending mail in Emacs.
134: * Rmail:: Reading mail in Emacs.
135: * Recursive Edit::
136: A command can allow you to do editing
137: "within the command". This is called a
138: `recursive editing level'.
139: * Narrowing:: Restricting display and editing to a portion
140: of the buffer.
141: * Shell:: Executing shell commands from Emacs.
142: * Dissociated Press:: Dissociating text for fun.
143: * Amusements:: Various games and hacks.
144: * Customization:: Modifying the behavior of Emacs.
145:
146: Recovery from Problems.
147: * Quitting:: Quitting and aborting.
148: * Lossage:: What to do if Emacs is hung or malfunctioning.
149: * Bugs:: How and when to report a bug.
150:
151: Here are some other nodes which are really inferiors of the ones
152: already listed, mentioned here so you can get to them in one step:
153:
154: Subnodes of Screen
155: * Point:: The place in the text where editing commands operate.
156: * Echo Area:: Short messages appear at the bottom of the screen.
157: * Mode Line:: Interpreting the mode line.
158:
159: Subnodes of Basic
160: * Blank Lines:: Commands to make or delete blank lines.
161: * Continuation Lines:: Lines too wide for the screen.
162: * Position Info:: What page, line, row, or column is point on?
163: * Arguments:: Giving numeric arguments to commands.
164:
165: Subnodes of Minibuffer
166: * Minibuffer File:: Entering file names with the minibuffer.
167: * Minibuffer Edit:: How to edit in the minibuffer.
168: * Completion:: An abbreviation facility for minibuffer input.
169: * Repetition:: Re-executing previous commands that used the minibuffer.
170:
171: Subnodes of Mark
172: * Mark Ring:: Previous mark positions saved so you can go back there.
173:
174: Subnodes of Registers
175: * RegPos:: Saving positions in registers.
176: * RegText:: Saving text in registers.
177: * RegRect:: Saving rectangles in registers.
178:
179: Subnodes of Display
180: * Selective Display:: Hiding lines with lots of indentation.
181: * Display Vars:: Information on variables for customizing display.
182:
183: Subnodes of Search
184: * Incremental Search:: Search happens as you type the string.
185: * Nonincremental Search:: Specify entire string and then search.
186: * Word Search:: Search for sequence of words.
187: * Regexp Search:: Search for match for a regexp.
188: * Regexps:: Syntax of regular expressions.
189: * Search Case:: To ignore case while searching, or not.
190: * Replace:: Search, and replace some or all matches.
191: * Unconditional Replace:: Everything about replacement except for querying.
192: * Query Replace:: How to use querying.
193: * Other Repeating Search:: Operating on all matches for some regexp.
194:
195: Subnodes of Fixit
196: * Kill Errors:: Commands to kill a batch of recently entered text.
197: * Transpose:: Exchanging two characters, words, lines, lists...
198: * Fixing Case:: Correcting case of last word entered.
199: * Spelling:: Apply spelling checker to a word, or a whole file.
200:
201: Subnodes of Files
202: * File Names:: How to type and edit file name arguments.
203: * Visiting:: Visiting a file prepares Emacs to edit the file.
204: * Saving:: Saving makes your changes permanent.
205: * Backup:: How Emacs saves the old version of your file.
206: * Interlocking::How Emacs protects against simultaneous editing
207: of one file by two users.
208: * Reverting:: Reverting cancels all the changes not saved.
209: * Auto Save:: Auto Save periodically protects against loss of data.
210: * ListDir:: Listing the contents of a file directory.
211: * Dired:: ``Editing'' a directory to delete, rename, etc.
212: the files in it.
213: * Misc File Ops:: Other things you can do on files.
214:
215: Subnodes of Buffers
216: * Select Buffer:: Creating a new buffer or reselecting an old one.
217: * List Buffers:: Getting a list of buffers that exist.
218: * Misc Buffer:: Renaming; changing read-only status.
219: * Kill Buffer:: Killing buffers you no longer need.
220: * Several Buffers:: How to go through the list of all buffers
221: and operate variously on several of them.
222:
223: Subnodes of Indentation
224: * Indentation Commands:: Various commands and techniques for indentation.
225: * Tab Stops:: You can set arbitrary "tab stops" and then
226: indent to the next tab stop when you want to.
227: * Just Spaces:: You can request indentation using just spaces.
228:
229: Subnodes of Text
230: * Text Mode:: The major mode for editing text files.
231: * Nroff Mode:: The major mode for editing input to the formatter nroff.
232: * TeX Mode:: The major mode for editing input to the formatter TeX.
233: * Outline Mode::The major mode for editing outlines.
234: * Words:: Moving over and killing words.
235: * Sentences:: Moving over and killing sentences.
236: * Paragraphs:: Moving over paragraphs.
237: * Pages:: Moving over pages.
238: * Filling:: Filling or justifying text
239: * Case:: Changing the case of text
240:
241: Subnodes of Programs
242: * Program Modes:: Major modes for editing programs.
243: * Lists:: Expressions with balanced parentheses.
244: There are editing commands to operate on them.
245: * Defuns:: Each program is made up of separate functions.
246: There are editing commands to operate on them.
247: * Grinding:: Adjusting indentation to show the nesting.
248: * Matching:: Insertion of a close-delimiter flashes matching open.
249: * Comments:: Inserting, illing and aligning comments.
250: * Balanced Editing:: Inserting two matching parentheses at once, etc.
251: * Documentation:: Getting documentation of functions you plan to call.
252: * Change Log:: Maintaining a change history for your program.
253: * Tags:: Go direct to any function in your program in one
254: command. Tags remembers which file it is in.
255:
256: Subnodes of Running
257: * Compilation:: Compiling programs in languages other than Lisp
258: (C, Pascal, etc.)
259: * Lisp Modes:: Various modes for editing Lisp programs, with
260: different facilities for running the Lisp programs.
261: * Lisp Libraries:: Creating Lisp programs to run in Emacs.
262: * Lisp Interaction:: Executing Lisp in an Emacs buffer.
263: * Lisp Eval:: Executing a single Lisp expression in Emacs.
264: * Lisp Debug:: Debugging Lisp programs running in Emacs.
265: * External Lisp:: Communicating through Emacs with a separate Lisp.
266:
267: Subnodes of Abbrevs
268: * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
269: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
270: * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
271: * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
272:
273: Subnodes of Picture
274: * Basic Picture:: Basic concepts and simple commands of Picture Mode.
275: * Insert in Picture:: Controlling direction of cursor motion
276: after "self-inserting" characters.
277: * Tabs in Picture:: Various features for tab stops and indentation.
278: * Rectangles in Picture:: Clearing and superimposing rectangles.
279:
280: Subnodes of Rmail::
281: * Rmail Scrolling:: Scrolling through a message.
282: * Rmail Motion:: Moving to another message.
283: * Rmail Deletion:: Deleting and expunging messages.
284: * Rmail Inbox:: How mail gets into the Rmail file.
285: * Rmail Files:: Using multiple Rmail files.
286: * Rmail Labels:: Classifying messages by labeling them.
287: * Rmail Summary:: Summaries show brief info on many messages.
288: * Rmail Reply:: Sending replies to messages you are viewing.
289: * Rmail Editing:: Editing message text and headers in Rmail.
290: * Rmail Digest:: Extracting the messages from a digest message.
291:
292: Subnodes of Customization
293: * Minor Modes:: Each minor mode is one feature you can turn on
294: independently of any others.
295: * Variables:: Many Emacs commands examine Emacs variables
296: to decide what to do; by setting variables,
297: you can control their functioning.
298: * Examining:: Examining or setting one variable's value.
299: * Edit Options:: Examining or editing list of all variables' values.
300: * Locals:: Per-buffer values of variables.
301: * File Variables:: How files can specify variable values.
302: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
303: to be replayed with a single command.
304: * Key Bindings:: The keymaps say what command each key runs.
305: By changing them, you can "redefine keys".
306: * Keymaps:: Definition of the keymap data structure.
307: * Rebinding:: How to redefine one key's meaning conveniently.
308: * Disabling:: Disabling a command means confirmation is required
309: before it can be executed. This is done to protect
310: beginners from surprises.
311: * Syntax:: The syntax table controls how words and expressions
312: are parsed.
313: * Init File:: How to write common customizations in the `.emacs' file.
314:
315: Subnodes of Lossage (and recovery)
316: * Stuck Recursive:: `[...]' in mode line around the parentheses.
317: * Screen Garbled:: Garbage on the screen.
318: * Text Garbled:: Garbage in the text.
319: * Unasked-for Search::Spontaneous entry to incremental search.
320: * Emergency Escape:: Emergency escape---
321: What to do if Emacs stops responding.
322: * Total Frustration:: When you are at your wits' end.
323: @end menu
324:
325: @iftex
326: @unnumbered Preface
327:
328: This manual documents the use and simple customization of the
329: Emacs editor. The reader is not expected to be a programmer. Even simple
330: customizations do not require programming skill, but the user who is not
331: interested in customizing can ignore the scattered customization hints.
332:
333: This is primarily a reference manual, but can also be used as a
334: primer. However, I recommend that the newcomer first use the on-line,
335: learn-by-doing tutorial, which you get by running Emacs and typing
336: @kbd{C-h t}. With it, you learn Emacs by using Emacs on a specially
337: designed file which describes commands, tells you when to try them,
338: and then explains the results you see. This gives a more vivid
339: introduction than a printed manual.
340:
341: On first reading, you need not make any attempt to memorize chapters one
342: and two, which describe the notational conventions of the manual and the
343: general appearance of the Emacs display screen. It is enough to be aware
344: of what questions are answered in these chapters, so you can refer back
345: when you later become interested in the answers. After reading chapter
346: four you should practice the commands there. The next few chapters
347: describe fundamental techniques and concepts that are referred to again and
348: again. It is best to understand them thoroughly, experimenting with them
349: if necessary.
350:
351: To find the documentation on a particular command, look in the
352: index. Keys (character commands) and command names have separate
353: indexes just for them. There is also a glossary, with a cross
354: reference for each term.
355:
356: @ignore
357: If you know vaguely what the command
358: does, look in the command summary. The command summary contains a line or
359: two about each command, and a cross reference to the section of the
360: manual that describes the command in more detail; related commands
361: are grouped together.
362: @end ignore
363:
364: This manual comes in two forms: the published form and the Info form.
365: The Info form is for on-line perusal with the INFO program; it is
366: distributed along with GNU Emacs. Both forms contain substantially the
367: same text and are generated from a common source file, which is distributed
368: along with GNU Emacs.
369:
370: GNU Emacs is a member of the Emacs editor family. There are many Emacs
371: editors, all sharing common principles of organization. For information on
372: the underlying philosophy of Emacs and the lessons learned from its
373: development, write for a copy of AI memo 519a, ``Emacs, the Extensible,
374: Customizable Self-Documenting Display Editor'', to
375:
376: @display
377: Publications Department
378: Artificial Intelligence Lab
379: 545 Tech Square
380: Cambridge, MA 02139
381: @end display
382:
383: At last report they charge $2.25 per copy.
384: @end iftex
385:
386: @node Distrib, License, Top, Top
387: @unnumbered Distribution
388:
389: GNU Emacs is @dfn{free}; this means that everyone is free to use it and
390: free to redistribute it on a free basis. GNU Emacs is not in the public
391: domain; it is copyrighted and there are restrictions on its distribution,
392: but these restrictions are designed to permit everything that a good
393: cooperating citizen would want to do. What is not allowed is to try to
394: prevent others from further sharing any version of GNU Emacs that they
395: might get from you. The precise conditions are found in the GNU Emacs
396: General Public License that comes with Emacs and also appears following
397: this section.
398:
399: The easiest way to get a copy of GNU Emacs is from someone else who has it.
400: You need not ask for permission to do so, or tell any one else; just copy
401: it.
402:
403: If you have access to the Internet, you can get the latest distribution
404: version of GNU Emacs from host @file{prep.ai.mit.edu} using anonymous
405: login. See the file @file{/u2/emacs/GETTING.GNU.SOFTWARE} on that host
406: to find out about your options for copying and which files to use.
407:
408: You may also eventually receive GNU Emacs when you buy a computer.
409: Computer manufacturers are free to distribute copies on the same terms that
410: apply to everyone else. These terms require them to give you the full
411: sources, including whatever changes they may have made, and to permit you
412: to redistribute the GNU Emacs received from them under the usual terms of
413: the General Public License. In other words, the program must be free for
414: you when you get it, not just free for the manufacturer.
415:
416: If you cannot get a copy in any of those ways, you can order one from the
417: Free Software Foundation. Though Emacs itself is free, our distribution
418: service is not. An order form is included at the end of the manual, in
419: manuals printed by the Foundation. It is also included in the file
420: @file{etc/DISTRIB} in the Emacs distribution. For further information,
421: write to
422:
423: @display
424: Free Software Foundation
425: 1000 Mass Ave
426: Cambridge, MA 02138
427: @end display
428:
429: The income from distribution fees goes to support the foundation's
430: purpose: the development of more free software to distribute just like
431: GNU Emacs.
432:
433: If you find GNU Emacs useful, we urge you to @b{send a donation} to the Free
434: Software Foundation. This will help support development of the rest of the
435: GNU system, and other useful software beyond that. Subject to approval of
436: our application for a tax exemption, your donation will be tax deductible.
437:
438: @node License, Intro, Distrib, Top
439: @unnumbered GNU Emacs General Public License
440:
441: The license agreements of most software companies keep you at the
442: mercy of those companies. By contrast, our general public license is
443: intended to give everyone the right to share GNU Emacs. To make
444: sure that you get the rights we want you to have, we need to make
445: restrictions that forbid anyone to deny you these rights or to ask you
446: to surrender the rights. Hence this license agreement.
447:
448: Specifically, we want to make sure that you have the right to give
449: away copies of Emacs, that you receive source code or else can get it
450: if you want it, that you can change Emacs or use pieces of it in new
451: free programs, and that you know you can do these things.
452:
453: To make sure that everyone has such rights, we have to forbid you to
454: deprive anyone else of these rights. For example, if you distribute
455: copies of Emacs, you must give the recipients all the rights that you
456: have. You must make sure that they, too, receive or can get the
457: source code. And you must tell them their rights.
458:
459: Also, for our own protection, we must make certain that everyone
460: finds out that there is no warranty for GNU Emacs. If Emacs is
461: modified by someone else and passed on, we want its recipients to know
462: that what they have is not what we distributed, so that any problems
463: introduced by others will not reflect on our reputation.
464:
465: Therefore we (Richard Stallman and the Free Software Foundation, Inc.)@:
466: make the following terms which say what you must do to be allowed to
467: distribute or change GNU Emacs.
468:
469: @unnumberedsec Copying Policies
470:
471: @enumerate
472: @item
473: You may copy and distribute verbatim copies of GNU Emacs source
474: code as you receive it, in any medium, provided that you conspicuously
475: and appropriately publish on each file a valid copyright notice such
476: as ``Copyright @copyright{} 1985 Richard M. Stallman'', containing the year of
477: last change and name of copyright holder for the file in question;
478: keep intact the notices on all files that refer to this License
479: Agreement and to the absence of any warranty; and give any other
480: recipients of the GNU Emacs program a copy of this License Agreement
481: along with the program.
482:
483: @item
484: You may modify your copy or copies of GNU Emacs source code or
485: any portion of it, and copy and distribute such modifications under
486: the terms of Paragraph 1 above, provided that you also do the following:
487:
488: @enumerate
489: @item
490: cause the modified files to carry prominent notices stating
491: who last changed such files and the date of any change; and
492:
493: @item
494: cause the whole of any work that you distribute or publish,
495: that in whole or in part contains or is a derivative of GNU Emacs
496: or any part thereof, to be freely distributed
497: and licensed to all third parties on terms identical to those
498: contained in this License Agreement (except that you may choose
499: to grant more extensive warranty protection to third parties,
500: at your option).
501:
502: @item
503: if the modified program serves as a text editor, cause it
504: when started running in the simplest and usual way, to print
505: an announcement including a valid copyright notice (``Copyright
506: @copyright{}'', the year of authorship, and all copyright owners' names),
507: saying that there is no warranty (or else, saying that you provide
508: a warranty) and that users may redistribute the program under
509: these conditions, and telling the user how to view a copy of
510: this License Agreement.
511: @end enumerate
512:
513: @item
514: You may copy and distribute GNU Emacs or any portion of it in
515: compiled, executable or object code form under the terms of Paragraphs
516: 1 and 2 above provided that you do the following:
517:
518: @enumerate
519: @item
520: cause each such copy of GNU Emacs to be accompanied by the
521: corresponding machine-readable source code; or
522:
523: @item
524: cause each such copy of GNU Emacs to be accompanied by a written
525: offer, with no time limit, to give any third party free (except
526: for a nominal shipping charge) machine readable copy of the
527: corresponding source code; or
528:
529: @item
530: in the case of a recipient of GNU Emacs in compiled, executable
531: or object code form (without the corresponding source code) you
532: shall cause copies you distribute to be accompanied by a copy of
533: the written offer of source code which you received along with
534: the copy of GNU Emacs.
535: @end enumerate
536:
537: @item
538: You may not copy, sublicense, distribute or transfer GNU Emacs except
539: as expressly provided under this License Agreement. Any attempt
540: otherwise to copy, sublicense, distribute or transfer GNU Emacs is
541: void and your rights to use GNU Emacs under this License agreement
542: shall be automatically terminated. However, parties who have received
543: computer software programs from you with this License Agreement will
544: not have their licenses terminated so long as such parties remain in
545: full compliance.
546: @end enumerate
547:
548: Your comments and suggestions about our licensing policies and our
549: software are welcome! Please contact the Free Software Foundation, Inc.,
550: 1000 Mass Ave, Cambridge, MA 02138, or call (617) 876-3296.
551:
552: @iftex
553: @vfil
554: @eject
555: @end iftex
556: @unnumberedsec NO WARRANTY
557:
558: BECAUSE GNU EMACS IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
559: NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT
560: WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC,
561: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU EMACS ``AS IS''
562: WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
563: BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
564: FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY
565: AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE GNU EMACS
566: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
567: SERVICING, REPAIR OR CORRECTION.
568:
569: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
570: FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
571: MODIFY AND REDISTRIBUTE GNU EMACS AS PERMITTED ABOVE, BE LIABLE TO YOU
572: FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
573: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
574: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
575: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
576: FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
577: FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
578: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
579: OTHER PARTY.
580:
581: @node Intro, Glossary, License, Top
582: @unnumbered Introduction
583:
584: You are about to read about GNU Emacs, the Unix/GNU incarnation of the
585: advanced, self-documenting, customizable, extensible real-time display
586: editor Emacs. (The `G' in `GNU' is not silent.)
587:
588: We say that Emacs is a @dfn{display} editor because normally the text
589: being edited is visible on the screen and is updated automatically as you
590: type your commands. @xref{Screen,Display}.
591:
592: We call it a @dfn{real-time} editor because the display is updated very
593: frequently, usually after each character or pair of characters you
594: type. This minimizes the amount of information you must keep in your
595: head as you edit. @xref{Basic,Real-time,Basic Editing}.
596:
597: We call Emacs advanced because it provides facilities that go beyond
598: simple insertion and deletion: filling of text; automatic indentation of
599: programs; viewing two or more files at once; and dealing in terms of
600: characters, words, lines, sentences, paragraphs, and pages, as well as
601: expressions and comments in several different programming languages. It is
602: much easier to type one command meaning ``go to the end of the paragraph''
603: than to find that spot with simple cursor keys.
604:
605: @dfn{Self-documenting} means that at any time you can type a special
606: character, @kbd{Control-h}, to find out what your options are. You can
607: also use it to find out what any command does, or to find all the commands
608: that pertain to a topic. @xref{Help}.
609:
610: @dfn{Customizable} means that you can change the definitions of Emacs
611: commands in little ways. For example, if you use a programming language in
612: which comments start with @samp{<**} and end with @samp{**>}, you can tell
613: the Emacs comment manipulation commands to use those strings
614: (@pxref{Comments}). Another sort of customization is rearrangement of the
615: command set. For example, if you prefer the four basic cursor motion
616: commands (up, down, left and right) on keys in a diamond pattern on the
617: keyboard, you can have it. @xref{Customization}.
618:
619: @dfn{Extensible} means that you can go beyond simple customization and
620: write entirely new commands, programs in the Lisp language to be run by
621: Emacs's own Lisp interpreter. Emacs is an ``on-line extensible'' system,
622: which means that it is divided into many functions that call each other,
623: any of which can be redefined in the middle of an editing session. Any
624: part of Emacs can be replaced without making a separate copy of all of
625: Emacs. Most of the editing commands of Emacs are written in Lisp already;
626: the few exceptions could have been written in Lisp but are written in C for
627: efficiency. Although only a programmer can write an extension, anybody can
628: use it afterward.
629:
630: @node Screen, Characters, Concept Index, Top
631:
632: @chapter The Organization of the Screen
633: @cindex screen
634:
635: Emacs divides the screen into several areas, each of which contains
636: its own sorts of information. The biggest area, of course, is the one
637: in which you usually see the text you are editing.
638:
639: When you are using Emacs, the screen is divided into a number of
640: @dfn{windows}. Initially there is one text window occupying all but the
641: last line, plus the special @dfn{echo area} or @dfn{minibuffer window} in
642: the last line. The text window can be subdivided horizontally or
643: vertically into multiple text windows, each of which can be used for a
644: different file (@pxref{Windows}). The window that the cursor is in is the
645: @dfn{selected window}, in which editing takes place. The other windows are
646: just for reference unless you select one of them.
647:
648: Each text window's last line is a @dfn{mode line} which describes what is
649: going on in that window. It is in inverse video if the terminal supports
650: that, and contains text that starts like @samp{-----Emacs:@: @var{something}}. Its
651: purpose is to indicate what buffer is being displayed in the window above
652: it; what major and minor modes are in use; and whether the buffer's text
653: has been changed.
654:
655: @menu
656: * Point:: The place in the text where editing commands operate.
657: * Echo Area:: Short messages appear at the bottom of the screen.
658: * Mode Line:: Interpreting the mode line.
659: @end menu
660:
661: @node Point, Echo Area, Screen, Screen
662: @section Point
663: @cindex point
664: @cindex cursor
665:
666: When Emacs is running, the terminal's cursor shows the location at
667: which editing commands will take effect. This location is called
668: @dfn{point}. Other commands move point through the text, so that you
669: can edit at different places in it.
670:
671: While the cursor appears to point @var{at} a character, point should be
672: thought of as @var{between} two characters; it points @var{before} the character
673: that the cursor appears on top of. Sometimes people speak of ``the
674: cursor'' when they mean ``point'', or speak of commands that move point as
675: ``cursor motion'' commands.
676:
677: Terminals have only one cursor, and when output is in progress it must
678: appear where the typing is being done. This does not mean that point is
679: moving. It is only that Emacs has no way to show you the location of point
680: except when the terminal is idle.
681:
682: Each Emacs buffer has its own point location. A buffer that is not being
683: displayed remembers where point is so that it can be seen when you look at
684: that buffer again.
685:
686: When there are multiple text windows, each window has its own point
687: location. The cursor shows the location of point in the selected window.
688: This also is how you can tell which window is selected. If the same buffer
689: appears in more than one window, point can be moved in each window
690: independently.
691:
692: The term `point' comes from the character @samp{.}, which was the
693: command in TECO (the language in which the original Emacs was written)
694: for accessing the value now called `point'.
695:
696: @node Echo Area, Mode Line, Point, Screen
697: @section The Echo Area
698: @cindex echo area
699:
700: The line at the bottom of the screen (below the mode line) is the
701: @dfn{echo area}. It is used to display small amounts of text for several
702: purposes.
703:
704: @dfn{Echoing} means printing out the characters that you type. Emacs
705: does not echo single-character keys, and does not echo any keys if you type
706: the characters with no long pause, but if you pause for more than a second
707: in the middle of a multi-character key, then all the characters typed so
708: far are echoed. This is intended to @dfn{prompt} you for the rest of the
709: key. Once the beginning of a key has been echoed, all the rest is echoed
710: as soon as it is typed; so either the entire key or none of it is echoed.
711: This behavior is designed to give confident users fast response, while
712: giving hesitant users maximum feedback. This behavior is controlled by a
713: variable you can change (@pxref{Display Vars}).
714:
715: If a command cannot be executed, it may print an @dfn{error message} in
716: the echo area. Error messages are accompanied by a beep or by flashing the
717: screen. Also, any input you have typed ahead is thrown away when an error
718: happens.
719:
720: Some commands print informative messages in the echo area. These
721: messages look much like error messages, but they are not announced with a
722: beep and do not throw away input. Sometimes the message tells you what the
723: command has done, when it is not obvious from looking at the text being
724: edited. Sometimes the sole purpose of a command is to print a message
725: giving you specific information. For example, the command @kbd{C-x =} is
726: used to print a message describing the character position of point in the
727: text and its current column in the window. Commands that take a long time
728: often display messages ending in @samp{@dots{}} while they are working, and
729: add @samp{done} at the end when they are finished.
730:
731: The echo area is also used to display the @dfn{minibuffer}, a window that
732: is used for reading arguments to commands, such as the name of a file to be
733: edited. When the minibuffer is in use, the echo area begins with a prompt
734: string that ends with a colon; also, the cursor appears in that line
735: because it is the selected window. You can always get out of the
736: minibuffer by typing @kbd{C-g}. @xref{Minibuffer}.
737:
738: @node Mode Line,, Echo Area, Screen
739: @section The Mode Line
740: @cindex mode line
741: @cindex top level
742:
743: Each text window's last line is a @dfn{mode line} which describes what is
744: going on in that window. When there is only one text window, the mode line
745: appears right above the echo area. The mode line is in inverse video if
746: the terminal supports that, starts and ends with dashes, and contains text
747: like @samp{Emacs:@: @var{something}}.
748:
749: If a mode line has something else in place of @samp{Emacs:@: @var{something}},
750: then the window above it is in a special subsystem such as Rmail. The mode
751: line then indicates the status of the subsystem.
752:
753: Normally, the mode line has the following appearance:
754:
755: @example
756: --@var{ch}-Emacs: @var{buf} (@var{major} @var{minor})----@var{pos}------
757: @end example
758:
759: @noindent
760: This serves to indicate various information about the buffer being
761: displayed in the window: the buffer's name, what major and minor modes are
762: in use, whether the buffer's text has been changed, and how far down the
763: buffer you are currently looking. The top level mode line has this format:
764:
765: @var{ch} contains two stars @samp{**} if the text in the buffer has been
766: edited (the buffer is ``modified''), or @samp{--} if the buffer has not been
767: edited. Exception: for a read-only buffer, it is @samp{%%}.
768:
769: @var{buf} is the name of the window's chosen @dfn{buffer}. The chosen buffer
770: in the selected window (the window that the cursor is in) is also Emacs's
771: selected buffer, the one that editing takes place in. When we speak of
772: what some command does to ``the buffer'', we are talking about the
773: currently selected buffer. @xref{Buffers}.
774:
775: @var{major} is the name of the @dfn{major mode} in effect in the buffer. At
776: any time, each buffer is in one and only one of the possible major modes.
777: The major modes available include Fundamental mode (the least specialized),
778: Text mode, Lisp mode, C mode, and others. @xref{Major Modes}, for details
779: of how the modes differ and how to select one.@refill
780:
781: @var{minor} is a list of some of the @dfn{minor modes} that are turned on
782: at the moment in the window's chosen buffer. @samp{Fill} means that Auto
783: Fill mode is on. @samp{Abbrev} means that Word Abbrev mode is on.
784: @samp{Overwrite} means that Overwrite mode is on. @xref{Minor Modes}, for
785: more information. @samp{Narrow} means that the buffer being displayed has
786: editing restricted to only a portion of its text. This is not really a
787: minor mode, but is like one. @xref{Narrowing}.@refill
788:
789: @var{pos} tells you whether there is additional text above the top of the
790: screen, or below the bottom. If your file is small and it is all on the
791: screen, @var{pos} is @samp{All}. Otherwise, it is @samp{Top} if you are
792: looking at the beginning of the file, @samp{Bot} if you are looking at the
793: end of the file, or @samp{@var{nn}%}, where @var{nn} is the percentage of
794: the file above the top of the screen.@refill
795:
796: Some other information about the state of Emacs can also be displayed
797: among the minor modes. @samp{Def} means that a keyboard macro is being
798: defined; although this is not exactly a minor mode, it is still useful to
799: be reminded about. @xref{Keyboard Macros}.
800:
801: In addition, if Emacs is currently inside a recursive editing level,
802: square brackets (@samp{[@dots{}]}) appear around the parentheses that
803: surround the modes. If Emacs is in one recursive editing level within
804: another, double square brackets appear, and so on. Since this information
805: pertains to Emacs in general and not to any one buffer, the square brackets
806: appear in every mode line on the screen or not in any of them.
807: @xref{Recursive Edit}.@refill
808:
809: @findex display-time
810: Emacs can optionally display the time and system load in all mode lines.
811: To enable this feature, type @kbd{M-x display-time}. The information added
812: to the mode line usually appears after the file name, before the mode names
813: and their parentheses. It looks like this:
814:
815: @example
816: @var{hh}:@var{mm}pm @var{l.ll} [@var{d}]
817: @end example
818:
819: @noindent
820: @var{hh} and @var{mm} are the hour and minute, followed always by @samp{am}
821: or @samp{pm}. @var{l.ll} is the average number of running processes in the
822: whole system recently. @var{d} is an approximate index of the ratio of
823: disk activity to cpu activity for all users.
824:
825: The word @samp{Mail} appears after the load level if there is mail for
826: you that you have not read yet.
827:
828: @vindex mode-line-inverse-video
829: Customization note: the variable @code{mode-line-inverse-video} controls
830: whether the mode line is displayed in inverse video (assuming the terminal
831: supports it); @code{nil} means no inverse video. The default is @code{t}.
832:
833: @iftex
834: @chapter Characters, Keys and Commands
835:
836: This chapter explains the character set used by Emacs for input commands
837: and for the contents of files, and also explains the concepts of
838: @dfn{keys} and @dfn{commands} which are necessary for understanding how
839: your keyboard input is understood by Emacs.
840: @end iftex
841:
842: @node Characters, Keys, Screen, Top
843: @section The Emacs Character Set
844: @cindex character set
845: @cindex ASCII
846:
847: GNU Emacs uses the ASCII character set, which defines 128 different
848: character codes. Some of these codes are assigned graphic symbols such
849: as @samp{a} and @samp{=}; the rest are control characters, such as
850: @kbd{Control-a} (also called @kbd{C-a} for short). @kbd{C-a} gets its name
851: from the fact that you type it by holding down the @key{CTRL} key and
852: then pressing @kbd{a}. There is no distinction between @kbd{C-a} and
853: @kbd{C-A}; they are the same character.@refill
854:
855: Some control characters have special names, and special keys you can
856: type them with: @key{RET}, @key{TAB}, @key{LFD}, @key{DEL} and @key{ESC}.
857: The space character is usually referred to below as @key{SPC}, even though
858: strictly speaking it is a graphic character whose graphic happens to be
859: blank.@refill
860:
861: Emacs extends the 7-bit ASCII code to an 8-bit code by adding an extra
862: bit to each character. This makes 256 possible command characters. The
863: additional bit is called Meta. Any ASCII character can be made Meta;
864: examples of Meta characters include @kbd{Meta-a} (@kbd{M-a}, for short),
865: @kbd{M-A} (not the same character as @kbd{M-a}, but those two characters
866: normally have the same meaning in Emacs), @kbd{M-@key{RET}}, and
867: @kbd{M-C-a}. For traditional reasons, @kbd{M-C-a} is usually called
868: @kbd{C-M-a}; logically speaking, the order in which the modifier keys
869: @key{CTRL} and @key{META} are mentioned does not matter.@refill
870:
871: @cindex Control
872: @cindex Meta
873: @cindex C-
874: @cindex M-
875: Some terminals have a @key{META} key, and allow you to type Meta
876: characters by holding this key down. Thus, @kbd{Meta-a} is typed by
877: holding down @key{META} and pressing @kbd{a}. Such a key is not always
878: labeled @key{META}, however, as it is usually a special option from the
879: manufacturer. If there is no @key{META} key, you can still type Meta
880: characters using two-character sequences starting with @key{ESC}. Thus, to
881: enter @kbd{M-a}, you could type @kbd{@key{ESC} a}. To enter @kbd{C-M-a},
882: you would type @kbd{@key{ESC} C-a}. @key{ESC} is allowed on terminals with
883: Meta keys, too, in case you have formed a habit of doing it.@refill
884:
885: @vindex meta-flag
886: Emacs believes the terminal has a @key{META} key if the variable
887: @code{meta-flag} is non-@code{nil}. Normally this is set automatically
888: according to the termcap entry for your terminal type. However, sometimes
889: the termcap entry is wrong, and then it is useful to set this variable
890: yourself.
891:
892: Emacs buffers also use an 8-bit character set, because bytes have 8 bits,
893: but only the ASCII characters are considered meaningful. ASCII graphic
894: characters in Emacs buffers are displayed with their graphics. @key{LFD}
895: is the same as a newline character; it is displayed by starting a new line.
896: @key{TAB} is displayed by moving to the next tab stop column (usually every
897: 8 columns). Other control characters are displayed as a caret (@samp{^})
898: followed by the non-control version of the character; thus, @kbd{C-a} is
899: displayed as @samp{^A}. Non-ASCII characters 128 and up are displayed with
900: octal escape sequences; thus, character code 243 (octal), also called
901: @kbd{M-#} when used as an input character, is displayed as @samp{\243}.
902:
903: @node Keys, Commands, Characters, Top
904: @section Keys
905:
906: @cindex key
907: A @dfn{key}---short for @dfn{key sequence}---is a sequence of characters
908: that is all part of specifying a single Emacs command to be run. If the
909: characters are enough to specify a command, they form a @dfn{complete key}.
910:
911: @kindex C-c
912: @kindex C-x
913: @kindex C-h
914: @kindex ESC
915: A single character is always a key; whether it is complete depends on its
916: meaning in Emacs. Most single characters are complete Emacs commands.
917: @kbd{C-c}, @kbd{C-h}, @kbd{C-x} and @key{ESC} are the only ones that are not complete.
918:
919: @cindex prefix key
920: A sequence of characters that is not enough to specify an Emacs command
921: is called a @dfn{prefix key}. A prefix key is the beginning of a series of
922: longer sequences that are valid keys; adding any single character to the
923: end of the prefix gives a valid key, which could be defined as an Emacs
924: command. For example, @kbd{C-x} is normally defined as a prefix, so
925: @kbd{C-x} and the next input character combine to make a two-character key.
926: There are 256 different two-character keys starting with @kbd{C-x}, one for
927: each possible second character. Many of these two-character keys starting
928: with @kbd{C-x} are standardly defined as Emacs commands. Notable examples
929: include @kbd{C-x C-f} and @kbd{C-x s} (@pxref{Files}).
930:
931: Adding one character to a prefix key does not have to form a complete
932: key. It could make another, longer prefix. For example, @kbd{C-x 4} is
933: itself a prefix that leads to 256 different three-character keys, including
934: @kbd{C-x 4 f}, @kbd{C-x 4 b} and so on. It would be possible to define one
935: of those three-character sequences as a prefix, creating a series of
936: four-character keys, but we did not define any of them this way.
937:
938: All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
939: @kbd{C-x 4}, and @key{ESC}. But this is not built in; it is just a matter
940: of Emacs's standard key bindings. In customizing Emacs, you could make
941: new prefix keys, or eliminate these. @xref{Key Bindings}.
942:
943: @node Commands, Entering Emacs, Keys, Top
944: @section Keys and Commands
945:
946: @cindex binding
947: @cindex customization
948: @cindex keymap
949: @cindex function
950: @cindex command
951: This manual is full of passages that tell you what particular keys do.
952: But Emacs does not assign meanings to keys directly. Instead, Emacs
953: assigns meanings to @dfn{functions}, and then gives keys their meanings by
954: @dfn{binding} them to functions.
955:
956: A function is a Lisp object that can be executed as a program.
957: Usually it is a Lisp symbol which has been given a function definition;
958: every symbol has a name, usually made of a few English words separated by
959: dashes, such as @code{next-line} or @code{forward-word}. It also has a
960: @dfn{definition} which is a Lisp program; this is what makes the function
961: do what it does. Only some functions can be the bindings of keys; these
962: are functions whose definitions use @code{interactive} to specify how to
963: call them interactively. Such functions are called @dfn{commands}, and
964: the name of a symbol that is a command is called a @dfn{command name}.
965: More information on this subject will appear in the @i{GNU Emacs Lisp
966: Manual} (which is not yet written).
967:
968: The bindings between keys and functions are recorded in various tables
969: called @dfn{keymaps}. @xref{Keymaps}.
970:
971: When we say that ``@kbd{C-n} moves down vertically one line'' we are
972: glossing over a distinction that is irrelevant in ordinary use but is vital
973: in understanding how to customize Emacs. It is the function
974: @code{next-line} that is programmed to move down vertically. @kbd{C-n} has
975: this effect @i{because} it is bound to that function. If you rebind
976: @kbd{C-n} to the function @code{forward-word} then @kbd{C-n} will move
977: forward by words instead. Rebinding keys is a common method of
978: customization.@refill
979:
980: In the rest of this manual, we usually ignore this subtlety to keep
981: things simple. To give the customizer the information he needs, we
982: state the name of the command which really does the work in parentheses
983: after mentioning the key that runs it. For example, we will say that
984: ``The command @kbd{C-n} (@code{next-line}) moves point vertically down,''
985: meaning that @code{next-line} is a command that moves vertically down
986: and @kbd{C-n} is a key that is standardly bound to it.
987:
988: @cindex variables
989: While we are on the subject of customization information which you should
990: not be frightened of, it's a good time to tell you about @dfn{variables}.
991: Often the description of a command will say, ``To change this, set the
992: variable @code{mumble-foo}.'' A variable is a name used to remember a
993: value. Most of the variables documented in this manual exist just to
994: permit customization: the variable's value is examined by some command,
995: and changing the value makes the command behave differently. Until you
996: are interested in customizing, you can ignore this information. When you
997: are ready to be interested, read the basic information on variables, and
998: then the information on individual variables will make sense.
999: @xref{Variables}.
1000:
1001: @node Entering Emacs, Exiting, Commands, Top
1002: @chapter Entering and Exiting Emacs
1003: @cindex entering Emacs
1004: @cindex arguments (from shell)
1005:
1006: The simplest way to invoke Emacs is just to type @kbd{emacs @key{RET}}
1007: at the shell.
1008:
1009: It is also possible to specify files to be visited, Lisp files to be
1010: loaded, and functions to be called, by giving Emacs arguments in the
1011: shell command line. The command arguments are processed in the order they
1012: appear in the command argument list; however, certain arguments must be at
1013: the front of the list (@samp{-t} or @samp{-batch}) if they are used.
1014:
1015: Here are the arguments allowed:
1016:
1017: @table @samp
1018: @item @var{file}
1019: Visit @var{file} using @code{find-file}. @xref{Visiting}.
1020:
1021: @item +@var{linenum} @var{file}
1022: Visit @var{file} using @code{find-file}, then go to line number
1023: @var{linenum} in it.
1024:
1025: @item -l @var{file}
1026: Load a file @var{file} of Lisp code with @code{load}. @xref{Lisp
1027: Libraries}.
1028:
1029: @item -f @var{function}
1030: Call Lisp function @var{function} with no arguments.
1031:
1032: @item -kill
1033: Exit from Emacs without asking for confirmation.
1034: @end table
1035:
1036: The remaining switches are recognized only at the beginning of the
1037: command line. If more than one of them appears, they must appear in the
1038: order that they appear in this table.
1039:
1040: @table @samp
1041: @item -t @var{device}
1042: Use @var{device} as the terminal for editing input and output.
1043:
1044: @cindex batch mode
1045: @item -batch
1046: Run Emacs in @dfn{batch mode}, which means that the text being edited is
1047: not displayed and the standard Unix interrupt characters such as @kbd{C-z}
1048: and @kbd{C-c} continue to have their normal effect. Emacs in batch mode
1049: outputs to @code{stdout} only what would normally be printed in the echo
1050: area under program control.
1051:
1052: Batch mode is used for running programs written in Emacs Lisp from
1053: shell scripts, makefiles, and so on. Normally the @samp{-l} switch
1054: or @samp{-f} switch will be used as well, to invoke a Lisp program
1055: to do the batch processing.
1056:
1057: @samp{-batch} implies @samp{-q} (do not load an init file). It also causes
1058: Emacs to kill itself after all command switches have been processed. In
1059: addition, auto-saving is not done except in buffers for which it has been
1060: explicitly requested.
1061:
1062: @item -q
1063: Do not load your Emacs init file @file{~/.emacs}.
1064:
1065: @item -u @var{user}
1066: Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
1067: your own.
1068: @end table
1069:
1070: One way to use command switches is to visit many files automatically:
1071:
1072: @example
1073: emacs *.c
1074: @end example
1075:
1076: @noindent
1077: passes each @code{.c} file as a separate argument to Emacs, so that Emacs
1078: visits each file (@pxref{Visiting}).
1079:
1080: Here is an advanced example that assumes you have a Lisp program
1081: file called @file{hack-c-program.el} which, when loaded, performs some
1082: useful operation on current buffer, expected to be a C program.
1083:
1084: @example
1085: emacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
1086: @end example
1087:
1088: @noindent
1089: Here Emacs is told to visit @file{foo.c}, load @file{hack-c-program.el}
1090: (which makes changes in the visited file), save @file{foo.c} (note that
1091: @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
1092: then exit to the shell that this command was done with. @samp{-batch}
1093: guarantees there will be no problem redirecting output to @file{log},
1094: because Emacs will not assume that it has a display terminal to work with.
1095:
1096: @node Exiting, Basic, Entering Emacs, Top
1097: @section Exiting Emacs
1098: @cindex exiting
1099: @cindex killing Emacs
1100: @cindex suspending
1101:
1102: There are two commands for exiting Emacs because there are two kinds of
1103: exiting: @dfn{suspending} Emacs and @dfn{killing} Emacs. @dfn{Suspending} means
1104: stopping Emacs temporarily and returning control to its superior (usually
1105: the shell), allowing you to resume editing later in the same Emacs job,
1106: with the same files, same kill ring, same undo history, and so on. This is
1107: the usual way to exit. @dfn{Killing} Emacs means destroying the Emacs job.
1108: You can run Emacs again after killing it, but you will get a fresh Emacs;
1109: there is no way to resume the same editing session after it has been
1110: killed.
1111:
1112: @kindex C-z
1113: @findex suspend-emacs
1114: To suspend Emacs, type @kbd{C-z} (@code{suspend-emacs}). On systems that do not
1115: permit programs to be suspended, @kbd{C-z} runs an inferior shell that
1116: communicates directly with the terminal, and Emacs waits until you exit
1117: the subshell. The only way on these systems to get back to the shell from
1118: which Emacs was run (to log out, for example) is to kill Emacs. @kbd{C-d} or
1119: @code{exit} are typical commands to exit a subshell.
1120:
1121: @kindex C-x C-c
1122: @findex save-buffers-kill-emacs
1123: To kill Emacs, type @kbd{C-x C-c} (@code{save-buffers-kill-emacs}). A
1124: two-character key is used for this to make it harder to type. Unless a
1125: numeric argument is used, this command first offers to save any modified
1126: buffers. If you do not save them all, it asks for reconfirmation with
1127: `yes' before killing Emacs, since any changes not saved before that will be
1128: lost forever. Also, if any subprocesses are still running, @kbd{C-x C-c}
1129: asks for confirmation about them, since killing Emacs will kill the
1130: subprocesses immediately.
1131:
1132: In most programs running on Berkeley Unix, @b{but not in Emacs}, the
1133: characters @kbd{C-z} and @kbd{C-c} instantly suspend or kill, respectively.
1134: The meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were inspired
1135: by the standard Unix meanings of @kbd{C-z} and @kbd{C-c}, but there is no
1136: causal connection. The standard Berkeley Unix handling of @kbd{C-z} and
1137: @kbd{C-c} is turned off in Emacs. You could customize these keys to do
1138: anything (@pxref{Keymaps}).
1139:
1140: @c??? What about system V here?
1141:
1142: @node Basic, Undo, Exiting, Top
1143: @chapter Basic Editing Commands
1144:
1145: @kindex C-h t
1146: @findex help-with-tutorial
1147: We now give the basics of how to enter text, make corrections, and
1148: save the text in a file. If this material is new to you, you might
1149: learn it more easily by running the Emacs learn-by-doing tutorial. To
1150: do this, type @kbd{Control-h t} (@code{help-with-tutorial}).
1151:
1152: @section Inserting Text
1153:
1154: @cindex insertion
1155: @cindex point
1156: @cindex cursor
1157: @cindex graphic characters
1158: To insert printing characters into the text you are editing, just
1159: type them. Except in special modes, Emacs defines each printing
1160: character as a key to run the command @code{self-insert}, which inserts
1161: the character that you typed to invoke it into the buffer at the
1162: cursor (that is, at @dfn{point}; @pxref{Point}). The cursor moves
1163: forward. Any characters after the cursor move forward too. If the
1164: text in the buffer is @samp{FOOBAR}, with the cursor before the
1165: @samp{B}, then if you type @kbd{XX}, you get @samp{FOOXXBAR}, with the
1166: cursor still before the @samp{B}.
1167:
1168: @kindex DEL
1169: @cindex deletion
1170: @findex delete-backward-char
1171: To @dfn{delete} text you have just inserted, you can use @key{DEL}
1172: (which runs the command named @code{delete-backward-char}). @key{DEL}
1173: deletes the character @var{before} the cursor (not the one that the cursor
1174: is on top of or under; that is the character @var{after} the cursor). The
1175: cursor and all characters after it move backwards. Therefore, if you type
1176: a printing character and then type @key{DEL}, they cancel out.
1177:
1178: @kindex RET
1179: @findex newline
1180: @cindex newline
1181: To end a line and start typing a new one, type @key{RET} (running the
1182: command @code{newline}). @key{RET} operates by inserting a newline
1183: character in the buffer. If point is in the middle of a line, @key{RET}
1184: splits the line. Typing @key{DEL} when the cursor is at the beginning of a
1185: line rubs out the newline before the line, thus joining the line with the
1186: preceding line.
1187:
1188: @cindex quoting
1189: @kindex C-q
1190: @findex quoted-insert
1191: Direct insertion works for printing characters and @key{SPC}, but other
1192: characters act as editing commands and do not insert themselves. If you
1193: need to insert a control character or a character whose code is above 200
1194: octal, you must @dfn{quote} it by typing @kbd{Control-q} (@code{quoted-insert}) first.
1195: There are two ways to use @kbd{C-q}:
1196:
1197: @itemize @bullet
1198: @item
1199: @kbd{Control-q} followed by any non-graphic character (even @kbd{C-g})
1200: inserts that character.
1201: @item
1202: @kbd{Control-q} followed by three octal digits inserts the character
1203: with the specified character code.
1204: @end itemize
1205:
1206: @noindent
1207: A numeric argument to @kbd{C-q} specifies how many copies of the
1208: quoted character should be inserted (@pxref{Arguments}).
1209:
1210: @section Changing the Location of Point
1211:
1212: To do more than insert characters, you have to know how to move
1213: point (@pxref{Point}). Here are a few of the commands for doing that.
1214:
1215: @kindex C-a
1216: @kindex C-e
1217: @kindex C-f
1218: @kindex C-b
1219: @kindex C-n
1220: @kindex C-p
1221: @kindex C-l
1222: @kindex C-t
1223: @kindex M->
1224: @kindex M-<
1225: @findex beginning-of-line
1226: @findex end-of-line
1227: @findex forward-char
1228: @findex backward-char
1229: @findex next-line
1230: @findex previous-line
1231: @findex recenter
1232: @findex transpose-chars
1233: @findex beginning-of-buffer
1234: @findex end-of-buffer
1235: @findex goto-char
1236: @table @kbd
1237: @item C-a
1238: Move to the beginning of the line (@code{beginning-of-line}).
1239: @item C-e
1240: Move to the end of the line (@code{end-of-line}).
1241: @item C-f
1242: Move forward one character (@code{forward-char}).
1243: @item C-b
1244: Move backward one character (@code{backward-char}).
1245: @item C-n
1246: Move down one line, vertically (@code{next-line}). This command
1247: attempts to keep the horizontal position unchanged, so if you start in
1248: the middle of one line, you end in the middle of the next. When on
1249: the last line of text, @kbd{C-n} creates a new line and moves onto it.
1250: @item C-p
1251: Move up one line, vertically (@code{previous-line}).
1252: @item C-l
1253: Clear the screen and reprint everything (@code{recenter}).
1254: @item C-t
1255: Transpose two characters, the ones before and after the cursor
1256: (@code{transpose-chars}).
1257: @item M-<
1258: Move to the top of the buffer (@code{beginning-of-buffer}). With
1259: numeric argument @var{n}, move to @var{n}/10 of the way from the top.
1260: @xref{Arguments}, for more information on numeric arguments.@refill
1261: @item M->
1262: Move to the end of the buffer (@code{end-of-buffer}).
1263: @item M-x goto-char
1264: Read a number @var{n} and move cursor to character number @var{n}.
1265: Position 1 is the beginning of the buffer.
1266: @item M-x goto-line
1267: Read a number @var{n} and move cursor to line number @var{n}. Line 1
1268: is the beginning of the buffer.
1269: @item C-x C-n
1270: Use the current column of point as the @dfn{semipermanent goal column} for
1271: @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). Henceforth, those
1272: commands always move to this column in each line moved into, or as
1273: close as possible given the contents of the line. This goal column remains
1274: in effect until canceled.
1275: @item C-u C-x C-n
1276: Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} once
1277: again try to avoid changing the horizontal position, as usual.
1278: @end table
1279:
1280: @vindex track-eol
1281: If you set the variable @code{track-eol} to a non-@code{nil} value, then
1282: @kbd{C-n} and @kbd{C-p} when at the end of the starting line move to the
1283: end of the line. Normally, @code{track-eol} is @code{nil}.
1284:
1285: @section Erasing Text
1286:
1287: @table @kbd
1288: @item @key{DEL}
1289: Delete the character before the cursor (@code{delete-backward-char}).
1290: @item C-d
1291: Delete the character after the cursor (@code{delete-char}).
1292: @item C-k
1293: Kill to the end of the line (@code{kill-line}).
1294: @end table
1295:
1296: You already know about the @key{DEL} key which deletes the character
1297: before the cursor. Another key, @kbd{Control-d}, deletes the character
1298: after the cursor, causing the rest of the text on the line to shift left.
1299: If @kbd{Control-d} is typed at the end of a line, that line and the next
1300: line are joined together.
1301:
1302: To erase a larger amount of text, use the @kbd{Control-k} key, which
1303: kills a line at a time. If @kbd{Control-k} is done at the beginning or
1304: middle of a line, it kills all the text up to the end of the line. If
1305: @kbd{Control-k} is done at the end of a line, it joins that line and the
1306: next line.
1307:
1308: @xref{Killing}, for more flexible ways of killing text.
1309:
1310: @section Files
1311:
1312: @cindex files
1313: The commands above are sufficient for creating and altering text in an
1314: Emacs buffer; the more advanced Emacs commands just make things easier.
1315: But to keep any text permanently you must put it in a @dfn{file}. Files
1316: are named units of text which are stored by the operating system for you to
1317: retrieve later by name. To look at or use the contents of a file in any
1318: way, including editing the file with Emacs, you must specify the file name.
1319:
1320: Consider a file named @file{/usr/rms/foo.c}. To edit this file in Emacs,
1321: type
1322:
1323: @example
1324: C-x C-f /usr/rms/foo.c @key{RET}
1325: @end example
1326:
1327: @noindent
1328: Here the file name is given as an @dfn{argument} to the command @kbd{C-x
1329: C-f} (@code{find-file}). @key{RET} is used to terminate the argument.
1330: Emacs obeys the command by @dfn{visiting} the file: creating a buffer,
1331: copying the contents of the file into the buffer, and then displaying the
1332: buffer for you to edit. You can make changes in it, and then @dfn{save}
1333: the file by typing @kbd{C-x C-s} (@code{save-buffer}). This makes the
1334: changes permanent by copying the altered contents of the buffer back into
1335: the file @file{/usr/rms/foo.c}. Until then, the changes are only inside
1336: your Emacs, and the file @file{foo.c} is not changed.@refill
1337:
1338: To create a file, just visit the file with @kbd{C-x C-f} as if it already
1339: existed. Emacs will make an empty buffer in which you can insert the text
1340: you want to put in the file. When you save your text with @kbd{C-x C-s},
1341: the file will be created.
1342:
1343: Of course, there is a lot more to learn about using files. @xref{Files}.
1344:
1345: @section Help
1346:
1347: If you forget what a key does, you can find out with the Help character,
1348: which is @kbd{C-h}. Type @kbd{C-h k} followed by the key you want to know
1349: about; for example, @kbd{C-h k C-n} tells you all about what @kbd{C-n}
1350: does. @kbd{C-h} is a prefix key; @kbd{C-h k} is just one of its
1351: subcommands (the command @code{describe-key}). The other subcommands of
1352: @kbd{C-h} provide different kinds of help. @xref{Help}.@refill
1353:
1354: @menu
1355: * Blank Lines:: Commands to make or delete blank lines.
1356: * Continuation Lines:: Lines too wide for the screen.
1357: * Position Info:: What page, line, row, or column is point on?
1358: * Arguments:: Numeric arguments for repeating a command.
1359: @end menu
1360:
1361: @node Blank Lines, Continuation Lines, Basic, Basic
1362: @section Blank Lines
1363:
1364: @c widecommands
1365: @table @kbd
1366: @item C-o
1367: Insert one or more blank lines after the cursor (@code{open-line}).
1368: @item C-x C-o
1369: Delete all but one of many consecutive blank lines
1370: (@code{delete-blank-lines}).
1371: @end table
1372:
1373: @kindex C-o
1374: @kindex C-x C-o
1375: @cindex blank lines
1376: @findex open-line
1377: @findex delete-blank-lines
1378: When you want to insert a new line of text before an existing line, you
1379: can do it by typing the new line of text, followed by @key{RET}. However,
1380: it may be easier to see what you are doing if you first make a blank line
1381: and then insert the desired text into it. This is easy to do using the key
1382: @kbd{C-o} (@code{open-line}), which inserts a newline after point but leaves
1383: point in front of the newline. After @kbd{C-o}, type the text for the new
1384: line. @kbd{C-o F O O} has the same effect as @kbd{F O O @key{RET}}, except for
1385: the final location of point.
1386:
1387: You can make several blank lines by typing @kbd{C-o} several times, or by
1388: giving it an argument to tell it how many blank lines to make.
1389: @xref{Arguments}, for how.
1390:
1391: If you have many blank lines in a row and want to get rid of them, use
1392: @kbd{C-x C-o} (@code{delete-blank-lines}). When point is on a blank line which
1393: is adjacent to at least one other blank line, @kbd{C-x C-o} deletes all but
1394: one of the consecutive blank lines, leaving exactly one. With point on a
1395: blank line with no other blank line adjacent to it, the sole blank line is
1396: deleted, leaving none. When point is on a nonblank line, @kbd{C-x C-o}
1397: deletes any blank lines following that nonblank line.
1398:
1399: @node Continuation Lines, Position Info, Blank Lines, Basic
1400: @section Continuation Lines
1401:
1402: @cindex continuation line
1403: If you add too many characters to one line, without breaking it with a
1404: @key{RET}, the line will grow to occupy two (or more) lines on the screen,
1405: with a @samp{\} at the extreme right margin of all but the last of them.
1406: The @samp{\} says that the following screen line is not really a distinct
1407: line in the text, but just the @dfn{continuation} of a line too long to fit
1408: the screen. Sometimes it is nice to have Emacs insert newlines
1409: automatically when a line gets too long; for this, use Auto Fill mode
1410: (@pxref{Filling}).
1411:
1412: @vindex truncate-lines
1413: @vindex default-truncate-lines
1414: @cindex truncation
1415: Continuation can be turned off for a particular buffer by setting the
1416: variable @code{truncate-lines} to non-@code{nil} in that buffer. Then,
1417: lines are @dfn{truncated}: the text that goes past the right margin does
1418: not appear at all. @samp{$} is used in the last column instead of @samp{\}
1419: when truncation is in effect. Truncation instead of continuation also
1420: happens whenever horizontal scrolling is in use, and optionally whenever
1421: side-by-side windows are in use (@pxref{Windows}). @code{truncate-lines}
1422: is automatically local in all buffers. When a buffer is created, its value
1423: of @code{truncate-lines} is initialized from the value of @code{default-truncate-lines},
1424: normally @code{nil}.
1425:
1426: @node Position Info, Arguments, Continuation Lines, Basic
1427: @section Cursor Position Information
1428:
1429: If you are accustomed to other display editors, you may be surprised that
1430: Emacs does not always display the page number or line number of point in
1431: the mode line. This is because the text is stored in a way that makes it
1432: difficult to compute this information. Displaying them all the time would
1433: be intolerably slow. They are not needed very often in Emacs anyway,
1434: but there are commands to print them.
1435:
1436: @table @kbd
1437: @item C-x =
1438: Print character code of character after point, character position of
1439: point, and column of point (@code{what-cursor-position}).
1440: @item M-x what-page
1441: Print page number of point, and line number within page.
1442: @item M-x what-line
1443: Print line number of point in the buffer.
1444: @item M-=
1445: Print number of lines in the current region (@code{count-lines-region}).
1446: @end table
1447:
1448: @kindex C-x =
1449: @findex what-cursor-position
1450: The command @kbd{C-x =} (@code{what-cursor-position}) can be used to find out
1451: the column that the cursor is in, and other miscellaneous information about
1452: point. It prints a line in the echo area that looks like this:
1453:
1454: @example
1455: Char: x (0170) point=65986 of 563027(12%) x=44
1456: @end example
1457:
1458: @noindent
1459: (In fact, this is the output produced when point is before the @samp{x=44}
1460: in the example.)
1461:
1462: The two values after @samp{Char:} describe the character following point,
1463: first by showing it and second by giving its octal character code.
1464:
1465: @samp{point=} is followed by the position of point expressed as a character
1466: count. The front of the buffer counts as position 1, one character later
1467: as 2, and so on. The next, larger number is the total number of characters
1468: in the buffer. Afterward in parentheses comes the position expressed as a
1469: percentage of the total size.
1470:
1471: @samp{x=} is followed by the horizontal position of point, in columns from the
1472: left edge of the window.
1473:
1474: If the buffer has been narrowed, making some of the text at the beginning and
1475: the end temporarily invisible, @kbd{C-x =} prints additional text describing the
1476: current visible range. For example, it might say
1477:
1478: @smallexample
1479: Char: x (0170) point=65986 of 563025(12%) <65102 - 68533> x=44
1480: @end smallexample
1481:
1482: @noindent
1483: where the two extra numbers give the smallest and largest character position
1484: that point is allowed to assume. The characters between those two positions
1485: are the visible ones. @xref{Narrowing}.
1486:
1487: If point is at the end of the buffer (or the end of the visible part),
1488: @kbd{C-x =} omits any description of the character after point.
1489: The output looks like
1490:
1491: @smallexample
1492: point=563026 of 563025(100%) x=0
1493: @end smallexample
1494:
1495: @noindent
1496: Usually @samp{x=0} at the end, because the text usually ends with a newline.
1497:
1498: @findex what-page
1499: @findex what-line
1500: There are two commands for printing line numbers. @kbd{M-x what-line}
1501: counts lines from the beginning of the file and prints the line number
1502: point is on. The first line of the file is line number 1. By contrast,
1503: @kbd{M-x what-page} counts pages from the beginning of the file, and
1504: counts lines within the page, printing both of them. @xref{Pages}.
1505:
1506: @kindex M-=
1507: @findex count-lines-region
1508: While on this subject, we might as well mention @kbd{M-=} (@code{count-lines-region}),
1509: which prints the number of lines in the region (@pxref{Mark}).
1510: @xref{Pages}, for the command @kbd{C-x l} which counts the lines in the
1511: current page.
1512:
1513: @node Arguments,, Position Info, Basic
1514: @section Numeric Arguments
1515: @cindex numeric arguments
1516:
1517: Any Emacs command can be given a @dfn{numeric argument}. Some commands
1518: interpret the argument as a repetition count. For example, giving an
1519: argument of ten to the key @kbd{C-f} (the command @code{forward-char}, move
1520: forward one character) moves forward ten characters. With these commands,
1521: no argument is equivalent to an argument of one. Negative arguments are
1522: allowed. Often they tell a command to move or act backwards.
1523:
1524: @kindex M-1
1525: @kindex M--
1526: @findex digit-argument
1527: @findex negative-argument
1528: If your terminal keyboard has a @key{META} key, the easiest way to
1529: specify a numeric argument is to type digits and/or a minus sign while
1530: holding down the the @key{META} key. For example,
1531: @example
1532: M-5 C-n
1533: @end example
1534: @noindent
1535: would move down five lines. The characters @kbd{Meta-1}, @kbd{Meta-2},
1536: etc., and @kbd{Meta--}, do this because they are keys bound to commands
1537: (@code{digit-argument} and @code{negative-argument}) that are defined to
1538: contribute to an argument for the next command.
1539:
1540: @kindex C-u
1541: @findex universal-argument
1542: Another way of specifying an argument is to use the @kbd{C-u}
1543: (@code{universal-argument}) command followed by the digits of the argument.
1544: With @kbd{C-u}, you can type the argument digits without holding
1545: down shift keys. To type a negative argument, start with a minus sign.
1546: Just a minus sign normally means -1. @kbd{C-u} works on all terminals.
1547:
1548: @kbd{C-u} followed by a character which is neither a digit nor a minus
1549: sign has the special meaning of ``multiply by four''. It multiplies the
1550: argument for the next command by four. @kbd{C-u} twice multiplies it by
1551: sixteen. Thus, @kbd{C-u C-u C-f} moves forward sixteen characters. This
1552: is a good way to move forward ``fast'', since it moves about 1/5 of a line
1553: in the usual size screen. Other useful combinations are @kbd{C-u C-n},
1554: @kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u C-u
1555: C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four
1556: lines).@refill
1557:
1558: Some commands care only about whether there is an argument, and not about
1559: its value. For example, the command @kbd{M-q} (@code{fill-paragraph}) with
1560: no argument fills text; with an argument, it justifies the text as well.
1561: (@xref{Filling}, for more information on @kbd{M-q}.) Just @kbd{C-u} is a
1562: handy way of providing an argument for such commands.
1563:
1564: Some commands use the value of the argument as a repeat count, but do
1565: something peculiar when there is no argument. For example, the command
1566: @kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines,
1567: including their terminating newlines. But @kbd{C-k} with no argument is
1568: special: it kills the text up to the next newline, or, if point is right at
1569: the end of the line, it kills the newline itself. Thus, two @kbd{C-k}
1570: commands with no arguments can kill a nonblank line, just like @kbd{C-k}
1571: with an argument of one. (@xref{Killing}, for more information on
1572: @kbd{C-k}.)@refill
1573:
1574: A few commands treat a plain @kbd{C-u} differently from an ordinary
1575: argument. A few others may treat an argument of just a minus sign
1576: differently from an argument of -1. These unusual cases will be described
1577: when they come up; they are always for reasons of convenience of use of the
1578: individual command.
1579:
1580: @c section Autoarg Mode
1581: @ignore
1582: @cindex autoarg mode
1583: Users of ASCII keyboards may prefer to use Autoarg mode. Autoarg mode
1584: means that you don't need to type C-U to specify a numeric argument.
1585: Instead, you type just the digits. Digits followed by an ordinary
1586: inserting character are themselves inserted, but digits followed by an
1587: Escape or Control character serve as an argument to it and are not
1588: inserted. A minus sign can also be part of an argument, but only at the
1589: beginning. If you type a minus sign following some digits, both the digits
1590: and the minus sign are inserted.
1591:
1592: To use Autoarg mode, set the variable Autoarg Mode nonzero.
1593: @xref{Variables}.
1594:
1595: Autoargument digits echo at the bottom of the screen; the first nondigit
1596: causes them to be inserted or uses them as an argument. To insert some
1597: digits and nothing else, you must follow them with a Space and then rub it
1598: out. C-G cancels the digits, while Delete inserts them all and then rubs
1599: out the last.
1600: @end ignore
1601:
1602: @node Undo, Minibuffer, Basic, Top
1603: @chapter Undoing Changes
1604: @cindex undo
1605:
1606: Emacs allows all changes made in the text of a buffer to be undone,
1607: up to a certain amount of change (8000 characters). Each buffer records
1608: changes individually, and the undo command always applies to the
1609: current buffer. Usually each editing command makes a separate entry
1610: in the undo records, but some commands such as @code{query-replace}
1611: make many entries, and very simple commands such as self-inserting
1612: characters are often grouped to make undoing less tedious.
1613:
1614: @table @kbd
1615: @item C-x u
1616: Undo one batch of changes (usually, one command worth) (@code{undo}).
1617: @item C-_
1618: The same.
1619: @end table
1620:
1621: @kindex C-x u
1622: @kindex C-_
1623: @findex undo
1624: The command @kbd{C-x u} or @kbd{C-_} is how you undo. The first
1625: time you give this command, it undoes the last change. Point moves to
1626: the beginning of the text affected by the undo, so you can see what
1627: was undone.@refill
1628:
1629: Consecutive repetitions of the @kbd{C-_} or @kbd{C-x u} commands undo
1630: earlier and earlier changes, back to the limit of what has been recorded.
1631: If all recorded changes have already been undone, the undo command gets an
1632: error.
1633:
1634: Any command other than an undo command breaks the sequence of undo
1635: commands. Starting at this moment, the previous undo commands are
1636: considered ordinary changes that can themselves be undone. Thus, you can
1637: redo changes you have undone by typing @kbd{C-@key{SPC}}, @kbd{C-f} or any
1638: other command that will have no important effect, and then using more undo
1639: commands.
1640:
1641: If you notice that a buffer has been modified accidentally, the easiest
1642: way to recover is to type @kbd{C-_} repeatedly until the stars disappear
1643: from the front of the mode line. At this time, all the modifications you
1644: made have been cancelled. If you do not remember whether you changed the
1645: buffer deliberately, type @kbd{C-_} once, and when you see the last change
1646: you made undone, you will remember why you made it. If it was an accident,
1647: leave it undone. If it was deliberate, redo the change as described in the
1648: preceding paragraph.
1649:
1650: Not all buffers record undo information. Buffers whose names start with
1651: spaces don't; these buffers are used internally by Emacs and its extensions
1652: to hold text that users don't normally look at or edit. Also, minibuffers,
1653: help buffers and documentation buffers don't record undo information.
1654:
1655: At most 8000 or so characters of deleted or modified text can be
1656: remembered in any one buffer for reinsertion by the undo command. Also,
1657: there is a limit on the number of individual insert, delete or change
1658: actions that can be remembered.
1659:
1660: The reason the @code{undo} command has two keys, @kbd{C-x u} and @kbd{C-_}, set
1661: up to run it is that it is worthy of a single-character key, but the way to
1662: type @kbd{C-_} on some keyboards is not obvious. @kbd{C-x u} is an
1663: alternative that requires no special knowledge of the terminal.
1664:
1665: @node Minibuffer, M-x, Undo, Top
1666: @chapter The Minibuffer
1667: @cindex minibuffer
1668:
1669: The @dfn{minibuffer} is the facility used by Emacs commands to read
1670: arguments more complicated than a single number. Minibuffer arguments can
1671: be file names, buffer names, Lisp function names, Emacs command names, Lisp
1672: expressions, and many other things, depending on the command reading the
1673: argument. The usual Emacs editing commands can be used to edit in the
1674: minibuffer also.
1675:
1676: @cindex prompt
1677: When the minibuffer is in use, it appears in the echo area, and the
1678: terminal's cursor moves there. The beginning of the minibuffer line
1679: displays a @dfn{prompt} which says what kind of input you should supply and
1680: how it will be used. Often this prompt is derived from the name of the
1681: command that the argument is for. The prompt normally ends with a colon.
1682:
1683: @cindex default argument
1684: Sometimes a @dfn{default argument} appears in parentheses after the
1685: colon; it too is part of the prompt. The default will be used as the
1686: argument value if you enter an empty argument (e.g., just type @key{RET}).
1687: For example, commands that read buffer names always show a default, which
1688: is the name of the buffer that will be used if you type just @key{RET}.
1689:
1690: @kindex C-g
1691: The simplest way to give a minibuffer argument is to type the text you
1692: want, terminated by @key{RET} which exits the minibuffer. You can get out
1693: of the minibuffer, canceling the command that it was for, by typing
1694: @kbd{C-g}.
1695:
1696: Since the minibuffer uses the screen space of the echo area, it can
1697: conflict with other ways Emacs customarily uses the echo area. Here is how
1698: Emacs handles such conflicts:
1699:
1700: @itemize @bullet
1701: @item
1702: If a command gets an error while you are in the minibuffer, this does
1703: not cancel the minibuffer. However, the echo area is needed for the
1704: error message and therefore the minibuffer itself is hidden for a
1705: while. It comes back after a few seconds.
1706:
1707: @item
1708: If in the minibuffer you use a command whose purpose is to print a
1709: message in the echo area, such as @kbd{C-x =}, the message is printed
1710: normally, and the minibuffer is hidden for a while. It comes back
1711: after a few seconds.
1712:
1713: @item
1714: Echoing of keystrokes does not take place while the minibuffer is in
1715: use.
1716: @end itemize
1717:
1718: @menu
1719: * File: Minibuffer File. Entering file names with the minibuffer.
1720: * Edit: Minibuffer Edit. How to edit in the minibuffer.
1721: * Completion:: An abbreviation facility for minibuffer input.
1722: * Repetition:: Re-executing commands that used the minibuffer.
1723: @end menu
1724:
1725: @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer
1726: @section Minibuffers for File Names
1727:
1728: Sometimes the minibuffer starts out with text in it. For example, when
1729: you are supposed to give a file name, the minibuffer starts out containing
1730: the @dfn{default directory}, which ends with a slash. This is to inform
1731: you which directory the file will be found in if you do not specify a
1732: directory. For example, the minibuffer might start out with
1733:
1734: @example
1735: Find File: /u2/emacs/src/
1736: @end example
1737:
1738: @noindent
1739: where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c} specifies
1740: the file @file{/u2/emacs/src/buffer.c}. To find files in nearby
1741: directories, use @kbd{..}; thus, if you type @kbd{../lisp/simple.el}, the
1742: file that you visit will be the one named @file{/u2/emacs/lisp/simple.el}.
1743: Alternatively, you can kill with @kbd{M-@key{DEL}} the directory names you
1744: don't want (@pxref{Words}).@refill
1745:
1746: You can also type an absolute file name, one starting with a slash or a
1747: tilde, ignoring the default directory. For example, to find the file
1748: @file{/etc/termcap}, just type the name, giving
1749:
1750: @example
1751: Find File: /u2/emacs/src//etc/termcap
1752: @end example
1753:
1754: @noindent
1755: Two slashes in a row are not normally meaningful in Unix file names, but
1756: they are allowed in GNU Emacs. They mean, ``ignore everything before the
1757: second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored, and
1758: you get the file @file{/etc/termcap}.
1759:
1760: @vindex insert-default-directory
1761: If you set @code{insert-default-directory} to @code{nil}, the default directory
1762: is not inserted in the minibuffer. This way, the minibuffer starts out
1763: empty. But the name you type, if relative, is still interpreted with
1764: respect to the same default directory.
1765:
1766: @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer
1767: @section Editing in the Minibuffer
1768:
1769: The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual
1770: Emacs commands are available for editing the text of an argument you are
1771: entering.
1772:
1773: Since @key{RET} in the minibuffer is defined to exit the minibuffer,
1774: inserting a newline into the minibuffer must be done with @kbd{C-o} or with
1775: @kbd{C-q @key{LFD}}. (Recall that a newline is really the @key{LFD}
1776: character.)
1777:
1778: The minibuffer has its own window which always has space on the screen
1779: but acts as if it were not there when the minibuffer is not in use. When
1780: the minibuffer is in use, its window is just like the others; you can
1781: switch to another window with @kbd{C-x o}, edit text in other windows and
1782: perhaps even visit more files, before returning to the minibuffer to submit
1783: the argument. You can kill text in another window, return to the
1784: minibuffer window, and then yank the text to use it in the argument.
1785: @xref{Windows}.
1786:
1787: There are some restrictions on the use of the minibuffer window, however.
1788: You cannot switch buffers in it---the minibuffer and its window are
1789: permanently attached. Also, you cannot split the minibuffer window.
1790:
1791: Recursive use of the minibuffer is supported by Emacs. However, it is
1792: easy to do this by accident (because of autorepeating keyboards, for
1793: example) and get confused. Therefore, most Emacs commands that use the
1794: minibuffer refuse to operate if the minibuffer window is selected. If the
1795: minibuffer is active but you have switched to a different window, recursive
1796: use of the minibuffer is allowed---if you know enough to try to do this,
1797: you probably will not get confused.
1798:
1799: @vindex enable-recursive-minibuffers
1800: If you set the variable @code{enable-recursive-minibuffers} to be
1801: non-@code{nil}, recursive use of the minibuffer is always allowed.
1802:
1803: @node Completion, Repetition, Minibuffer Edit, Minibuffer
1804: @section Completion
1805: @cindex completion
1806:
1807: When appropriate, the minibuffer provides a @dfn{completion} facility.
1808: This means that you type enough of the argument to determine the rest,
1809: based on Emacs's knowledge of which arguments make sense, and Emacs visibly
1810: fills in the rest, or as much as can be determined from the part you have
1811: typed.
1812:
1813: When completion is available, certain keys---@key{TAB}, @key{RET}, and @key{SPC}---are
1814: redefined to complete an abbreviation present in the minibuffer into a
1815: longer string that it stands for, by matching it against a set of
1816: @dfn{completion alternatives} provided by the command reading the argument.
1817: @kbd{?} is defined to display a list of possible completions of what you
1818: have inserted.
1819:
1820: For example, when the minibuffer is being used by @kbd{Meta-x} to read
1821: the name of a command, it is given a list of all available Emacs command
1822: names to complete against. The completion keys match the text in the
1823: minibuffer against all the command names, find any additional characters of
1824: the name that are implied by the ones already present in the minibuffer,
1825: and add those characters to the ones you have given.
1826:
1827: @kindex TAB
1828: @findex minibuffer-complete
1829: A concrete example may help here. If you type @kbd{Meta-x au @key{TAB}}, the @key{TAB}
1830: looks for alternatives (in this case, command names) that start with
1831: @samp{au}. In this case, there are only two: @code{auto-fill-mode} and
1832: @code{auto-save-mode}. These are the same as far as @code{auto-}, so the
1833: @samp{au} in the minibuffer changes to @samp{auto-}.
1834:
1835: If you go on to type @kbd{f @key{TAB}}, this second @key{TAB} sees @samp{auto-f}.
1836: The only command name starting this way is @code{auto-fill-mode}, so that
1837: is the completion. You have now have @samp{auto-fill-mode} in the
1838: minibuffer after typing just @kbd{au @key{TAB} f @key{TAB}}. Note that
1839: @key{TAB} has this effect because in the minibuffer it is bound to the
1840: function @code{minibuffer-complete} when completion is supposed to be done.
1841:
1842: Case is normally significant in completion, because it is significant in
1843: most of the names that you can complete (buffer names, file names and
1844: command names). Thus, @samp{fo} will not complete to @samp{Foo}. When you
1845: are completing a name in which case does not matter, the program can request
1846: that case be ignored for completion as well.
1847:
1848: Here is a list of all the completion commands, defined in the minibuffer
1849: when completion is available.
1850:
1851: @table @kbd
1852: @item @key{TAB}
1853: Complete the text in the minibuffer as much as possible @*
1854: (@code{minibuffer-complete}).
1855: @item @key{SPC}
1856: Complete the text in the minibuffer but don't add or fill out more
1857: than one word (@code{minibuffer-complete-word}).
1858: @item @key{RET}
1859: Submit the text in the minibuffer as the argument, possibly completing
1860: first as described below (@code{minibuffer-complete-and-exit}).
1861: @item ?
1862: Print a list of all possible completions of the text in the minibuffer
1863: (@code{minibuffer-list-completions}).
1864: @end table
1865:
1866: @kindex SPC
1867: @findex minibuffer-complete-word
1868: @key{SPC} completes much like @key{TAB}, but never adds goes beyond the
1869: next hyphen. If you have @samp{auto-f} in the minibuffer and type
1870: @key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but it
1871: stops completing after @samp{fill-}. This gives @samp{auto-fill-}.
1872: Another @key{SPC} at this point completes all the way to
1873: @samp{auto-fill-mode}. @key{SPC} in the minibuffer runs the function
1874: @code{minibuffer-complete-word} when completion is available.
1875:
1876: There are three different ways that @key{RET} can work in completing
1877: minibuffers, depending on how the argument will be used.
1878:
1879: @itemize @bullet
1880: @item
1881: @dfn{Strict} completion is used when it is meaningless to give any
1882: argument except one of the known alternatives. For example, when
1883: @kbd{C-x k} reads the name of a buffer to kill, it is meaningless to
1884: give anything but the name of an existing buffer. In strict
1885: completion, @key{RET} refuses to exit if the text in the minibuffer
1886: does not complete to an exact match.
1887:
1888: @item
1889: @dfn{Cautious} completion is similar to strict completion, except that
1890: @key{RET} exits only if the text was an exact match already, not
1891: needing completion. If the text is not an exact match, @key{RET} does
1892: not exit, but it does complete the text. If it completes to an exact
1893: match, a second @key{RET} will exit.
1894:
1895: Cautious completion is used for reading file names for files that must
1896: already exist.
1897:
1898: @item
1899: @dfn{Permissive} completion is used when any string whatever is
1900: meaningful, and the list of completion alternatives is just a guide.
1901: For example, when @kbd{C-x C-f} reads the name of a file to visit, any
1902: file name is allowed, in case you want to create a file. In
1903: permissive completion, @key{RET} takes the text in the minibuffer
1904: exactly as given, without completing it.
1905: @end itemize
1906:
1907: @vindex completion-ignored-extensions
1908: When completion is done on file names, certain file names are usually
1909: ignored. The variable @code{completion-ignored-extensions} contains a list
1910: of strings; a file whose name ends in any of those strings is ignored as a
1911: possible completion. The standard value of this variable is @code{(".o"
1912: ".elc" "~")}, which is designed to allow @samp{foo} to complete to
1913: @samp{foo.c} even though @samp{foo.o} exists as well. If the only possible
1914: completions are files that end in ``ignored'' strings, then they are not
1915: ignored.
1916:
1917: @node Repetition,, Completion, Minibuffer
1918: @section Repeating Minibuffer Commands
1919:
1920: Every command that uses the minibuffer at least once is recorded on a
1921: special history list, together with the values of the minibuffer arguments,
1922: so that you can repeat the command easily. In particular, every
1923: use of @kbd{Meta-x} is recorded, since @kbd{M-x} uses the minibuffer to
1924: read the command name.
1925:
1926: @c widecommands
1927: @table @kbd
1928: @item C-x @key{ESC}
1929: Re-execute a recent minibuffer command @*(@code{repeat-complex-command}).
1930: @end table
1931:
1932: @kindex C-x ESC
1933: @findex repeat-complex-command
1934: @kbd{C-x @key{ESC}} is used to re-execute a recent minibuffer-using
1935: command. With no argument, it repeats the last such command. A numeric
1936: argument specifies which command to repeat; one means the last one, and
1937: larger numbers specify earlier ones.
1938:
1939: @kbd{C-x @key{ESC}} works by turning the previous command into a Lisp
1940: expression and then entering a minibuffer initialized with the text for
1941: that expression. If you type just @key{RET}, the command is repeated as
1942: before. You can also change the command by editing the Lisp expression.
1943: Whatever expression you finally submit is what will be executed. The
1944: repeated command does not go on the command history itself; @kbd{C-x
1945: @key{ESC}} does not alter the command history.
1946:
1947: @kindex M-n
1948: @kindex M-p
1949: @findex next-complex-command
1950: @findex previous-complex-command
1951: Once inside the minibuffer for @kbd{C-x @key{ESC}}, if the command shown
1952: to you is not the one you want to repeat, you can move around the list of
1953: previous commands using @kbd{M-n} and @kbd{M-p}. @kbd{M-p} replaces the
1954: contents of the minibuffer with the next earlier recorded command, and
1955: @kbd{M-n} replaces them with the next later command. After finding the
1956: desired previous command, you can edit its expression as usual and then
1957: resubmit it by typing @key{RET} as usual. Any editing you have done on the
1958: command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}.
1959:
1960: @kbd{M-p} is more useful than @kbd{M-n}, since more often you will
1961: initially request to repeat the most recent command and then decide to
1962: repeat an older one instead. These keys are specially defined within
1963: @kbd{C-x @key{ESC}} to run the commands @code{next-complex-command} and
1964: @code{previous-complex-command}.
1965:
1966: @vindex command-history
1967: The list of previous minibuffer-using commands is stored as a Lisp list
1968: in the variable @code{command-history}. Each element is a Lisp expression
1969: which describes one command and its arguments. The command can be
1970: reexecuted by feeding the corresponding @code{command-history} element to
1971: @code{eval}.
1972:
1973: @node M-x, Help, Minibuffer, Top
1974: @chapter Running Commands by Name
1975:
1976: The Emacs commands that are used often or that must be quick to type are
1977: bound to keys---short sequences of characters---for convenient use. Other
1978: Emacs commands that do not need to be brief are not bound to keys; to run
1979: them, you must refer to them by name.
1980:
1981: A command name is, by convention, made up of one or more words, separated
1982: by hyphens; for example, @code{auto-fill-mode} or @code{manual-entry}. The
1983: use of English words makes the command name easier to remember than a key
1984: made up of obscure characters, even though it is more characters to type.
1985: Any command can be run by name, even if it is also runnable by keys.
1986:
1987: @kindex M-x
1988: @findex execute-extended-command
1989: @cindex minibuffer
1990: The way to run a command by name is to start with @kbd{M-x}, type the
1991: command name, and finish it with @key{RET}. Actually, @kbd{M-x} (the command
1992: @code{execute-extended-command}) is using the minibuffer to read the
1993: command name.
1994:
1995: Emacs uses the minibuffer for reading input for many different purposes;
1996: on this occasion, the string @samp{M-x} is displayed at the beginning of
1997: the minibuffer as a @dfn{prompt} to remind you that your input should be
1998: the name of a command to be run. @xref{Minibuffer}, for full information
1999: the features of the minibuffer.
2000:
2001: You can use completion to enter the command name. For example, the
2002: command @code{forward-char} can be invoked by name by typing
2003:
2004: @example
2005: M-x forward-char @key{RET}
2006:
2007: @exdent or
2008:
2009: M-x fo @key{TAB} c @key{RET}
2010: @end example
2011:
2012: @noindent
2013: Note that @code{forward-char} is the same command that you invoke with
2014: the key @kbd{C-f}. Any command (interactively callable function) defined
2015: in Emacs can be called by its name using @kbd{M-x} whether or not any
2016: keys are bound to it.
2017:
2018: If you type @kbd{C-g} while the command name is being read, you cancel
2019: the @kbd{M-x} command and get out of the minibuffer, ending up at top level.
2020:
2021: To pass a numeric argument to the command you are invoking with
2022: @kbd{M-x}, specify the numeric argument before the @kbd{M-x}. @kbd{M-x}
2023: passes the argument along to the function which it calls. The argument
2024: value appears in the prompt while the command name is being read.
2025:
2026: Normally, when describing a command that is run by name, we omit the
2027: @key{RET} that is needed to terminate the name. Thus we might speak of
2028: @kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode @key{RET}}.
2029: We mention the @key{RET} only when there is a need to emphasize its
2030: presence, such as when describing a sequence of input that contains a
2031: command name and arguments that follow it.
2032:
2033: @iftex
2034: In this manual, the convention for font usage is that Lisp objects,
2035: including command names (which are Lisp symbols), appear in @code{this
2036: font}, but keyboard input appears in @kbd{this font}. This brings up
2037: a problem with names of commands that are normally run by name: is the
2038: name a piece of Lisp code, or is it a sequence of characters to type?
2039: Unfortunately, it is both, but only one of the two fonts can be used.
2040: I have chosen to use the Lisp object font when discussing the command,
2041: as in @code{auto-fill-mode}, but to use the keyboard input font for
2042: sequences of input, as in @kbd{M-x auto-fill-mode}.
2043: @end iftex
2044:
2045: @node Help, Mark, M-x, Top
2046: @chapter Help
2047: @kindex Help
2048: @cindex help
2049: @cindex self-documentation
2050:
2051: Emacs provides extensive help features which revolve around a single
2052: character, @kbd{C-h}. @kbd{C-h} is a prefix key that is used only for
2053: documentation-printing commands. The characters that you can type after
2054: @kbd{C-h} are called @dfn{help options}. One help option is @kbd{C-h};
2055: that is how you ask for help about using @kbd{C-h}.
2056:
2057: @kbd{C-h C-h} prints a list of the possible help options, and then asks
2058: you to go ahead and type the option. It prompts with a string
2059:
2060: @smallexample
2061: A, C, F, I, K, L, M, N, S, T, V, W, C-c, C-d, C-w or C-h for more help:
2062: @end smallexample
2063:
2064: @noindent
2065: and you should type one of those characters. Typing a third @kbd{C-h}
2066: displays a description of what the options mean; it still waits for you to
2067: type an option. To cancel, type @kbd{C-g}.
2068:
2069: Here is a summary of the defined help commands.
2070:
2071: @table @kbd
2072: @item C-h a
2073: Display list of commands whose names contain a specified string
2074: (@code{command-apropos}).
2075: @item C-h b
2076: Display a table of all key bindings in effect now; local bindings of
2077: the current major mode first, followed by all global bindings
2078: (@code{describe-bindings}).
2079: @item C-h c @var{key}
2080: Print the name of the command that @var{key} runs (@code{describe-key-briefly}).
2081: @kbd{c} is for `character'.
2082: @item C-h f @var{function} @key{RET}
2083: Display documentation on the Lisp function named @var{function}
2084: (@code{describe-function}). Note that commands are Lisp functions, so
2085: a command name may be used.
2086: @item C-h k @var{key}
2087: Display name and documentation of the command @var{key} runs (@code{describe-key}).
2088: @item C-h i
2089: Run Info, the program for browsing documentation files (@code{info}).
2090: @item C-h l
2091: Display a description of the last 100 characters you typed
2092: (@code{view-lossage}).
2093: @item C-h m
2094: Display documentation of the current major mode (@code{describe-mode}).
2095: @item C-h n
2096: Display documentation of Emacs changes, most recent first
2097: (@code{view-emacs-news}).
2098: @item C-h s
2099: Display current contents of the syntax table, plus an explanation of
2100: what they mean (@code{describe-syntax}).
2101: @item C-h t
2102: Display the Emacs tutorial (@code{help-with-tutorial}).
2103: @item C-h v @var{var} @key{RET}
2104: Display the documentation of the Lisp variable @var{var}
2105: (@code{describe-variable}).
2106: @item C-h w @var{command} @key{RET}
2107: Print which keys run the command named @var{command} (@code{where-is}).
2108: @end table
2109:
2110: @section Documentation for a Key
2111:
2112: @kindex C-h c
2113: @findex describe-key-briefly
2114: The most basic @kbd{C-h} options are @kbd{C-h c}
2115: (@code{describe-key-briefly}) and @kbd{C-h k} (@code{describe-key}).
2116: @kbd{C-h c @var{key}} prints in the echo area the name of the command that
2117: @var{key} is bound to. For example, @kbd{C-h c C-f} prints
2118: @samp{forward-char}. Since command names are chosen to describe what the
2119: command does, this is a good way to get a very brief description of what
2120: @var{key} does.@refill
2121:
2122: @kindex C-h k
2123: @findex describe-key
2124: @kbd{C-h k @var{key}} is similar but gives more information. It displays
2125: the documentation string of the command @var{key} is bound to as well as
2126: its name. This is too big for the echo area, so a window is used for the
2127: display.
2128:
2129: @section Help by Command or Variable Name
2130:
2131: @kindex C-h f
2132: @findex describe-function
2133: @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function
2134: using the minibuffer, then displays that function's documentation string
2135: in a window. Since commands are Lisp functions, you can use this to get
2136: the documentation of a command that is known by name. For example,
2137:
2138: @example
2139: C-h f auto-fill-mode @key{RET}
2140: @end example
2141:
2142: @noindent
2143: displays the documentation of @code{auto-fill-mode}. This is the only
2144: way to see the documentation of a command that is not bound to any key
2145: (one which you would normally call using @kbd{M-x}).
2146:
2147: @kbd{C-h f} is also useful for Lisp functions that you are planning to
2148: use in a Lisp program. For example, if you have just written the code
2149: @code{(make-vector len)} and want to be sure that you are using
2150: @code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. Because
2151: @kbd{C-h f} allows all function names, not just command names, you may find
2152: that some of your favorite abbreviations that work in @kbd{M-x} don't work
2153: in @kbd{C-h f}. An abbreviation may be unique among command names yet fail
2154: to be unique when other function names are allowed.
2155:
2156: The function name for @kbd{C-h f} to describe has a default which is
2157: used if you type @key{RET} leaving the minibuffer empty. The default is
2158: the function called by the innermost Lisp expression in the buffer around
2159: point, @i{provided} that is a valid, defined Lisp function name. For
2160: example, if point is located following the text @samp{(make-vector (car
2161: x)}, the innermost list containing point is the one that starts with
2162: @samp{(make-vector}, so the default is to describe the function
2163: @code{make-vector}.
2164:
2165: @kbd{C-h f} is often useful just to verify that you have the right
2166: spelling for the function name. If @kbd{C-h f} mentions a default in the
2167: prompt, you have typed the name of a defined Lisp function. If that tells
2168: you what you want to know, just type @kbd{C-g} to cancel the @kbd{C-h f}
2169: command and go on editing.
2170:
2171: @kindex C-h w
2172: @findex where-is
2173: @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
2174: @var{command}. It prints a list of the keys in the echo area.
2175: Alternatively, it says that the command is not on any keys, which implies
2176: that you must use @kbd{M-x} to call it.@refill
2177:
2178: @kindex C-h v
2179: @findex describe-variable
2180: @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes
2181: Lisp variables instead of Lisp functions. Its default is the Lisp symbol
2182: around or before point, but only if that is the name of a known Lisp
2183: variable. @xref{Variables}.@refill
2184:
2185: @section Apropos
2186:
2187: @kindex C-h a
2188: @findex command-apropos
2189: @cindex apropos
2190: A more sophisticated sort of question to ask is, ``What are the commands
2191: for working with files?'' For this, type @kbd{C-h a file @key{RET}}, which
2192: displays a list of all command names that contain @samp{file}, such as
2193: @code{copy-file}, @code{find-file}, and so on. With each command name
2194: appears a brief description of how to use the command, and what keys you
2195: can currently invoke it with. For example, it would say that you can
2196: invoke @code{find-file} by typing @kbd{C-x C-f}. The @kbd{a} in @kbd{C-h
2197: a} stands for `Apropos'; @kbd{C-h a} runs the Lisp function
2198: @code{command-apropos}.@refill
2199:
2200: Because @kbd{C-h a} looks only for functions whose names contain the
2201: string which you specify, you must use ingenuity in choosing substrings.
2202: If you are looking for commands for killing backwards and @kbd{C-h a
2203: kill-backwards @key{RET}} doesn't reveal any, don't give up. Try just
2204: @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}. Be persistent.
2205: Pretend you are playing Adventure.
2206:
2207: Here is a set of arguments to give to @kbd{C-h a} that covers many
2208: classes of Emacs commands, since there are strong conventions for naming
2209: the standard Emacs commands. By giving you a feel for the naming
2210: conventions, this set should also serve to aid you in developing a
2211: technique for picking @code{apropos} strings.
2212:
2213: @quotation
2214: char, line, word, sentence, paragraph, region, page, sexp, list, defun,
2215: buffer, screen, window, file, dir, register, mode,
2216: beginning, end, forward, backward, next, previous, up, down, search, goto,
2217: kill, delete, mark, insert, yank, fill, indent, case,
2218: change, set, what, list, find, view, describe.
2219: @end quotation
2220:
2221: @findex apropos
2222: To list all Lisp symbols that contain a match for a regexp, not just
2223: the ones that are defined as commands, use the command @kbd{M-x apropos}
2224: instead of @kbd{C-h a}.
2225:
2226: @section Other Help Commands
2227:
2228: @kindex C-h l
2229: @findex view-lossage
2230: If something surprising happens, and you are not sure what commands you
2231: typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} prints the last
2232: 100 command characters you typed in. If you see commands that you don't
2233: know, you can use @kbd{C-h c} to find out what they do.
2234:
2235: @kindex C-h m
2236: @findex describe-mode
2237: Emacs has several major modes, each of which redefines a few keys and
2238: makes a few other changes in how editing works. @kbd{C-h m} (@code{describe-mode})
2239: prints documentation on the current major mode, which normally describes
2240: all the commands that are changed in this mode.
2241:
2242: @kindex C-h b
2243: @findex describe-bindings
2244: @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
2245: (@code{describe-syntax}) present other information about the current
2246: Emacs mode. @kbd{C-h b} displays a list of all the key bindings now
2247: in effect; the local bindings of the current major mode first,
2248: followed by the global bindings (@pxref{Key Bindings}). @kbd{C-h s}
2249: displays the contents of the syntax table, with explanations of each
2250: character's syntax (@pxref{Syntax}).@refill
2251:
2252: @kindex C-h i
2253: @findex info
2254: @kindex C-h n
2255: @findex view-emacs-news
2256: @kindex C-h t
2257: @findex help-with-tutorial
2258: @kindex C-h C-c
2259: @findex describe-copying
2260: @kindex C-h C-d
2261: @findex describe-distribution
2262: @kindex C-h C-w
2263: @findex describe-no-warranty
2264: The other @kbd{C-h} options display various files of useful information.
2265: @kbd{C-h C-w} displays the full details on the complete absence of warranty
2266: for GNU Emacs. @kbd{C-h n} (@code{view-emacs-news}) displays the file
2267: @file{emacs/etc/NEWS}, which contains documentation on Emacs changes
2268: arranged chronologically. @kbd{C-h t} (@code{help-with-tutorial}) displays
2269: the learn-by-doing Emacs tutorial. @kbd{C-h i} (@code{info}) runs the Info
2270: program, which is used for browsing through structured documentation files.
2271: @kbd{C-h C-c} (@code{describe-copying}) displays the file
2272: @file{emacs/etc/COPYING}, which tells you the conditions you must obey in
2273: distributing copies of Emacs. @kbd{C-h C-d} (@code{describe-distribution})
2274: displays the file @file{emacs/etc/DISTRIB}, which tells you how you can
2275: order a copy of the latest version of Emacs.@refill
2276:
2277: @node Mark, Killing, Help, Top
2278: @chapter The Mark and the Region
2279: @cindex mark
2280: @cindex region
2281:
2282: There are many Emacs commands which operate on an arbitrary contiguous
2283: part of the current buffer. To specify the text for such a command to
2284: operate on, you set @dfn{the mark} at one end of it, and move point to the
2285: other end. The text between point and the mark is called @dfn{the region}.
2286: You can move point or the mark to adjust the boundaries of the region. It
2287: doesn't matter which one is set first chronologically, or which one comes
2288: earlier in the text.
2289:
2290: Once the mark has been set, it remains until it is set again at another
2291: place. The mark remains fixed with respect to the preceding character if
2292: text is inserted or deleted in the buffer. Each Emacs buffer has its own
2293: mark, so that when you return to a buffer that had been selected
2294: previously, it has the same mark it had before.
2295:
2296: Many commands that insert text, such as @kbd{C-y} (@code{yank}) and
2297: @kbd{M-x insert-buffer}, position the mark at one end of the inserted
2298: text---the opposite end from where point is positioned, so that the region
2299: contains the text just inserted.
2300:
2301: @menu
2302: * Mark Ring::
2303:
2304: Aside from delimiting the region, the mark is also useful for remembering
2305: a spot that you may want to go back to. To make this feature more useful,
2306: Emacs remembers 16 previous locations of the mark, in the @code{mark ring}.
2307: @end menu
2308:
2309: Here are some commands for setting the mark:
2310:
2311: @c WideCommands
2312: @table @kbd
2313: @item C-@key{SPC}
2314: Set the mark where point is (@code{set-mark-command}).
2315: @item C-@@
2316: The same.
2317: @item C-x C-x
2318: Interchange mark and point (@code{exchange-point-and-mark}).
2319: @item M-@@
2320: Set mark after end of next word (@code{mark-word}). This command and
2321: the following one do not move point.
2322: @item C-M-@@
2323: Set mark after end of next Lisp expression (@code{mark-sexp}).
2324: @item M-h
2325: Put region around current paragraph (@code{mark-paragraph}).
2326: @item C-M-h
2327: Put region around current Lisp defun (@code{mark-defun}).
2328: @item C-x h
2329: Put region around entire buffer (@code{mark-whole-buffer}).
2330: @item C-x C-p
2331: Put region around current page (@code{mark-page}).
2332: @end table
2333:
2334: For example, if you wish to convert part of the buffer to all upper-case,
2335: you can use the @kbd{C-x C-u} (@code{upcase-region}) command, which operates
2336: on the text in the region. You can first go to the beginning of the text
2337: to be capitalized, type @kbd{C-@key{SPC}} to put the mark there, move to
2338: the end, and then type @kbd{C-x C-u}. Or, you can set the mark at the end
2339: of the text, move to the beginning, and then type @kbd{C-x C-u}. Most
2340: commands that operate on the text in the region have the word @code{region}
2341: in their names.
2342:
2343: @kindex C-SPC
2344: @findex set-mark-command
2345: The most common way to set the mark is with the @kbd{C-@key{SPC}} command
2346: (@code{set-mark-command}). This sets the mark where point is. Then you
2347: can move point away, leaving the mark behind. It is actually incorrect to
2348: speak of the character @kbd{C-@key{SPC}}; there is no such character. When
2349: you type @key{SPC} while holding down @key{CTRL}, what you get on most
2350: terminals is the character @kbd{C-@@}. This is the key actually bound to
2351: @code{set-mark-command}. But unless you are unlucky enough to have a
2352: terminal where typing @kbd{C-@key{SPC}} does not produce @kbd{C-@@}, you
2353: might as well think of this character as @kbd{C-@key{SPC}}.
2354:
2355: @kindex C-x C-x
2356: @findex exchange-point-and-mark
2357: Since terminals have only one cursor, there is no way for Emacs to show
2358: you where the mark is located. You have to remember. The usual solution
2359: to this problem is to set the mark and then use it soon, before you forget
2360: where it is. But you can see where the mark is with the command @kbd{C-x
2361: C-x} (@code{exchange-point-and-mark}) which puts the mark where point was and
2362: point where the mark was. The extent of the region is unchanged, but the
2363: cursor and point are now at the previous location of the mark.
2364:
2365: @kbd{C-x C-x} is also useful when you are satisfied with the location of
2366: point but want to move the mark; do @kbd{C-x C-x} to put point there and
2367: then you can move it. A second use of @kbd{C-x C-x}, if necessary, puts
2368: the mark at the new location with point back at its original location.
2369:
2370: @section Operating on the Region
2371:
2372: Once you have created an active region, you can do many things to
2373: the text in it:
2374: @itemize @bullet
2375: @item
2376: Kill it with @kbd{C-w} (@pxref{Killing}).
2377: @item
2378: Save it in a register with @kbd{C-x x} (@pxref{Registers}).
2379: @item
2380: Save it in a buffer or a file (@pxref{Accumulating Text}).
2381: @item
2382: Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} @*(@pxref{Case}).
2383: @item
2384: Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
2385: @item
2386: Fill it as text with @kbd{M-g} (@pxref{Filling}).
2387: @item
2388: Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}).
2389: @item
2390: Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}).
2391: @end itemize
2392:
2393: @section Commands to Mark Textual Objects
2394:
2395: @kindex M-@@
2396: @kindex C-M-@@
2397: @findex mark-word
2398: @findex mark-sexp
2399: There are commands for placing the mark on the other side of a certain
2400: object such as a word or a list, without having to move there first.
2401: @kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next word,
2402: while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the next Lisp
2403: expression. These characters allow you to save a little typing or
2404: redisplay, sometimes.
2405:
2406: @kindex M-h
2407: @kindex C-M-h
2408: @kindex C-x C-p
2409: @kindex C-x h
2410: @findex mark-paragraph
2411: @findex mark-defun
2412: @findex mark-page
2413: @findex mark-whole-buffer
2414: Other commands set both point and mark, to delimit an object in the
2415: buffer. @kbd{M-h} (@code{mark-paragraph}) moves point to the beginning of
2416: the paragraph that surrounds or follows point, and puts the mark at the end
2417: of that paragraph (@pxref{Paragraphs}). @kbd{M-h} does all that's
2418: necessary if you wish to indent, case-convert, or kill a whole paragraph.
2419: @kbd{C-M-h} (@code{mark-defun}) similarly puts point before and the mark
2420: after the current or following defun (@pxref{Defuns}). @kbd{C-x C-p}
2421: (@code{mark-page}) puts point before the current page (or the next or
2422: previous, according to the argument), and mark at the end (@pxref{Pages}).
2423: The mark goes after the terminating page delimiter (to include it), while
2424: point goes after the preceding page delimiter (to exclude it). Finally,
2425: @kbd{C-x h} (@code{mark-whole}) sets up the entire buffer as the region, by
2426: putting point at the beginning and the mark at the end.
2427:
2428: @node Mark Ring,, Mark, Mark
2429: @section The Mark Ring
2430:
2431: @kindex C-u C-SPC
2432: @cindex mark ring
2433: @kindex C-u C-@@
2434: Aside from delimiting the region, the mark is also useful for remembering
2435: a spot that you may want to go back to. To make this feature more useful,
2436: Emacs remembers 16 previous locations of the mark, in the @code{mark ring}.
2437: Most commands that set the mark push the old mark onto this ring. To
2438: return to a marked location, use @kbd{C-u C-@@} (or @kbd{C-u C-@key{SPC}});
2439: this is the command @code{set-mark-command} given a numeric argument. This
2440: moves point to where the mark was, and restores the mark from the ring of
2441: former marks. So repeated use of this command moves point to all of the
2442: old marks on the ring, one by one. Enough uses of @kbd{C-u C-@@} bring
2443: point back to where it was originally.
2444:
2445: Each buffer has its own mark ring. All editing commands that use the
2446: mark ring use the current buffer's mark ring. In particular, @kbd{C-u
2447: C-@key{SPC}} always stays in the same buffer.
2448:
2449: Many commands that can move long distances, such as @kbd{M-<}
2450: (@code{beginning-of-buffer}), start by setting the mark and saving the old
2451: mark on the mark ring, just as a way of making it possible for you to move
2452: to where point was before the command. This is to make it easier for you
2453: to move back later. Searches do this except when they do not actually move
2454: point. You can tell when a command sets the mark because @samp{Mark Set}
2455: is printed in the echo area.
2456:
2457: @vindex mark-ring-max
2458: The variable @code{mark-ring-max} is the maximum number of entries to
2459: keep in the mark ring. If that many entries exist and another one is
2460: pushed, the last one in the list is discarded. Repeating @kbd{C-u
2461: C-@key{SPC}} circulates through the limited number of entries that are
2462: currently in the ring.
2463:
2464: @vindex mark-ring
2465: The variable @code{mark-ring} holds the mark ring itself, as a list of
2466: marker objects in the order most recent first.
2467:
2468: @iftex
2469: @chapter Killing and Moving Text
2470:
2471: @dfn{Killing} means erasing text and copying it into the @dfn{kill ring},
2472: from which it can be retrieved by @dfn{yanking} it.
2473:
2474: The commonest way of moving or copying text with Emacs is to kill it and
2475: later yank it in one or more places. This is very safe because all the
2476: text killed recently is remembered, and it is versatile, because the many
2477: commands for killing syntactic units can also be used for moving those
2478: units. There are also other ways of copying text for special purposes.
2479:
2480: Emacs has only one kill ring, so you can kill text in one buffer and yank
2481: it in another buffer.
2482:
2483: @end iftex
2484:
2485: @node Killing, Yanking, Mark, Top
2486: @section Deletion and Killing
2487: @findex delete-char
2488: @c ??? Should be backward-delete-char
2489: @findex delete-backward-char
2490:
2491: @cindex killing
2492: @cindex deletion
2493: @kindex C-d
2494: @kindex DEL
2495: Most commands which erase text from the buffer save it so that you can
2496: get it back if you change your mind, or move or copy it to other parts of
2497: the buffer. These commands are known as @dfn{kill} commands. The rest of
2498: the commands that erase text do not save it; they are known as @dfn{delete}
2499: commands. (This distinction is made only for erasure of text in the
2500: buffer.)
2501:
2502: The delete commands include @kbd{C-d} (@code{delete-char}) and
2503: @key{DEL} (@code{delete-backward-char}), which delete only one character at
2504: a time, and those commands that delete only spaces or newlines. Commands
2505: that can destroy significant amounts of nontrivial data generally kill.
2506: The commands' names and individual descriptions use the words @samp{kill}
2507: and @samp{delete} to say which they do. If you do a kill or delete command
2508: by mistake, you can use the @kbd{C-x u} (@code{undo}) command to undo it
2509: (@pxref{Undo}).@refill
2510:
2511: @subsection Deletion
2512:
2513: @table @kbd
2514: @item C-d
2515: Delete next character (@code{delete-char}).
2516: @item @key{DEL}
2517: Delete previous character (@code{delete-backward-char}).
2518: @item M-\
2519: Delete spaces and tabs around point (@code{delete-horizontal-space}).
2520: @item M-@key{SPC}
2521: Delete spaces and tabs around point, leaving one space
2522: (@code{just-one-space}).
2523: @item C-x C-o
2524: Delete blank lines around the current line (@code{delete-blank-lines}).
2525: @item M-^
2526: Join two lines by deleting the intervening newline, and any indentation
2527: following it (@code{delete-indentation}).
2528: @end table
2529:
2530: The most basic delete commands are @kbd{C-d} (@code{delete-char}) and
2531: @key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the character
2532: after point, the one the cursor is ``on top of''. Point doesn't move.
2533: @key{DEL} deletes the character before the cursor, and moves point back.
2534: Newlines can be deleted like any other characters in the buffer; deleting a
2535: newline joins two lines. Actually, @kbd{C-d} and @key{DEL} aren't always
2536: delete commands; if given an argument, they kill instead, since they can
2537: erase more than one character this way.
2538:
2539: @kindex M-\
2540: @findex delete-horizontal-space
2541: @kindex M-SPC
2542: @findex just-one-space
2543: @kindex C-x C-o
2544: @findex delete-blank-lines
2545: @kindex M-^
2546: @findex delete-indentation
2547: The other delete commands are those which delete only formatting
2548: characters: spaces, tabs and newlines. @kbd{M-\} (@code{delete-horizontal-space})
2549: deletes all the spaces and tab characters before and after point.
2550: @kbd{M-@key{SPC}} (@code{just-one-space}) does likewise but leaves a single
2551: space after point, regardless of the number of spaces that existed
2552: previously (even zero).
2553:
2554: @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines after
2555: the current line, and if the current line is blank deletes all blank lines
2556: preceding the current line as well (leaving one blank line, the current
2557: line). @kbd{M-^} (@code{delete-indentation}) joins the current line and
2558: the previous line, or the current line and the next line if given an
2559: argument, by deleting a newline and all surrounding spaces, possibly
2560: leaving a single space. @xref{Indentation,M-^}.
2561:
2562: @subsection Killing by Lines
2563:
2564: @table @kbd
2565: @item C-k
2566: Kill rest of line or one or more lines (@code{kill-line}).
2567: @end table
2568:
2569: @kindex C-k
2570: @findex kill-line
2571: The simplest kill command is @kbd{C-k}. If given at the beginning of a
2572: line, it kills all the text on the line, leaving it blank. If given on a
2573: blank line, the blank line disappears. As a consequence, if you go to the
2574: front of a non-blank line and type @kbd{C-k} twice, the line disappears
2575: completely.
2576:
2577: More generally, @kbd{C-k} kills from point up to the end of the line,
2578: unless it is at the end of a line. In that case it kills the newline
2579: following the line, thus merging the next line into the current one.
2580: Invisible spaces and tabs at the end of the line are ignored when deciding
2581: which case applies, so if point appears to be at the end of the line, you
2582: can be sure the newline will be killed.
2583:
2584: If @kbd{C-k} is given a positive argument, it kills that many lines and
2585: the newlines that follow them (however, text on the current line before
2586: point is spared). With a negative argument, it kills back to a number of
2587: line beginnings. An argument of -2 means kill back to the second line
2588: beginning. If point is at the beginning of a line, that line beginning
2589: doesn't count, so @kbd{C-u - 2 C-k} with point at the front of a line kills
2590: the two previous lines.
2591:
2592: @kbd{C-k} with an argument of zero kills all the text before point on the
2593: current line.
2594:
2595: @subsection Other Kill Commands
2596: @findex kill-line
2597: @findex kill-region
2598: @findex kill-word
2599: @findex backward-kill-word
2600: @findex kill-sexp
2601: @findex kill-sentence
2602: @findex backward-kill-sentence
2603: @kindex M-d
2604: @kindex M-DEL
2605: @kindex C-M-k
2606: @kindex C-x DEL
2607: @kindex M-k
2608: @kindex C-k
2609: @kindex C-w
2610:
2611: @c DoubleWideCommands
2612: @table @kbd
2613: @item C-w
2614: Kill region (from point to the mark) (@code{kill-region}).
2615: @item M-d
2616: Kill word (@code{kill-word}).
2617: @item M-@key{DEL}
2618: Kill word backwards (@code{backward-kill-word}).
2619: @item C-x @key{DEL}
2620: Kill back to beginning of sentence (@code{backward-kill-sentence}).
2621: @xref{Sentences}.
2622: @item M-k
2623: Kill to end of sentence (@code{kill-sentence}).
2624: @item C-M-k
2625: Kill sexp (@pxref{Lists}) (@code{kill-sexp}).
2626: @item M-z @var{char}
2627: Kill up to next occurrence of @var{char} (@code{zap-to-char}).
2628: @end table
2629:
2630: A kill command which is very general is @kbd{C-w} (@code{kill-region}),
2631: which kills everything between point and the mark. With this command, you
2632: can kill any contiguous sequence of characters, if you first set the mark
2633: at one end of them and go to the other end.
2634:
2635: @kindex M-z
2636: @findex zap-to-char
2637: A convenient way of killing is combined with searching: @kbd{M-z}
2638: (@code{zap-to-char}) reads a character and kills from point up to (but not
2639: including) the next occurrence of that character in the buffer. If there
2640: is no next occurrence, killing goes to the end of the buffer. A numeric
2641: argument acts as a repeat count. A negative argument means to search
2642: backward and kill text before point.
2643:
2644: Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and
2645: @kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and
2646: sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k}
2647: (@pxref{Sentences}).@refill
2648:
2649: @node Yanking, Accumulating Text, Killing, Top
2650: @section Yanking
2651: @cindex moving text
2652: @cindex kill ring
2653: @cindex yanking
2654:
2655: @dfn{Yanking} is getting back text which was killed. The usual way to
2656: move or copy text is to kill it and then yank it one or more times.
2657:
2658: @table @kbd
2659: @item C-y
2660: Yank last killed text (@code{yank}).
2661: @item M-y
2662: Replace re-inserted killed text with the previously killed text
2663: (@code{yank-pop}).
2664: @item M-w
2665: Save region as last killed text without actually killing it
2666: (@code{copy-region-as-kill}).
2667: @item C-M-w
2668: Append next kill to last batch of killed text (@code{append-next-kill}).
2669: @end table
2670:
2671: @kindex C-y
2672: @findex Yank
2673: All killed text is recorded in the @dfn{kill ring}, a list of blocks of
2674: text that have been killed. There is only one kill ring, used in all
2675: buffers, so you can kill text in one buffer and yank it in another buffer.
2676: This is the usual way to move text from one file to another.
2677: (@xref{Accumulating Text}, for some other ways.)
2678:
2679: The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent
2680: kill. It leaves the cursor at the end of the text. It sets the mark at
2681: the beginning of the text. @xref{Mark}.
2682:
2683: @kbd{C-u C-y} leaves the cursor in front of the text, and sets the mark
2684: after it. This is only if the argument is specified with just a @kbd{C-u},
2685: precisely. Any other sort of argument, including @kbd{C-u} and digits, has
2686: an effect described below (under ``Yanking Earlier Kills'').
2687:
2688: @kindex M-w
2689: @findex copy-region-as-kill
2690: If you wish to copy a block of text, you might want to use @kbd{M-w}
2691: (@code{copy-region-as-kill}), which copies the region into the kill ring
2692: without removing it from the buffer. This is approximately equivalent to
2693: @kbd{C-w} followed by @kbd{C-y}, except that @kbd{M-w} does not mark the
2694: buffer as ``modified'' and does not temporarily change the screen.
2695:
2696: @subsection Appending Kills
2697:
2698: Normally, each kill command pushes a new block onto the kill ring.
2699: However, two or more kill commands in a row combine their text into a
2700: single entry, so that a single @kbd{C-y} gets it all back as it was before
2701: it was killed. This means that you don't have to kill all the text in one
2702: command; you can keep killing line after line, or word after word, until
2703: you have killed it all, and you can still get it all back at once. (Thus
2704: we join television in leading people to kill thoughtlessly.)
2705:
2706: Commands that kill forward from point add onto the end of the previous
2707: killed text. Commands that kill backward from point add onto the
2708: beginning. This way, any sequence of mixed forward and backward kill
2709: commands puts all the killed text into one entry without rearrangement.
2710: Numeric arguments do not break the sequence of appending kills. For
2711: example, suppose the buffer contains
2712:
2713: @example
2714: This is the first
2715: line of sample text
2716: and here is the third.
2717: @end example
2718:
2719: @noindent
2720: with point at the beginning of the second line. If you type @kbd{C-k C-u 2
2721: M-@key{DEL} C-k}, the first @kbd{C-k} kills the text @samp{line of sample
2722: text}, @kbd{C-u 2 M-@key{DEL}} kills @samp{the first} with the newline that
2723: followed it, and the second @kbd{C-k} kills the newline after the second
2724: line. The result is that the buffer contains @samp{This is and here is the
2725: third.} and a single kill entry contains @samp{the first@key{RET}line of
2726: sample text@key{RET}}---all the killed text, in its original order.
2727:
2728: @kindex C-M-w
2729: @findex append-next-kill
2730: If a kill command is separated from the last kill command by other
2731: commands (not just numeric arguments), it starts a new entry on the kill
2732: ring. But you can force it to append by first typing the command
2733: @kbd{C-M-w} (@code{append-next-kill}) in front of it. The @kbd{C-M-w}
2734: tells the following command, if it is a kill command, to append the text it
2735: kills to the last killed text, instead of starting a new entry. With
2736: @kbd{C-M-w}, you can kill several separated pieces of text and accumulate
2737: them to be yanked back in one place.@refill
2738:
2739: @subsection Yanking Earlier Kills
2740:
2741: @kindex M-y
2742: @findex yank-pop
2743: To recover killed text that is no longer the most recent kill, you need
2744: the @kbd{Meta-y} (@code{yank-pop}) command. @kbd{M-y} can be used only
2745: after a @kbd{C-y} or another @kbd{M-y}. It takes the text previously
2746: yanked and replaces it with the text from an earlier kill. So, to recover
2747: the text of the next-to-the-last kill, you first use @kbd{C-y} to recover
2748: the last kill, and then use @kbd{M-y} to replace it with the previous
2749: kill.@refill
2750:
2751: You can think in terms of a ``last yank'' pointer which points at an item
2752: in the kill ring. Each time you kill, the ``last yank'' pointer moves to
2753: the newly made item at the front of the ring. @kbd{C-y} yanks the item
2754: which the ``last yank'' pointer points to. @kbd{M-y} moves the ``last
2755: yank'' pointer to a different item, and the text in the buffer changes to
2756: match. Enough @kbd{M-y} commands can move the pointer to any item in the
2757: ring, so you can get any item into the buffer. Eventually the pointer
2758: reaches the end of the ring; the next @kbd{M-y} moves it to the first item
2759: again.
2760:
2761: @kbd{M-y} can take a numeric argument, which tells it how many items to
2762: advance the ``last yank'' pointer by. A negative argument moves the
2763: pointer toward the front of the ring; from the front of the ring, it moves
2764: to the last entry and starts moving forward from there.
2765:
2766: Once the text you are looking for is brought into the buffer, you can
2767: stop doing @kbd{M-y} commands and it will stay there. It's just a copy of
2768: the kill ring item, so editing it in the buffer does not change what's in
2769: the ring. As long as no new killing is done, the ``last yank'' pointer
2770: remains at the same place in the kill ring, so repeating @kbd{C-y} will
2771: yank another copy of the same old kill.
2772:
2773: If you know how many @kbd{M-y} commands it would take to find the
2774: text you want, you can yank that text in one step using @kbd{C-y} with
2775: a numeric argument. @kbd{C-y} with an argument greater than one
2776: restores the text the specified number of entries back in the kill
2777: ring. Thus, @kbd{C-u 2 C-y} gets the next to the last block of killed
2778: text. It is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numeric
2779: argument starts counting from the ``last yank'' pointer, and sets the
2780: ``last yank'' pointer to the entry that it yanks.
2781:
2782: @vindex kill-ring-max
2783: The length of the kill ring is controlled by the variable
2784: @code{kill-ring-max}; no more than that many blocks of killed text are
2785: saved.
2786:
2787: @node Accumulating Text, Rectangles, Yanking, Top
2788: @section Accumulating Text
2789: @kindex C-x a
2790: @findex append-to-buffer
2791: @findex prepend-to-buffer
2792: @findex copy-to-buffer
2793: @findex append-to-file
2794:
2795: Usually we copy or move text by killing it and yanking it, but there are
2796: other ways that are useful for copying one block of text in many places, or
2797: for copying many scattered blocks of text into one place.
2798:
2799: You can accumulate blocks of text from scattered locations either into a
2800: buffer or into a file if you like. These commands are described here. You
2801: can also use Emacs registers for storing and accumulating text.
2802: @xref{Registers}.
2803:
2804: @table @kbd
2805: @item C-x a
2806: Append region to contents of specified buffer (@code{append-to-buffer}).
2807: @item M-x prepend-to-buffer
2808: Prepend region to contents of specified buffer.
2809: @item M-x copy-to-buffer
2810: Copy region into specified buffer, deleting that buffer's old contents.
2811: @item M-x insert-buffer
2812: Insert contents of specified buffer into current buffer at point.
2813: @item M-x append-to-file
2814: Append region to contents of specified file, at the end.
2815: @end table
2816:
2817: To accumulate text into a buffer, use the command @kbd{C-x a @var{buffername}}
2818: (@code{append-to-buffer}), which inserts a copy of the region into the
2819: buffer @var{buffername}, at the location of point in that buffer. If there
2820: is no buffer with that name, one is created. If you append text into a
2821: buffer which has been used for editing, the copied text goes into the
2822: middle of the text of the buffer, wherever point happens to be in it.
2823:
2824: Point in that buffer is left at the end of the copied text, so successive
2825: uses of @kbd{C-x a} accumulate the text in the specified buffer in the same
2826: order as they were copied. Strictly speaking, @kbd{C-x a} does not always
2827: append to the text already in the buffer; but if @kbd{C-x a} is the only
2828: command used to alter a buffer, it does always append to the existing text
2829: because point is always at the end.
2830:
2831: @kbd{M-x prepend-to-buffer} is just like @kbd{C-x a} except that point in
2832: the other buffer is left before the copied text, so successive prependings
2833: add text in reverse order. @kbd{M-x copy-to-buffer} is similar except that
2834: any existing text in the other buffer is deleted, so the buffer is left
2835: containing just the text newly copied into it.
2836:
2837: You can retrieve the accumulated text from that buffer with @kbd{M-x
2838: insert-buffer}; this too takes @var{buffername} as an argument. It inserts
2839: a copy of the text in buffer @var{buffername} into the selected buffer.
2840: You could alternatively select the other buffer for editing, perhaps moving
2841: text from it by killing or with @kbd{C-x a}. @xref{Buffers}, for
2842: background information on buffers.
2843:
2844: Instead of accumulating text within Emacs, in a buffer, you can append
2845: text directly into a file with @kbd{M-x append-to-file}, which takes
2846: @var{file-name} as an argument. It adds the text of the region to the end
2847: of the specified file. The file is changed immediately on disk. This
2848: command is normally used with files that are @i{not} being visited in
2849: Emacs. Using it on a file that Emacs is visiting can produce confusing
2850: results, because the text inside Emacs for that file will not change
2851: while the file itself changes.
2852:
2853: @node Rectangles, Registers, Accumulating Text, Top
2854: @section Rectangles
2855: @cindex rectangles
2856:
2857: The rectangle commands affect rectangular areas of the text: all the
2858: characters between a certain pair of columns, in a certain range of lines.
2859: Commands are provided to kill rectangles, yank killed rectangles, clear
2860: them out, or delete them. Rectangle commands are useful with text in
2861: multicolumnar formats, such as perhaps code with comments at the right,
2862: or for changing text into or out of such formats.
2863:
2864: When you must specify a rectangle for a command to work on, you do
2865: it by putting the mark at one corner and point at the opposite corner.
2866: The rectangle thus specified is called the @dfn{region-rectangle}
2867: because it is controlled about the same way the region is controlled.
2868: But remember that a given combination of point and mark values can be
2869: interpreted either as specifying a region or as specifying a
2870: rectangle; it is up to the command that uses them to choose the
2871: interpretation.
2872:
2873: @table @kbd
2874: @item M-x delete-rectangle
2875: Delete the text of the region-rectangle, moving any following text on
2876: each line leftward to the left edge of the region-rectangle.
2877: @item M-x kill-rectangle
2878: Similar, but also save the contents of the region-rectangle as the
2879: ``last killed rectangle''.
2880: @item M-x yank-rectangle
2881: Yank the last killed rectangle with its upper left corner at point.
2882: @item M-x open-rectangle
2883: Insert blank space to fill the space of the region-rectangle.
2884: The previous contents of the region-rectangle are pushed rightward.
2885: @item M-x clear-rectangle
2886: Clear the region-rectangle by replacing its contents with spaces.
2887: @end table
2888:
2889: The rectangle operations fall into two classes: commands deleting and
2890: moving rectangles, and commands for blank rectangles.
2891:
2892: @findex delete-rectangle
2893: @findex kill-rectangle
2894: There are two ways to delete a rectangle: you can discard its contents,
2895: or save them as the ``last killed'' rectangle. The commands for these
2896: two ways are @kbd{M-x delete-rectangle} and @kbd{M-x kill-rectangle}. In
2897: any case, the portion of each line that falls inside the rectangle's
2898: boundaries is deleted, causing following text (if any) on the line to move
2899: left.
2900:
2901: Note that ``killing'' a rectangle is not killing in the usual sense; the
2902: rectangle is not stored in the kill ring, but in a special place that
2903: can only record the most recent rectangle killed. This is because yanking
2904: a rectangle is so different from yanking linear text that different yank
2905: commands have to be used and yank-popping is hard to make sense of.
2906:
2907: Inserting a rectangle is the opposite of deleting one. All you need to
2908: specify is where to put the upper left corner; that is done by putting
2909: point there. The rectangle's first line is inserted there, the rectangle's
2910: second line is inserted at a point one line vertically down, and so on.
2911: The number of lines affected is determined by the height of the saved
2912: rectangle.
2913:
2914: @findex yank-rectangle
2915: To insert the last killed rectangle, type @kbd{M-x yank-rectangle}.
2916:
2917: @findex open-rectangle
2918: @findex clear-rectangle
2919: There are two commands for working with blank rectangles: @kbd{M-x
2920: clear-rectangle} to blank out existing text, and @kbd{M-x open-rectangle}
2921: to insert a blank rectangle. Clearing a rectangle is equivalent to
2922: deleting it and then inserting as blank rectangle of the same size.
2923:
2924: Rectangles can also be copied into and out of registers.
2925: @xref{RegRect,,Rectangle Registers}.
2926:
2927: @node Registers, Display, Rectangles, Top
2928: @chapter Registers
2929: @cindex registers
2930:
2931: Emacs @dfn{registers} are places you can save text or positions for
2932: later use. Text saved in a register can be copied into the buffer
2933: once or many times; a position saved in a register is used by moving
2934: point to that position. Rectangles can also be copied into and out of
2935: registers (@pxref{Rectangles}).
2936:
2937: Each register has a name, which is a single character. It can store
2938: either a piece of text or a position or a rectangle; only one of the three
2939: at any given time. Whatever you store in a register remains there until
2940: you store something else in that register.
2941:
2942: @menu
2943: * RegPos:: Saving positions in registers.
2944: * RegText:: Saving text in registers.
2945: * RegRect:: Saving rectangles in registers.
2946: @end menu
2947:
2948: @table @kbd
2949: @item M-x view-register @key{RET} @var{r}
2950: Display a description of what register @var{r} contains.
2951: @end table
2952:
2953: @findex view-register
2954: @kbd{M-x view-register} reads a register name as an argument and then
2955: displays the contents of the specified register.
2956:
2957: @node RegPos, RegText, Registers, Registers
2958: @section Saving Positions in Registers
2959:
2960: Saving a position records a spot in a buffer so that you can move
2961: back there later. Moving to a saved position reselects the buffer
2962: and moves point to the spot.
2963:
2964: @table @kbd
2965: @item C-x / @var{r}
2966: Save location of point in register @var{r} (@code{point-to-register}).
2967: @item C-x j @var{r}
2968: Jump to the location saved in register @var{r} (@code{register-to-point}).
2969: @end table
2970:
2971: @kindex C-x /
2972: @findex point-to-register
2973: To save the current location of point in a register, choose a name
2974: @var{r} and type @kbd{C-x / @var{r}}. The register @var{r} retains
2975: the location thus saved until you store something else in that
2976: register.@refill
2977:
2978: @kindex C-x j
2979: @findex register-to-point
2980: The command @kbd{C-x j @var{r}} moves point to the location recorded
2981: in register @var{r}. The register is not affected; it continues to
2982: record the same location. You can jump to the same position using the
2983: same register any number of times.
2984:
2985: @node RegText, RegRect, RegPos, Registers
2986: @section Saving Text in Registers
2987:
2988: When you want to insert a copy of the same piece of text frequently, it
2989: may be impractical to use the kill ring, since each subsequent kill moves
2990: the piece of text farther down on the ring. It becomes hard to keep track
2991: of what argument is needed to retrieve the same text with @kbd{C-y}. An
2992: alternative is to store the text in a register with @kbd{C-x x}
2993: (@code{copy-to-register}) and then retrieve it with @kbd{C-x g}
2994: (@code{insert-register}).
2995:
2996: @table @kbd
2997: @item C-x x @var{r}
2998: Copy region into register @var{r} (@code{copy-to-register}).
2999: @item C-x g @var{r}
3000: Insert text contents of register @var{r} (@code{insert-register}).
3001: @end table
3002:
3003: @kindex C-x x
3004: @kindex C-x g
3005: @findex copy-to-register
3006: @findex insert-register
3007: @kbd{C-x x @var{r}} stores a copy of the text of the region into the
3008: register named @var{r}. Given a numeric argument, @kbd{C-x x} deletes the
3009: text from the buffer as well.
3010:
3011: @kbd{C-x g @var{r}} inserts in the buffer the text from register @var{r}.
3012: Normally it leaves point before the text and places the mark after, but
3013: with a numeric argument it puts point after the text and the mark before.
3014:
3015: @node RegRect,, RegText, Registers
3016: @section Saving Rectangles in Registers
3017: @cindex rectangle
3018:
3019: A register can contain a rectangle instead of linear text. The rectangle
3020: is represented as a list of strings. @xref{Rectangles}, for basic
3021: information on rectangles and how rectangles in the buffer are specified.
3022:
3023: @table @kbd
3024: @item C-x r @var{r}
3025: Copy the region-rectangle into register @var{r} @*(@code{copy-region-to-rectangle}).
3026: With numeric argument, delete it as well.
3027: @item C-x g @var{r}
3028: Insert the rectangle stored in register @var{r} (if it contains a
3029: rectangle) (@code{insert-register}).
3030: @end table
3031:
3032: The @kbd{C-x g} command inserts linear text if the register contains
3033: that, or inserts a rectangle if the register contains one.
3034:
3035: @node Display, Search, Registers, Top
3036: @chapter Controlling the Display
3037: @cindex scrolling
3038:
3039: Since only part of a large buffer fits in the window, Emacs tries to show
3040: the part that is likely to be interesting. The display control commands
3041: allow you to ask to see a different part of the text. This is also known
3042: as @dfn{scrolling}.
3043:
3044: If a buffer contains text that is too large to fit entirely within a
3045: window that is displaying the buffer, Emacs shows a contiguous section of
3046: the text. The section shown always contains point. As you change the
3047: text, Emacs always tries to keep the same position in the text at the top
3048: of the window. A new position moves to the top of the window only if this
3049: is necessary to keep point visible, or if you request it explicitly with a
3050: display control command.
3051:
3052: @table @kbd
3053: @item C-l
3054: Clear screen and redisplay, scrolling the selected window to center
3055: point vertically within it (@code{recenter}).
3056: @item C-v
3057: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
3058: @item M-v
3059: Scroll backward (@code{scroll-down}).
3060: @item C-x <
3061: Scroll text in current window to the left (@code{scroll-left}).
3062: @item C-x >
3063: Scroll to the right (@code{scroll-right}).
3064: @item M-r
3065: Move point to the text at a given vertical position within the window
3066: (@code{move-to-window-line}).
3067: @item C-x $
3068: Make deeply indented lines invisible (@code{set-selective-display}).
3069: @end table
3070:
3071: @kindex C-l
3072: @findex recenter
3073: The basic display control command is @kbd{C-l} (@code{recenter}). In its
3074: simplest form, with no argument, it clears the entire screen and redisplays
3075: all windows, scrolling the selected window so that point is halfway down
3076: from the top of the window. Other windows are cleared and redisplayed, but
3077: not scrolled.
3078:
3079: @kbd{C-l} with a numeric argument does not clear the screen; it does
3080: nothing except scroll the selected window as specified by the argument.
3081: With a positive argument @var{n}, it repositions text to put point @var{n}
3082: lines down from the top. An argument of zero puts point on the very top
3083: line. Point does not move with respect to the text; rather, the text and
3084: point move rigidly on the screen. @kbd{C-l} with a negative argument puts
3085: point that many lines from the bottom of the window. For example, @kbd{C-u
3086: - 1 C-l} puts point on the bottom line, and @kbd{C-u - 5 C-l} puts it five
3087: lines from the bottom.
3088:
3089: @kindex C-v
3090: @kindex M-v
3091: @findex scroll-up
3092: @findex scroll-down
3093: The @dfn{scrolling} commands @kbd{C-v} and @kbd{M-v} let you move the
3094: whole display up or down a few lines. @kbd{C-v} (@code{scroll-up}) with an
3095: argument shows you that many more lines at the bottom of the window, moving
3096: the text and point up together as @kbd{C-l} might. @kbd{C-v} with a
3097: negative argument shows you more lines at the top of the window.
3098: @kbd{Meta-v} (@code{scroll-down}) is like @kbd{C-v}, but moves in the
3099: opposite direction.@refill
3100:
3101: @vindex next-screen-context-lines
3102: To read the buffer a windowful at a time, use @kbd{C-v} with no argument.
3103: It takes the last two lines at the bottom of the window and puts them at
3104: the top, followed by nearly a whole windowful of lines not previously
3105: visible. If point was in the text scrolled off the top, it moves to the
3106: new top of the window. @kbd{M-v} with no argument moves backward with
3107: overlap similarly. The number of lines of overlap across a @kbd{C-v} or
3108: @kbd{M-v} is controlled by the variable @code{next-screen-context-lines}; by
3109: default, it is two.
3110:
3111: @vindex scroll-step
3112: Scrolling happens automatically if point has moved out of the visible
3113: portion of the text when it is time to display. Usually the scrolling is
3114: done so as to put point vertically centered within the window. However, if
3115: the variable @code{scroll-step} has a nonzero value, an attempt is made to
3116: scroll the buffer by that many lines; if that is enough to bring point back
3117: into visibility, that is what is done.
3118:
3119: @kindex C-x <
3120: @kindex C-x >
3121: @findex scroll-left
3122: @findex scroll-right
3123: @cindex horizontal scrolling
3124: The text in a window can also be scrolled horizontally. This means that
3125: each line of text is shifted sideways in the window, and one or more
3126: characters at the beginning of each line are not displayed at all. When a
3127: window has been scrolled horizontally in this way, text lines are truncated
3128: rather than continued (@pxref{Continuation Lines}), with a @samp{$} appearing
3129: in the first column when there is text truncated to the left, and in the
3130: last column when there is text truncated to the right.
3131:
3132: The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected window
3133: to the left by @var{n} columns with argument @var{n}. With no argument, it scrolls
3134: by almost the full width of the window (two columns less, to be precise).
3135: @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right.
3136: The window cannot be scrolled any farther to the right once it is
3137: displaying normally (with each line starting at the window's left margin);
3138: attempting to do so has no effect.
3139:
3140: @kindex M-r
3141: @findex move-to-window-line
3142: The commands described above all change the position of point on the
3143: screen, carrying the text with it. Another command moves point the same
3144: way but leaves the text fixed. It is @kbd{Meta-r} (@code{move-to-window-line}).
3145: With no argument, it puts point at the beginning of the line at the center
3146: of the window. An argument is used to specify the line to put point on,
3147: counting from the top if the argument is positive, or from the bottom if it
3148: is negative. Thus, @kbd{M-0 M-r} moves point to the text at the top of the
3149: window. @kbd{Meta-r} never causes any text to move on the screen; it
3150: causes point to move with respect to the screen and the text.
3151:
3152: @menu
3153: * Selective Display:: Hiding lines with lots of indentation.
3154: * Display Vars:: Information on variables for customizing display.
3155: @end menu
3156:
3157: @node Selective Display, Display Vars, Display, Display
3158: @section Selective Display
3159: @findex set-selective-display
3160: @kindex C-x $
3161:
3162: Emacs has the ability to hide lines indented more than a certain number
3163: of columns (you specify how many columns). You can use this to get an
3164: overview of a part of a program.
3165:
3166: To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a
3167: numeric argument @var{n}. (@xref{Arguments}, for how to give the
3168: argument.) Then lines with at least @var{n} columns of indentation
3169: disappear from the screen. The only indication of their presence is that
3170: three dots (@samp{@dots{}}) appear at the end of each visible line that is
3171: followed by one or more invisible ones.@refill
3172:
3173: The invisible lines are still present in the buffer, and most editing
3174: commands see them as usual, so it is very easy to put point in the middle
3175: of invisible text. When this happens, the cursor appears at the end of the
3176: previous line, after the three dots. If point is at the end of the visible
3177: line, before the newline that ends it, the cursor appears before the three
3178: dots.
3179:
3180: The commands @kbd{C-n} and @kbd{C-p} move across the invisible lines as if they
3181: were not there.
3182:
3183: To make everything visible again, type @kbd{C-x $} with no argument.
3184:
3185: @node Display Vars,, Selective Display, Display
3186: @section Variables Controlling Display
3187:
3188: This section contains information for customization only. Beginning
3189: users should skip it.
3190:
3191: @vindex mode-line-inverse-video
3192: The variable @code{mode-line-inverse-video} controls whether the mode
3193: line is displayed in inverse video (assuming the terminal supports it);
3194: @code{nil} means don't do so. @xref{Mode Line}.
3195:
3196: @vindex inverse-video
3197: If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
3198: to invert all the lines of the display from what they normally are.
3199:
3200: @vindex visible-bell
3201: If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
3202: to make the whole screen blink when it would normally make an audible bell
3203: sound. This variable has no effect if your terminal does not have a way
3204: to make the screen blink.@refill
3205:
3206: @vindex echo-keystrokes
3207: The variable @code{echo-keystrokes} controls the echoing of multi-character
3208: keys; its value is the number of seconds of pause required to cause echoing
3209: to start, or zero meaning don't echo at all. @xref{Echo Area}.
3210:
3211: @vindex ctl-arrow
3212: @vindex default-ctl-arrow
3213: If the variable @code{ctl-arrow} is @code{nil}, control characters in the buffer
3214: are displayed with octal escape sequences, all except newline and tab.
3215: This variable has a separate value in each buffer; in new buffers, its
3216: value is initialized from the variable @code{default-ctl-arrow}.
3217:
3218: @vindex tab-width
3219: @vindex default-tab-width
3220: Normally, a tab character in the buffer is displayed as whitespace which
3221: extends to the next display tab stop position, and display tab stops come
3222: at intervals equal to eight spaces. The number of spaces per tab is
3223: controlled by the variable @code{tab-width}, which is local to every
3224: buffer just like @code{ctl-arrow} and gets its value in a new buffer from
3225: @code{default-tab-width}. Note that how the tab character in the buffer is
3226: displayed has nothing to do with the definition of @key{TAB} as a command.
3227:
3228: @node Search, Fixit, Display, Top
3229: @chapter Searching and Replacement
3230: @cindex searching
3231:
3232: Like other editors, Emacs has commands for searching for occurrences of
3233: a string. The principal search command is unusual in that it is
3234: @dfn{incremental}; it begins to search before you have finished typing the
3235: search string. There are also nonincremental search commands more like
3236: those of other editors.
3237:
3238: Besides the usual @code{replace-string} command that finds all
3239: occurrences of one string and replaces them with another, Emacs has a fancy
3240: replacement command called @code{query-replace} which asks interactively
3241: which occurrences to replace.
3242:
3243: @menu
3244: * Incremental Search:: Search happens as you type the string.
3245: * Nonincremental Search:: Specify entire string and then search.
3246: * Word Search:: Search for sequence of words.
3247: * Regexp Search:: Search for match for a regexp.
3248: * Regexps:: Syntax of regular expressions.
3249: * Search Case:: To ignore case while searching, or not.
3250: * Replace:: Search, and replace some or all matches.
3251: * Other Repeating Search:: Operating on all matches for some regexp.
3252: @end menu
3253:
3254: @node Incremental Search, Nonincremental Search, Search, Search
3255: @section Incremental Search
3256:
3257: An incremental search begins searching as soon as you type the first
3258: character of the search string. As you type in the search string, Emacs
3259: shows you where the string (as you have typed it so far) would be found.
3260: When you have typed enough characters to identify the place you want, you
3261: can stop. Depending on what you will do next, you may or may not need to
3262: terminate the search explicitly with an @key{ESC} first.
3263:
3264: @c WideCommands
3265: @table @kbd
3266: @item C-s
3267: Incremental search forward (@code{isearch-forward}).
3268: @item C-r
3269: Incremental search backward (@code{isearch-backward}).
3270: @end table
3271:
3272: @kindex C-s
3273: @kindex C-r
3274: @findex isearch-forward
3275: @findex isearch-backward
3276: @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from
3277: the keyboard and positions the cursor at the first occurrence of the
3278: characters that you have typed. If you type @kbd{C-s} and then @kbd{F},
3279: the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see
3280: the cursor move to after the first @samp{FO}. After another @kbd{O}, the
3281: cursor is after the first @samp{FOO} after the place where you started the
3282: search. Meanwhile, the search string @samp{FOO} has been echoed in the
3283: echo area.@refill
3284:
3285: The echo area display ends with three dots when actual searching is going
3286: on. When search is waiting for more input, the three dots are removed.
3287: (On slow terminals, the three dots are not displayed.)
3288:
3289: If you make a mistake in typing the search string, you can erase
3290: characters with @key{DEL}. Each @key{DEL} cancels the last character of
3291: search string. This does not happen until Emacs is ready to read another
3292: input character; first it must either find, or fail to find, the character
3293: you want to erase. If you do not want to wait for this to happen, use
3294: @kbd{C-g} as described below.@refill
3295:
3296: When you are satisfied with the place you have reached, you can type
3297: @key{ESC}, which stops searching, leaving the cursor where the search
3298: brought it. Also, any command not specially meaningful in searches stops
3299: the searching and is then executed. Thus, typing @kbd{C-a} would exit the
3300: search and then move to the beginning of the line. @key{ESC} is necessary
3301: only if the next command you want to type is a printing character,
3302: @key{DEL}, @key{ESC}, or another control character that is special within
3303: searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s} or @kbd{C-k}).
3304:
3305: Sometimes you search for @samp{FOO} and find it, but not the one you
3306: expected to find. There was a second @samp{FOO} that you forgot about,
3307: before the one you were looking for. In this event, type another @kbd{C-s}
3308: to move to the next occurrence of the search string. This can be done any
3309: number of times. If you overshoot, you can cancel some @kbd{C-s}
3310: characters with @key{DEL}.
3311:
3312: After you exit a search, you can search for the same string again by
3313: typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
3314: incremental search, and the second @kbd{C-s} means ``search again''.
3315:
3316: If your string is not found at all, the echo area says @samp{Failing
3317: I-Search}. The cursor is after the place where Emacs found as much of your
3318: string as it could. Thus, if you search for @samp{FOOT}, and there is no
3319: @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
3320: At this point there are several things you can do. If your string was
3321: mistyped, you can rub some of it out and correct it. If you like the place
3322: you have found, you can type @key{ESC} or some other Emacs command to
3323: ``accept what the search offered''. Or you can type @kbd{C-g}, which
3324: removes from the search string the characters that could not be found (the
3325: @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
3326: @samp{FOOT}). A second @kbd{C-g} at that point cancels the search
3327: entirely, returning point to where it was when the search started.
3328:
3329: @cindex quitting (in search)
3330: The @kbd{C-g} ``quit'' character does special things during searches;
3331: just what it does depends on the status of the search. If the search has
3332: found what you specified and is waiting for input, @kbd{C-g} cancels the
3333: entire search. The cursor moves back to where you started the search. If
3334: @kbd{C-g} is typed when there are characters in the search string that have
3335: not been found---because Emacs is still searching for them, or because it
3336: has failed to find them---then the search string characters which have not
3337: been found are discarded from the search string. With them gone, the
3338: search is now successful and waiting for more input, so a second @kbd{C-g}
3339: will cancel the entire search.
3340:
3341: To search for a control character such as @kbd{C-s} or @key{DEL} or @key{ESC},
3342: you must quote it by typing @kbd{C-q} first. This function of @kbd{C-q} is
3343: analogous to its meaning as an Emacs command: it causes the following
3344: character to be treated the way a graphic character would normally be
3345: treated in the same context.
3346:
3347: You can change to searching backwards with @kbd{C-r}. If a search fails
3348: because the place you started was too late in the file, you should do this.
3349: Repeated @kbd{C-r} keeps looking for more occurrences backwards. A
3350: @kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be cancelled
3351: with @key{DEL}.
3352:
3353: If you know initially that you want to search backwards, you can
3354: use @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r}
3355: is also a key running a command (@code{isearch-reverse}) to search
3356: backward.
3357:
3358: The characters @kbd{C-y} and @kbd{C-w} can be used in incremental search
3359: to grab text from the buffer into the search string. This makes it
3360: convenient to search for another occurrence of text at point. @kbd{C-w}
3361: copies the word after point as part of the search string, advancing
3362: point over that word. Another @kbd{C-s} to repeat the search will then
3363: search for a string including that word. @kbd{C-y} is similar to @kbd{C-w}
3364: but copies all the rest of the current line into the search string.
3365:
3366: All the characters special in incremental search can be changed by setting
3367: the following variables:
3368:
3369: @vindex search-delete-char
3370: @vindex search-exit-char
3371: @vindex search-quote-char
3372: @vindex search-repeat-char
3373: @vindex search-reverse-char
3374: @vindex search-yank-line-char
3375: @vindex search-yank-word-char
3376: @table @code
3377: @item search-delete-char
3378: Character to delete from incremental search string (normally @key{DEL}).
3379: @item search-exit-char
3380: Character to exit incremental search (normally @key{ESC}).
3381: @item search-quote-char
3382: Character to quote special characters for incremental search (normally
3383: @kbd{C-q}).
3384: @item search-repeat-char
3385: Character to repeat incremental search forwards (normally @kbd{C-s}).
3386: @item search-reverse-char
3387: Character to repeat incremental search backwards (normally @kbd{C-r}).
3388: @item search-yank-line-char
3389: Character to pull rest of line from buffer into search string
3390: (normally @kbd{C-y}).
3391: @item search-yank-word-char
3392: Character to pull next word from buffer into search string (normally
3393: @kbd{C-w}).
3394: @end table
3395:
3396: @subsection Slow Terminal Incremental Search
3397:
3398: Incremental search on a slow terminal uses a modified style of display
3399: that is designed to take less time. Instead of redisplaying the buffer at
3400: each place the search gets to, it creates a new single-line window and uses
3401: that to display the line that the search has found. The single-line window
3402: comes into play as soon as point gets outside of the text that is already
3403: on the screen.
3404:
3405: When the search is terminated, the single-line window is removed. Only
3406: at this time is the window in which the search was done redisplayed to show
3407: its new value of point.
3408:
3409: The three dots at the end of the search string, normally used to indicate
3410: that searching is going on, are not displayed in slow style display.
3411:
3412: @vindex isearch-slow-speed
3413: The slow terminal style of display is used when the terminal baud rate is
3414: less than or equal to the value of the variable @code{isearch-slow-speed},
3415: initially 1200.
3416:
3417: @node Nonincremental Search, Word Search, Incremental Search, Search
3418: @section Nonincremental Search
3419: @cindex nonincremental search
3420:
3421: Emacs also has conventional nonincremental search commands, which require
3422: you to type the entire search string before searching begins.
3423:
3424: @table @kbd
3425: @item C-s @key{ESC} @var{string} @key{RET}
3426: Search for @var{string}.
3427: @item C-r @key{ESC} @var{string} @key{RET}
3428: Search backward for @var{string}.
3429: @end table
3430:
3431: To do a nonincremental search, first type @kbd{C-s @key{ESC}}. This
3432: enters the minibuffer to read the search string; terminate the string with
3433: @key{RET}, and then the search is done. If the string is not found the
3434: search command gets an error.
3435:
3436: The way @kbd{C-s @key{ESC}} works is that the @kbd{C-s} invokes
3437: incremental search, which is specially programmed to invoke nonincremental
3438: search if the argument you give it is empty. (Such an empty argument would
3439: otherwise be useless.) @kbd{C-r @key{ESC}} also works this way.
3440:
3441: @findex search-forward
3442: @findex search-backward
3443: Forward and backward nonincremental searches are implemented by the
3444: commands @code{search-forward} and @code{search-backward}. These commands
3445: may be bound to keys in the usual manner. The reason that they are reached
3446: by special-case code in incremental search is because @kbd{C-s @key{ESC}}
3447: is the traditional sequence of characters used in Emacs to invoke
3448: nonincremental search.
3449:
3450: However, nonincremental searches performed using @kbd{C-s @key{ESC}} do
3451: not call @code{search-forward} right away. The first thing done is to see
3452: if the next character is @kbd{C-w}, which requests a word search.
3453: @ifinfo
3454: @xref{Word Search}.
3455: @end ifinfo
3456:
3457: @node Word Search, Regexp Search, Nonincremental Search, Search
3458: @section Word Search
3459: @cindex word search
3460:
3461: Word search searches for a sequence of words without regard to how the
3462: words are separated. More precisely, you type a string of many words,
3463: using single spaces to separate them, and the string can be found even if
3464: there are multiple spaces, newlines or other punctuation between the words.
3465:
3466: Word search is useful in editing documents formatted by text formatters.
3467: If you edit while looking at the printed, formatted version, you can't tell
3468: where the line breaks are in the source file. With word search, you can
3469: search without having to know them.
3470:
3471: @table @kbd
3472: @item C-s @key{ESC} C-w @var{words} @key{RET}
3473: Search for @var{words}, ignoring differences in punctuation.
3474: @item C-r @key{ESC} C-w @var{words} @key{RET}
3475: Search backward for @var{words}, ignoring differences in punctuation.
3476: @end table
3477:
3478: Word search is a special case of nonincremental search and is invoked
3479: with @kbd{C-s @key{ESC} C-w}. This is followed by the search string, which
3480: must always be terminated with @key{RET}. Being nonincremental, this
3481: search does not start until the argument is terminated. It works by
3482: constructing a regular expression and searching for that. @xref{Regexp
3483: Search}.
3484:
3485: A backward word search can be done by @kbd{C-r @key{ESC} C-w}.
3486:
3487: @findex word-search-forward
3488: @findex word-search-backward
3489: Forward and backward word searches are implemented by the commands
3490: @code{word-search-forward} and @code{word-search-backward}. These commands
3491: may be bound to keys in the usual manner. The reason that they are reached
3492: by special-case code in incremental and nonincremental search is because
3493: @kbd{C-s @key{ESC} C-w} is the traditional Emacs sequence of keys to use to
3494: do a word search.
3495:
3496: @node Regexp Search, Regexps, Word Search, Search
3497: @section Regular Expression Search
3498: @cindex regular expression
3499: @cindex regexp
3500:
3501: A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
3502: denotes a set of strings, possibly an infinite set. Searching for matches
3503: for a regexp is a very powerful operation that editors on Unix systems have
3504: traditionally offered. In GNU Emacs, you can search for the next match for
3505: a regexp either incrementally or not.
3506:
3507: @kindex C-M-s
3508: @findex isearch-forward-regexp
3509: Incremental search for a regexp is done by typing @kbd{C-M-s}
3510: (@code{isearch-forward-regexp}). This command reads a search string
3511: incrementally just like @kbd{C-s}, but it treats the search string as a
3512: regexp rather than looking for an exact match against the text in the
3513: buffer. Each time you add text to the search string, you make the regexp
3514: longer, and the new regexp is searched for.
3515:
3516: Note that adding characters to the regexp in an incremental regexp search
3517: does not make the cursor move back and start again. Perhaps it ought to; I
3518: am not sure. As it stands, if you have searched for @samp{foo} and you
3519: add @samp{\|bar}, the search will not check for a @samp{bar} in the
3520: buffer before the @samp{foo}.
3521:
3522: @findex re-search-forward
3523: @findex re-search-backward
3524: Nonincremental search for a regexp is done by the functions
3525: @code{re-search-forward} and @code{re-search-backward}. You can invoke
3526: these with @kbd{M-x}, or bind them to keys. Also, you can call
3527: @code{re-search-forward} by way of incremental regexp search with
3528: @kbd{C-M-s @key{ESC}}.
3529:
3530: @node Regexps, Search Case, Regexp Search, Search
3531: @section Syntax of Regular Expressions
3532:
3533: Regular expressions have a syntax in which a few characters are special
3534: constructs and the rest are @dfn{ordinary}. An ordinary character is a
3535: simple regular expression which matches that character and nothing else.
3536: The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*},
3537: @samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}. Any other character
3538: appearing in a regular expression is ordinary, unless a @samp{\} precedes
3539: it.@refill
3540:
3541: No new special characters will ever be defined. All extensions to the
3542: regular expression syntax are made by defining new two-character
3543: constructs that begin with @samp{\}.
3544:
3545: For example, @samp{f} is not a special character, so it is ordinary, and
3546: therefore @samp{f} is a regular expression that matches the string @samp{f}
3547: and no other string. (It does @i{not} match the string @samp{ff}.) Likewise,
3548: @samp{o} is a regular expression that matches only @samp{o}.@refill
3549:
3550: Any two regular expressions @var{a} and @var{b} can be concatenated. The
3551: result is a regular expression which matches a string if @var{a} matches
3552: some amount of the beginning of that string and @var{b} matches the rest of
3553: the string.@refill
3554:
3555: As a simple example, we can concatenate the regular expressions @samp{f}
3556: and @samp{o} to get the regular expression @samp{fo}, which matches only
3557: the string @samp{fo}. Still trivial. To do something nontrivial, you
3558: need to use one of the special characters. Here is a list of them.
3559:
3560: @table @kbd
3561: @item .
3562: is a special character that matches anything except a newline. Using
3563: concatenation, we can make regular expressions like @samp{a.b} which
3564: matches any three-character string which begins with @samp{a} and ends
3565: with @samp{b}.@refill
3566:
3567: @item *
3568: is not a construct by itself; it is a suffix, which means the
3569: preceding regular expression is to be repeated as many times as
3570: possible. In @samp{fo*}, the @samp{*} applies to the @samp{o}, so
3571: @samp{fo*} matches @samp{f} followed by any number of @samp{o}s. The
3572: case of zero @samp{o}s is allowed: @samp{fo*} does match @samp{f}.@refill
3573:
3574: @samp{*} always applies to the @i{smallest} possible preceding expression.
3575: Thus, @samp{fo*} has a repeating @samp{o}, not a repeating @samp{fo}.@refill
3576:
3577: The matcher processes a @samp{*} construct by matching, immediately,
3578: as many repetitions as can be found. Then it continues with the rest
3579: of the pattern. If that fails, backtracking occurs, discarding some
3580: of the matches of the @samp{*}-modified construct in case that makes
3581: it possible to match the rest of the pattern. For example, matching
3582: @samp{c[ad]*ar} against the string @samp{caddaar}, the @samp{[ad]*}
3583: first matches @samp{addaa}, but this does not allow the next @samp{a}
3584: in the pattern to match. So the last of the matches of @samp{[ad]} is
3585: undone and the following @samp{a} is tried again. Now it
3586: succeeds.@refill
3587:
3588: @item +
3589: Is a suffix character similar to @samp{*} except that it requires that
3590: the preceding expression be matched at least once. So, for example,
3591: @samp{c[ad]+r} will match the strings @samp{car} and @samp{caaadar}
3592: but not the string @samp{cr}, whereas @samp{c[ad]*r} would match all
3593: three strings.@refill
3594:
3595: @item ?
3596: Is a suffix character similar to @samp{*} except that it can match the
3597: preceding expression either once or not at all. For example,
3598: @samp{c[ad]?r} will match @samp{car}, @samp{cdr} or @samp{cr}; nothing else.
3599:
3600: @item [ ... ]
3601: @samp{[} begins a @dfn{character set}, which is terminated by a
3602: @samp{]}. In the simplest case, the characters between the two form
3603: the set. Thus, @samp{[ad]} matches either @samp{a} or @samp{d}, and
3604: @samp{[ad]*} matches any string of @samp{a} and @samp{d} (including
3605: the empty string), from which it follows that @samp{c[ad]*r} matches
3606: @samp{car}, etc.@refill
3607:
3608: Character ranges can also be included in a character set, by writing
3609: two characters with a @samp{-} between them. Thus, @samp{[a-z]}
3610: matches any lower-case letter. Ranges may be intermixed freely with
3611: individual characters, as in @samp{[a-z$%.]}, which matches any lower
3612: case letter or @samp{$}, @samp{%} or period.@refill
3613:
3614: Note that the usual special characters are not special any more inside
3615: a character set. A completely different set of special characters
3616: exists inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
3617:
3618: To include a @samp{]} in a character set, you must make it the first
3619: character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
3620: include a @samp{-}, write @samp{---}, which is a range containing only
3621: @samp{-}. To include @samp{^}, make it other than the first character
3622: in the set.@refill
3623:
3624: @item [^ ... ]
3625: @samp{[^} begins a @dfn{complement character set}, which matches any
3626: character except the ones specified. Thus, @samp{[^a-z0-9A-Z]}
3627: matches all characters @i{except} letters and digits.@refill
3628:
3629: @samp{^} is not special in a character set unless it is the first
3630: character. The character following the @samp{^} is treated as if it
3631: were first (it may be a @samp{-} or a @samp{]}).
3632:
3633: Note that a complement character set can match a newline, unless
3634: newline is mentioned as one of the characters not to match.
3635:
3636: @item ^
3637: is a special character that matches the empty string, but only if at
3638: the beginning of a line in the text being matched. Otherwise it fails
3639: to match anything. Thus, @samp{^foo} matches a @samp{foo} which occurs
3640: at the beginning of a line.
3641:
3642: @item $
3643: is similar to @samp{^} but matches only at the end of a line. Thus,
3644: @samp{xx*$} matches a string of one @samp{x} or more at the end of a line.
3645:
3646: @item \
3647: has two functions: it quotes the special characters (including
3648: @samp{\}), and it introduces additional special constructs.
3649:
3650: Because @samp{\} quotes special characters, @samp{\$} is a regular
3651: expression which matches only @samp{$}, and @samp{\[} is a regular
3652: expression which matches only @samp{[}, and so on.@refill
3653: @end table
3654:
3655: Note: for historical compatibility, special characters are treated as
3656: ordinary ones if they are in contexts where their special meanings make no
3657: sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is
3658: no preceding expression on which the @samp{*} can act. It is poor practice
3659: to depend on this behavior; better to quote the special character anyway,
3660: regardless of where is appears.@refill
3661:
3662: For the most part, @samp{\} followed by any character matches only
3663: that character. However, there are several exceptions: characters
3664: which, when preceded by @samp{\}, are special constructs. Such
3665: characters are always ordinary when encountered on their own.
3666:
3667: @table @kbd
3668: @item \|
3669: specifies an alternative.
3670: Two regular expressions @var{a} and @var{b} with @samp{\|} in
3671: between form an expression that matches anything that either @var{a} or
3672: @var{b} will match.@refill
3673:
3674: Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
3675: but no other string.@refill
3676:
3677: @samp{\|} applies to the largest possible surrounding expressions. Only a
3678: surrounding @samp{\( ... \)} grouping can limit the grouping power of
3679: @samp{\|}.@refill
3680:
3681: Full backtracking capability exists to handle multiple uses of @samp{\|}.
3682:
3683: @item \( ... \)
3684: is a grouping construct that serves three purposes:
3685:
3686: @enumerate
3687: @item
3688: To enclose a set of @samp{\|} alternatives for other operations.
3689: Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
3690:
3691: @item
3692: To enclose a complicated expression for the postfix @samp{*} to operate on.
3693: Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any (zero or
3694: more) number of @samp{na} strings.@refill
3695:
3696: @item
3697: To mark a matched substring for future reference.
3698:
3699: @end enumerate
3700:
3701: This last application is not a consequence of the idea of a
3702: parenthetical grouping; it is a separate feature which happens to be
3703: assigned as a second meaning to the same @samp{\( ... \)} construct
3704: because there is no conflict in practice between the two meanings.
3705: Here is an explanation of this feature:
3706:
3707: @item \@var{digit}
3708: after the end of a @samp{\( ... \)} construct, the matcher remembers the
3709: beginning and end of the text matched by that construct. Then, later on
3710: in the regular expression, you can use @samp{\} followed by @var{digit}
3711: to mean ``match the same text matched the @var{digit}'th time by the
3712: @samp{\( ... \)} construct.''@refill
3713:
3714: The strings matching the first nine @samp{\( ... \)} constructs
3715: appearing in a regular expression are assigned numbers 1 through 9 in
3716: order of their beginnings. @samp{\1} through @samp{\9} may be used to
3717: refer to the text matched by the corresponding @samp{\( ... \)}
3718: construct.
3719:
3720: For example, @samp{\(.*\)\1} matches any newline-free string that is
3721: composed of two identical halves. The @samp{\(.*\)} matches the first
3722: half, which may be anything, but the @samp{\1} that follows must match
3723: the same exact text.
3724:
3725: @item \`
3726: matches the empty string, but only if it is at the beginning
3727: of the buffer.
3728:
3729: @item \'
3730: matches the empty string, but only if it is at the end of
3731: the buffer.
3732:
3733: @item \b
3734: matches the empty string, but only if it is at the beginning or
3735: end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
3736: @samp{foo} as a separate word. @samp{\bballs?\b} matches
3737: @samp{ball} or @samp{balls} as a separate word.@refill
3738:
3739: @item \B
3740: matches the empty string, provided it is @i{not} at the beginning or
3741: end of a word.
3742:
3743: @item \<
3744: matches the empty string, provided it is at the beginning of a word.
3745:
3746: @item \>
3747: matches the empty string, provided it is at the end of a word.
3748:
3749: @item \w
3750: matches any word-constituent character. The editor syntax table
3751: determines which characters these are.
3752:
3753: @item \W
3754: matches any character that is not a word-constituent.
3755:
3756: @item \s@var{code}
3757: matches any character whose syntax is @var{code}. @var{code} is a
3758: character which represents a syntax code: thus, @samp{w} for word
3759: constituent, @samp{-} for whitespace, @samp{(} for open-parenthesis,
3760: etc. @xref{Syntax}.@refill
3761:
3762: @item \S@var{code}
3763: matches any character whose syntax is not @var{code}.
3764: @end table
3765:
3766: @node Search Case, Replace, Regexps, Search
3767: @section Searching and Case
3768:
3769: @vindex case-fold-search
3770: @vindex default-case-fold-search
3771: All sorts of searches in Emacs normally ignore the case of the text they
3772: are searching through; if you specify searching for @samp{FOO}, then
3773: @samp{Foo} and @samp{foo} are also considered a match. Regexps, and in
3774: particular character sets, are included: @samp{[aB]} would match @samp{a}
3775: or @samp{A} or @samp{b} or @samp{B}.@refill
3776:
3777: If you do not want this feature, set the variable @code{case-fold-search}
3778: to @code{nil}. Then all letters must match exactly, including case. This
3779: variable has separate values in all individual buffers; in a new buffer,
3780: its value is initialized from @code{default-case-fold-search}.
3781: @xref{Variables}.
3782:
3783: @node Replace, Other Repeating Search, Search Case, Search
3784: @section Replacement Commands
3785: @cindex replacement
3786: @cindex string substitution
3787: @cindex global substitution
3788:
3789: Global search-and-replace operations are not needed as often in Emacs as
3790: they are in other editors, but they are available. In addition to the
3791: simple @code{replace-string} command which is like that found in most
3792: editors, there is a @code{query-replace} command which asks you, for each
3793: occurrence of the pattern, whether to replace it.
3794:
3795: The replace commands all replace one string (or regexp) with one
3796: replacement string. It is possible to perform several replacements in
3797: parallel using the command @code{expand-region-abbrevs}. @xref{Expanding
3798: Abbrevs}.
3799:
3800: @menu
3801: * Unconditional Replace:: Everything about replacement except for querying.
3802: * Query Replace:: How to use querying.
3803: @end menu
3804:
3805: @node Unconditional Replace, Query Replace, Replace, Replace
3806: @subsection Unconditional Replacement
3807: @findex replace-string
3808: @findex replace-regexp
3809:
3810: @table @kbd
3811: @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
3812: Replace every occurrence of @var{string} with @var{newstring}.
3813: @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
3814: Replace every match for @var{regexp} with @var{newstring}.
3815: @end table
3816:
3817: To replace every instance of @samp{foo} after point with @samp{bar}, use
3818: the command @kbd{M-x replace-string} with the two arguments @samp{foo} and
3819: @samp{bar}. Replacement occurs only after point, so if you want to cover
3820: the whole buffer you must go to the beginning first. All occurrences up to
3821: the end of the buffer are replaced; to limit replacement to part of the
3822: buffer, narrow to that part of the buffer before doing the replacement.
3823:
3824: When @code{replace-string} exits, point is left at the last occurrence
3825: replaced. The value of point when the @code{replace-string} command was
3826: issued is remembered on the mark ring; @kbd{C-u C-@key{SPC}} moves back
3827: there.
3828:
3829: @code{replace-string} replaces exact matches for a single string. The
3830: similar command @code{replace-regexp} replaces any match for a specified
3831: pattern.
3832:
3833: In @code{replace-regexp}, the @var{newstring} need not be constant. It
3834: can refer to all or part of what is matched by the @var{regexp}. @samp{\&}
3835: in @var{newstring} is replaced by the entire text being replaced.
3836: @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, is replaced
3837: by whatever matched the @var{d}'th parenthesized grouping in @var{regexp}.
3838: For example,@refill
3839:
3840: @example
3841: M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
3842: @end example
3843:
3844: @noindent
3845: would replace (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
3846: with @samp{cddr-safe}.
3847:
3848: @example
3849: M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
3850: @end example
3851:
3852: @noindent
3853: would perform exactly the opposite replacements. To include a @samp{\}
3854: in the text to replace with, you must give @samp{\\}.
3855:
3856: A numeric argument to either of the @code{replace-} commands restricts
3857: replacement to matches that are surrounded by word boundaries.
3858:
3859: @vindex case-replace
3860: @vindex case-fold-search
3861: If the arguments to @code{replace-string} are in lower case, it preserves
3862: case when it makes a replacement. Thus, the command
3863:
3864: @example
3865: M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
3866: @end example
3867:
3868: @noindent
3869: replaces a lower case @samp{foo} with a lower case @samp{bar}, @samp{FOO}
3870: with @samp{BAR}, and @samp{Foo} with @samp{Bar}. If upper case letters are
3871: used in the second argument, they remain upper case every time that
3872: argument is inserted. If upper case letters are used in the first
3873: argument, the second argument is always substituted exactly as given, with
3874: no case conversion. Likewise, if the variable @code{case-replace} is set
3875: to @code{nil}, replacement is done without case conversion. If
3876: @code{case-fold-search} is set to @code{nil}, case is significant in
3877: matching occurrences of @samp{foo} to replace; also, case conversion of the
3878: replacement string is not done.
3879:
3880: @node Query Replace,, Unconditional Replace, Replace
3881: @subsection Query Replace
3882: @cindex Query Replace
3883:
3884: @table @kbd
3885: @item M-% @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
3886: @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
3887: Replace some occurrences of @var{string} with @var{newstring}.
3888: @item M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
3889: Replace some matches for @var{string} with @var{newstring}.
3890: @end table
3891:
3892: @kindex M-%
3893: @findex query-replace
3894: If you want to change only some of the occurrences of @samp{foo} to
3895: @samp{bar}, not all of them, then you cannot use an ordinary
3896: @code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}).
3897: This command finds occurrences of @samp{foo} one by one, displays each
3898: occurrence and asks you whether to replace it. A numeric argument to
3899: @code{query-replace} tells it to consider only occurrences that are bounded
3900: by word-delimiter characters.@refill
3901:
3902: Aside from querying, @code{query-replace} works just like
3903: @code{replace-string}, and @code{query-replace-regexp} works
3904: just like @code{replace-regexp}.@refill
3905:
3906: The things you can type when you are shown an occurrence of @var{string}
3907: or a match for @var{regexp} are:
3908:
3909: @kindex SPC (query-replace)
3910: @kindex DEL (query-replace)
3911: @kindex Comma (query-replace)
3912: @kindex ESC (query-replace)
3913: @kindex . (query-replace)
3914: @kindex ! (query-replace)
3915: @kindex ^ (query-replace)
3916: @kindex C-r (query-replace)
3917: @kindex C-w (query-replace)
3918: @kindex C-l (query-replace)
3919:
3920: @c WideCommands
3921: @table @kbd
3922: @item @key{SPC}
3923: to replace the occurrence with @var{newstring}. This preserves case, just
3924: like @code{replace-string}, provided @code{case-replace} is non-@code{nil},
3925: as it normally is.@refill
3926:
3927: @item @key{DEL}
3928: to skip to the next occurrence without replacing this one.
3929:
3930: @item ,
3931: to replace this occurrence and display the result. You are then asked
3932: for another input character, except that since the replacement has
3933: already been made, @key{DEL} and @key{SPC} are equivalent. You could
3934: type @kbd{C-r} at this point (see below) to alter the replaced text. You
3935: could also type @kbd{C-x u} to undo the replacement; this exits the
3936: @code{query-replace}, so if you want to do further replacement you must use
3937: @kbd{C-x ESC} to restart (@pxref{Repetition}).
3938:
3939: @item @key{ESC}
3940: to exit without doing any more replacements.
3941:
3942: @item .
3943: to replace this occurrence and then exit.
3944:
3945: @item !
3946: to replace all remaining occurrences without asking again.
3947:
3948: @item ^
3949: to go back to the location of the previous occurrence (or what used to
3950: be an occurrence), in case changed it by mistake. This works by
3951: popping the mark ring. Only one @kbd{^} is allowed, because only one
3952: previous replacement location is kept during @code{query-replace}.
3953:
3954: @item C-r
3955: to enter a recursive editing level, in case the occurrence needs to be
3956: edited rather than just replaced with @var{newstring}. When you are
3957: done, exit the recursive editing level with @kbd{C-M-c} and the next
3958: occurrence will be displayed. @xref{Recursive Edit}.
3959:
3960: @item C-w
3961: to delete the occurrence, and then enter a recursive editing level as
3962: in @kbd{C-r}. Use the recursive edit to insert text to replace the
3963: deleted occurrence of @var{string}. When done, exit the recursive
3964: editing level with @kbd{C-M-c} and the next occurrence will be
3965: displayed.
3966:
3967: @item C-l
3968: to redisplay the screen and then give another answer.
3969:
3970: @item C-h
3971: to display a message summarizing these options, then give another
3972: answer.
3973: @end table
3974:
3975: If you type any other character, the @code{query-replace} is exited, and
3976: the character executed as a command. To restart the @code{query-replace},
3977: use @kbd{C-x @key{ESC}}, which repeats the @code{query-replace} because it
3978: used the minibuffer to read its arguments. @xref{Repetition, C-x ESC}.
3979:
3980: @node Other Repeating Search,, Replace, Search
3981: @section Other Search-and-Loop Commands
3982:
3983: Here are some other commands that find matches for a regular expression.
3984: They all operate from point to the end of the buffer.
3985:
3986: @findex list-matching-lines
3987: @findex count-matches
3988: @findex delete-non-matching-lines
3989: @findex delete-matching-lines
3990: @c grosscommands
3991: @table @kbd
3992: @item M-x list-matching-lines
3993: Print each line that follows point and contains a match for the
3994: specified regexp. A numeric argument specifies the number of context
3995: lines to print before and after each matching line; the default is
3996: none.
3997:
3998: @item M-x count-matches
3999: Print the number of matches following point for the specified regexp.
4000:
4001: @item M-x delete-non-matching-lines
4002: Delete each line that follows point and does not contain a match for
4003: the specified regexp.
4004:
4005: @item M-x delete-matching-lines
4006: Delete each line that follows point and contains a match for the
4007: specified regexp.
4008: @end table
4009:
4010: @node Fixit, Files, Search, Top
4011: @chapter Commands for Fixing Typos
4012: @cindex typos
4013:
4014: In this chapter we describe the commands that are especially useful for
4015: the times when you catch a mistake in your text just after you have made
4016: it, or change your mind while composing text on line.
4017:
4018: @menu
4019: * Kill Errors:: Commands to kill a batch of recently entered text.
4020: * Transpose:: Exchanging two characters, words, lines, lists...
4021: * Fixing Case:: Correcting case of last word entered.
4022: * Spelling:: Apply spelling checker to a word, or a whole file.
4023: @end menu
4024:
4025: @node Kill Errors, Transpose, Fixit, Fixit
4026: @section Killing Your Mistakes
4027:
4028: @table @kbd
4029: @item @key{DEL}
4030: Delete last character (@code{delete-backward-char}).
4031: @item M-@key{DEL}
4032: Kill last word (@code{backward-kill-word}).
4033: @item C-x @key{DEL}
4034: Kill to beginning of sentence (@code{backward-kill-sentence}).
4035: @end table
4036:
4037: @kindex DEL
4038: @findex delete-backward-char
4039: The @key{DEL} character (@code{delete-backward-char}) is the most
4040: important correction command. When used among graphic (self-inserting)
4041: characters, it can be thought of as canceling the last character typed.
4042:
4043: @kindex M-DEL
4044: @kindex C-x DEL
4045: @findex backward-kill-word
4046: @findex backward-kill-sentence
4047: When your mistake is longer than a couple of characters, it might be more
4048: convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}.
4049: @kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x
4050: @key{DEL}} kills back to the start of the last sentence. @kbd{C-x
4051: @key{DEL}} is particularly useful when you are thinking of what to write as
4052: you type it, in case you change your mind about phrasing.
4053: @kbd{M-@key{DEL}} and @kbd{C-x @key{DEL}} save the killed text for
4054: @kbd{C-y} and @kbd{M-y} to retrieve. @xref{Yanking}.@refill
4055:
4056: @kbd{M-@key{DEL}} is often useful even when you have typed only a few
4057: characters wrong, if you know you are confused in your typing and aren't
4058: sure exactly what you typed. At such a time, you cannot correct with
4059: @key{DEL} except by looking at the screen to see what you did. It requires
4060: less thought to kill the whole word and start over again.
4061:
4062: @node Transpose, Fixing Case, Kill Errors, Fixit
4063: @section Transposing Text
4064:
4065: @table @kbd
4066: @item C-t
4067: Transpose two characters (@code{transpose-chars}).
4068: @item M-t
4069: Transpose two words (@code{transpose-words}).
4070: @item C-M-t
4071: Transpose two balanced expressions (@code{transpose-sexps}).
4072: @item C-x C-t
4073: Transpose two lines (@code{transpose-lines}).
4074: @end table
4075:
4076: @cindex transposition
4077: @kindex C-t
4078: @findex transpose-chars
4079: The common error of transposing two characters can be fixed, when they
4080: are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally,
4081: @kbd{C-t} transposes the two characters on either side of point. When
4082: given at the end of a line, rather than transposing the last character of
4083: the line with the newline, which would be useless, @kbd{C-t} transposes the
4084: last two characters on the line. So, if you catch your transposition error
4085: right away, you can fix it with just a @kbd{C-t}. If you don't catch it so
4086: fast, you must move the cursor back to between the two transposed
4087: characters. If you transposed a space with the last character of the word
4088: before it, the word motion commands are a good way of getting there.
4089: Otherwise, a reverse search (@kbd{C-r}) is often the best way.
4090: @xref{Search}.
4091:
4092:
4093: @kindex C-x C-t
4094: @findex transpose-lines
4095: @kindex M-t
4096: @findex transpose-words
4097: @kindex C-M-t
4098: @findex transpose-sexps
4099: @kbd{Meta-t} (@code{transpose-words}) transposes the word before point
4100: with the word after point. It moves point forward over a word, dragging
4101: the word preceding or containing point forward as well. The punctuation
4102: characters between the words do not move. For example, @w{@samp{FOO, BAR}}
4103: transposes into @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.
4104:
4105: @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing
4106: two expressions (@pxref{Lists}), and @kbd {C-x C-t} (@code{transpose-lines})
4107: exchanges lines. They work like @kbd{M-t} except in determining the
4108: division of the text into syntactic units.
4109:
4110: A numeric argument to a transpose command serves as a repeat count: it
4111: tells the transpose command to move the character (word, sexp, line) before
4112: or containing point across several other characters (words, sexps, lines).
4113: For example, @kbd{C-u 3 C-t} moves the character before point forward
4114: across three other characters. This is equivalent to repeating @kbd{C-t}
4115: three times. @kbd{C-u - 4 M-t} moves the word before point backward across
4116: four words. @kbd{C-u - C-M-t} would cancel the effect of plain
4117: @kbd{C-M-t}.@refill
4118:
4119: A numeric argument of zero is assigned a special meaning (because
4120: otherwise a command with a repeat count of zero would do nothing): to
4121: transpose the character (word, sexp, line) ending after point with the
4122: one ending after the mark.
4123:
4124: @node Fixing Case, Spelling, Transpose, Fixit
4125: @section Case Conversion
4126:
4127: @table @kbd
4128: @item M-- M-l
4129: Convert last word to lower case. @kbd{Meta--} is Meta-minus!
4130: @item M-- M-u
4131: Convert last word to all upper case.
4132: @item M-- M-c
4133: Convert last word to lower case with capital initial.
4134: @end table
4135:
4136: @findex downcase-word
4137: @findex upcase-word
4138: @findex capitalize-word
4139: @kindex M-- M-l
4140: @kindex M-- M-u
4141: @kindex M-- M-c
4142: @cindex case conversion
4143: @cindex words
4144: A very common error is to type words in the wrong case. Because of this,
4145: the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a
4146: special feature when used with a negative argument: they do not move the
4147: cursor. As soon as you see you have mistyped the last word, you can simply
4148: case-convert it and go on typing. @xref{Case}.@refill
4149:
4150: @node Spelling,, Fixing Case, Fixit
4151: @section Checking and Correcting Spelling
4152: @cindex spelling
4153:
4154: @c doublewidecommands
4155: @table @kbd
4156: @item M-$
4157: Check and correct spelling of word (@code{spell-word}).
4158: @item M-x spell-buffer
4159: Check and correct spelling of each word in the buffer.
4160: @item M-x spell-region
4161: Check and correct spelling of each word in the region.
4162: @item M-x spell-string
4163: Check spelling of specified word.
4164: @end table
4165:
4166: @kindex M-$
4167: @findex spell-word
4168: To check the spelling of the word before point, and optionally correct it
4169: as well, use the command @kbd{M-$} (@code{spell-word}). This command runs
4170: an inferior process containing the @code{spell} program to see whether the
4171: word is correct English. If it is not, it asks you to edit the word (in
4172: the minibuffer) into a corrected spelling, and then does a @code{query-replace}
4173: to substitute the corrected spelling for the old one throughout the buffer.
4174:
4175: If you exit the minibuffer without altering the original spelling, it
4176: means you do not want to do anything to that word. Then the @code{query-replace}
4177: is not done.
4178:
4179: @findex spell-buffer
4180: @kbd{M-x spell-buffer} checks each word in the buffer the same way that
4181: @code{spell-word} does, doing a @code{query-replace} if appropriate for
4182: every incorrect word.@refill
4183:
4184: @findex spell-region
4185: @kbd{M-x spell-region} is similar but operates only on the region, not
4186: the entire buffer.
4187:
4188: @findex spell-string
4189: @kbd{M-x spell-string} reads a string as an argument and checks whether
4190: that is a correctly spelled English word. It prints in the echo area a
4191: message giving the answer.
4192:
4193: @node Files, Buffers, Fixit, Top
4194: @chapter File Handling
4195: @cindex files
4196:
4197: The basic unit of stored data in Unix is the @dfn{file}. To edit a file,
4198: you must tell Emacs to examine the file and prepare a buffer containing a
4199: copy of the file's text. This is called @dfn{visiting} the file. Editing
4200: commands apply directly to text in the buffer; that is, to the copy inside
4201: Emacs. Your changes appear in the file itself only when you @dfn{save} the
4202: buffer back into the file.
4203:
4204: In addition to visiting and saving files, Emacs can delete, copy, rename,
4205: and append to files, and operate on file directories.
4206:
4207: @menu
4208: * File Names:: How to type and edit file name arguments.
4209: * Visiting:: Visiting a file prepares Emacs to edit the file.
4210: * Saving:: Saving makes your changes permanent.
4211: * Reverting:: Reverting cancels all the changes not saved.
4212: * Auto Save:: Auto Save periodically protects against loss of data.
4213: * ListDir:: Listing the contents of a file directory.
4214: * Dired:: ``Editing'' a directory to delete, rename, etc.
4215: the files in it.
4216: * Misc File Ops:: Other things you can do on files.
4217: @end menu
4218:
4219: @node File Names,, Files, Files
4220: @section File Names
4221: @cindex file names
4222:
4223: Most Emacs commands that operate on a file require you to specify the
4224: file name. (Saving and reverting are exceptions; the buffer knows which
4225: file name to use for them.) File names are specified using the minibuffer
4226: (@pxref{Minibuffer}). @dfn{Completion} is available, to make it easier to
4227: specify long file names. @xref{Completion}.
4228:
4229: There is always a @dfn{default file name} which will be used if you type
4230: just @key{RET}, entering an empty argument. Normally the default file name
4231: is the name of the file visited in the current buffer; this makes it easy
4232: to operate on that file with any of the Emacs file commands.
4233:
4234: @vindex default-directory
4235: Each buffer has a default directory, normally the same as the directory
4236: of the file visited in that buffer. When Emacs reads a file name, if you
4237: do not specify a directory, the default directory is used. If you specify
4238: a directory in a relative fashion, with a name that does not start with a
4239: slash, it is interpreted with respect to the default directory. The
4240: default directory is kept in the variable @code{default-directory}, which
4241: has a separate value in every buffer.
4242:
4243: For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then
4244: the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo},
4245: which does not specify a directory, it is short for @file{/u/rms/gnu/foo}.
4246: @samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo}
4247: would stand for the filename @file{/u/rms/gnu/new/foo}.
4248:
4249: The default directory actually appears initially in the minibuffer when
4250: the file name is read. This serves two purposes: it shows you what the
4251: default is, so that you can type a relative file name and know with
4252: certainty what it will mean, and it allows you to edit the default to
4253: specify a different directory.
4254:
4255: Note that it is legitimate to type an absolute file name after you enter
4256: the minibuffer, ignoring the presence of the default directory name as part
4257: of the text. The final minibuffer contents may look invalid, but that is
4258: not so. @xref{Minibuffer File}.
4259:
4260: The command @kbd{M-x pwd} prints the current buffer's default directory,
4261: and the command @kbd{M-x cd} sets it (to a value read using the
4262: minibuffer). A buffer's default directory changes only when the @code{cd}
4263: command is used. A file-visiting buffer's default directory is initialized
4264: to the directory of the file that is visited there. If a buffer is made
4265: randomly with @kbd{C-x b}, its default directory is copied from that of the
4266: buffer that was current at the time.
4267:
4268: @node Visiting, Saving, File Names, Files
4269: @section Visiting Files
4270: @cindex visiting files
4271:
4272: @c WideCommands
4273: @table @kbd
4274: @item C-x C-f
4275: Visit a file (@code{find-file}).
4276: @item C-x C-v
4277: Visit a different file instead of the one visited last
4278: (@code{find-alternate-file}).
4279: @item C-x 4 C-f
4280: Visit a file, in another window (@code{find-file-other-window}). Don't
4281: change this window.
4282: @end table
4283:
4284: @cindex files
4285: @cindex visiting
4286: @cindex saving
4287: @vindex ask-about-buffer-names
4288: @dfn{Visiting} a file means copying its contents into Emacs where you can
4289: edit them. Emacs makes a new buffer for each file that you visit. We say
4290: that the buffer is visiting the file that it was created to hold. Emacs
4291: constructs the buffer name from the file name by throwing away the
4292: directory, keeping just the name proper. For example, a file named
4293: @file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}. If
4294: there is already a buffer with that name, a unique name is constructed by
4295: appending @samp{<2>}, @samp{<3>}, or so on, using the lowest number that
4296: makes a name that is not already in use. If the variable
4297: @code{ask-about-buffer-names} is non-@code{nil}, the user is asked what
4298: buffer name to use; this takes the place of automatic uniquization.
4299:
4300: Each window's mode line shows the name of the buffer that is being displayed
4301: in that window, so you can always tell what buffer you are editing.
4302:
4303: The changes you make with Emacs are made in the Emacs buffer. They do
4304: not take effect in the file that you visited, or any place permanent, until
4305: you @dfn{save} the buffer. Saving the buffer means that Emacs writes the
4306: current contents of the buffer into its visited file. @xref{Saving}.
4307:
4308: @cindex modified (buffer)
4309: If a buffer contains changes that have not been saved, the buffer is said
4310: to be @dfn{modified}. This is important because it implies that some
4311: changes will be lost if the buffer is not saved. The mode line displays
4312: two stars near the left margin if the buffer is modified.
4313:
4314: @kindex C-x C-f
4315: @findex find-file
4316: To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow
4317: the command with the name of the file you wish to visit, terminated by a
4318: @key{RET}.
4319:
4320: The file name is read using the minibuffer (@pxref{Minibuffer}), with
4321: defaulting and completion in the standard manner (@pxref{File Names}).
4322: While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}.
4323:
4324: Your confirmation that @kbd{C-x C-f} has completed successfully is the
4325: appearance of new text on the screen and a new buffer name in the mode
4326: line. If the specified file does not exist and could not be created, or
4327: cannot be read, then an error results. The error message is printed in the
4328: echo area, and includes the file name which Emacs was trying to visit.
4329:
4330: If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
4331: another copy. It selects the existing buffer containing that file.
4332: However, before doing so, it checks that the file itself has not changed
4333: since you visited or saved it last. If the file has changed, a warning
4334: message is printed. @xref{Interlocking,,Simultaneous Editing}.
4335:
4336: @cindex creating files
4337: What if you want to create a file? Just visit it. Emacs prints
4338: @samp{(New File)} in the echo area, but in other respects behaves as if you
4339: had visited an existing empty file. If you make any changes and save them,
4340: the file is created.
4341:
4342: @kindex C-x C-v
4343: @findex find-alternate-file
4344: If you visit a nonexistent file unintentionally (because you typed the
4345: wrong file name), use the @kbd{C-x C-v} (@code{find-alternate-file})
4346: command to visit the file you wanted. @kbd{C-x C-v} is similar to @kbd{C-x
4347: C-f}, but it kills the current buffer (after first offering to save it if
4348: it is modified).@refill
4349:
4350: @vindex find-file-run-dired
4351: If the file you specify is actually a directory, Dired is called on that
4352: directory (@pxref{Dired}). This can be inhibited by setting the variable
4353: @code{find-file-run-dired} to @code{nil}; then it is an error to try to
4354: visit a directory.
4355:
4356: @kindex C-x 4 f
4357: @findex find-file-other-window
4358: @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
4359: except that the buffer containing the specified file is selected in another
4360: window. The window that was selected before @kbd{C-x 4 f} continues to
4361: show the same buffer it was already showing. If this command is used when
4362: only one window is being displayed, that window is split in two, with one
4363: window showing the same before as before, and the other one showing the
4364: newly requested buffer.
4365:
4366: @node Saving, Reverting, Visiting, Files
4367: @section Saving Files
4368:
4369: @dfn{Saving} a buffer in Emacs means writing its contents back into the file
4370: that was visited in the buffer.
4371:
4372: @table @kbd
4373: @item C-x C-s
4374: Save the current buffer in its visited file (@code{save-buffer}).
4375: @item C-x s
4376: Save any or all buffers in their visited files (@code{save-some-buffers}).
4377: @item M-~
4378: Forget that the current buffer has been changed (@code{not-modified}).
4379: @item C-x C-w
4380: Save the current buffer in a specified file, and record that file as
4381: the one visited in the buffer (@code{write-file}).
4382: @item M-x set-visited-file-name
4383: Mark the current buffer as visiting a specified file.
4384: @end table
4385:
4386: @kindex C-x C-s
4387: @findex save-buffer
4388: When you wish to save the file and make your changes permanent, type
4389: @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
4390: prints a message such as
4391:
4392: @example
4393: Wrote /u/rms/gnu/gnu.tasks
4394: @end example
4395:
4396: @noindent
4397: If the selected buffer is not modified (no changes have been made in it
4398: since the buffer was created or last saved), saving is not really done,
4399: because it would be redundant. Instead, @kbd{C-x C-s} prints a message in
4400: the echo area saying
4401:
4402: @example
4403: (No changes need to be written)
4404: @end example
4405:
4406: @kindex C-x s
4407: @findex save-some-buffers
4408: The command @kbd{C-x s} (@code{save-some-buffers}) can save any or all modified
4409: buffers. First it asks, for each modified buffer, whether to save it.
4410: These questions appear as typeout, overlying the buffer text, and should
4411: be answered with @kbd{y} or @kbd{n}. After all questions have been asked,
4412: the buffers you have approved are all saved.
4413:
4414: @kindex M-~
4415: @findex not-modified
4416: If you have changed a buffer and do not want the changes to be saved, you
4417: should take some action to prevent it. Otherwise, each time you use
4418: @code{save-some-buffers} you are liable to save it by mistake. One thing
4419: you can do is type @kbd{M-~} (@code{not-modified}), which clears out the
4420: indication that the buffer is modified. If you do this, none of the save
4421: commands will believe that the buffer needs to be saved. (If we take
4422: @samp{~} to mean `not', then @kbd{Meta-~} is `not', metafied.) You could
4423: also use @code{set-visited-file-name} (see below) to mark the buffer as
4424: visiting a different file name, one which is not in use for anything
4425: important. Alternatively, you can undo all the changes made since the file
4426: was visited or saved, by reading the text from the file again. This is
4427: called @dfn{reverting}. @xref{Reverting}. You could also undo all the
4428: changes by repeating the undo command @kbd{C-x u} until you have undone all
4429: the changes; but this only works if you have not made more changes than the
4430: undo mechanism can remember.
4431:
4432: @findex set-visited-file-name
4433: @kbd{M-x set-visited-file-name} alters the name of the file that the
4434: current buffer is visiting. It reads the new file name using the
4435: minibuffer. It can be used on a buffer that is not visiting a file, too.
4436: The buffer's name is changed to correspond to the file it is now visiting
4437: in the usual fashion (unless the new name is in use already for some other
4438: buffer; in that case, the buffer name is not changed).
4439: @code{set-visited-file-name} does not save the buffer in the newly visited
4440: file; it just alters the records inside Emacs so that, if you save the
4441: buffer, it will be saved in that file. It also marks the buffer as
4442: ``modified'' so that @kbd{C-x C-s} @i{will} save.
4443:
4444: @kindex C-x C-w
4445: @findex write-file
4446: If you wish to mark the buffer as visiting different file and save it
4447: right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely
4448: equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}.
4449: @kbd{C-x C-s} used on a buffer that is not visiting with a file has the
4450: same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
4451: buffer as visiting that file, and saves it there. The default file name in
4452: a buffer that is not visiting a file is made by combining the buffer name
4453: with the buffer's default directory.
4454:
4455: If Emacs is about to save a file and sees that the date of the latest
4456: version on disk does not match what Emacs last read or wrote, Emacs
4457: notifies you of this fact, because it probably indicates a problem caused
4458: by simultaneous editing and requires your immediate attention.
4459: @xref{Interlocking,, Simultaneous Editing}.
4460:
4461: @vindex require-final-newline
4462: If the variable @code{require-final-newline} is non-@code{nil}, Emacs
4463: puts a newline at the end of any file that doesn't already end in one,
4464: every time a file is saved or written.
4465:
4466: @menu
4467: * Backup:: How Emacs saves the old version of your file.
4468: * Interlocking:: How Emacs protects against simultaneous editing
4469: of one file by two users.
4470: @end menu
4471:
4472: @node Backup, Interlocking, Saving Saving
4473: @subsection Backup Files
4474: @cindex backup file
4475:
4476: Because Unix does not provide version numbers in file names, rewriting a
4477: file in Unix automatically destroys all record of what the file used to
4478: contain. Thus, saving a file from Emacs throws away the old contents of
4479: the file---or it would, except that Emacs carefully copies the old contents
4480: to another file, called the @dfn{backup} file, before actually saving.
4481: At your option, Emacs can keep either a single backup file or a series of
4482: numbered backup files for each file that you edit.
4483:
4484: Emacs makes a backup for a file only the first time the file is saved
4485: from one buffer. No matter how many times you save a file, its backup file
4486: continues to contain the contents from before the file was visited.
4487: Normally this means that the backup file contains the contents from before
4488: the current editing session; however, if you kill the buffer and then visit
4489: the file again, a new backup file will be made by the next save.
4490:
4491: If you choose to have a single backup file (this is the default),
4492: the backup file's name is constructed by appending @samp{~} to the
4493: file name being edited; thus, the backup file for @file{eval.c} would
4494: be @file{eval.c~}.
4495:
4496: If you choose to have a series of numbered backup files, backup file
4497: names are made by appending @samp{.~}, the number, and another @samp{~} to
4498: the original file name. Thus, the backup files of @file{eval.c} would be
4499: called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names
4500: like @file{eval.c.~259~} and beyond.
4501:
4502: @vindex version-control
4503: The choice of single backup or numbered backups is controlled by the
4504: variable @code{version-control}. Its possible values are
4505:
4506: @table @code
4507: @item t
4508: Make numbered backups.
4509: @item nil
4510: Make numbered backups for files that have numbered backups already.
4511: @item never
4512: Do not in any case make numbered backups.
4513: @end table
4514:
4515: @noindent
4516: @code{version-control} may be set locally in an individual buffer to
4517: control the making of backups for that buffer's file. For example,
4518: Rmail mode locally sets @code{version-control} to @code{never} to make sure
4519: that there is only one backup for an Rmail file. @xref{Locals}.
4520:
4521: @vindex make-backup-files
4522: If the variable @code{make-backup-files} is set to @code{nil}, backup
4523: files are not written at all.
4524:
4525: @subsubsection Automatic Deletion of Backups
4526:
4527: @vindex kept-old-versions
4528: @vindex kept-new-versions
4529: To prevent unlimited consumption of disk space, Emacs can delete numbered
4530: backup versions automatically. Generally Emacs keeps the first few backups
4531: and the latest few backups, deleting any in between. This happens every
4532: time a new backup is made. The two variables that control the deletion are
4533: @code{kept-old-versions} and @code{kept-new-versions}. Their values are, respectively
4534: the number of oldest (lowest-numbered) backups to keep and the number of
4535: newest (highest-numbered) ones to keep, each time a new backup is made.
4536: Recall that these values are used just after a new backup version is made;
4537: that newly made backup is included in the count in @code{kept-new-versions}.
4538: By default, both variables are 2.
4539:
4540: @vindex trim-versions-without-asking
4541: If @code{trim-versions-without-asking} is non-@code{nil}, the excess
4542: middle versions are deleted without a murmur. If it is @code{nil}, the
4543: default, then you are asked whether the excess middle versions should
4544: really be deleted.
4545:
4546: Dired's @kbd{.} command can also be used to delete old versions;
4547: @xref{Dired}.
4548:
4549: @subsubsection Copying vs.@: Renaming
4550:
4551: Backup files can be made by copying the old file or by renaming it. This
4552: makes a difference when the old file has multiple names. If the old file
4553: is renamed into the backup file, then the alternate names become names for
4554: the backup file. If the old file is copied instead, then the alternate
4555: names remain names for the file that you are editing, and the contents
4556: accessed by those names will be the new contents.
4557:
4558: @vindex backup-by-copying
4559: @vindex backup-by-copying-when-linked
4560: The choice of renaming or copying is controlled by two variables.
4561: Normally, renaming is done. If the variable @code{backup-by-copying} is
4562: non-@code{nil}, copying is used. If the variable @code{backup-by-copying-when-linked}
4563: is non-@code{nil}, then copying is done for files that have multiple names,
4564: but renaming is done when the file being edited has only one name. (For
4565: files with only one name, the major difference between renaming and copying
4566: is that renaming is faster.)
4567:
4568: @node Interlocking,,Backup,Saving
4569: @subsection Protection against Simultaneous Editing
4570:
4571: @cindex file dates
4572: @cindex simultaneous editing
4573: Simultaneous editing occurs when two users visit the same file, both make
4574: changes, and then both save them. If nobody were informed that this was
4575: happening, whichever user saved first would later find that his changes
4576: were lost. On some systems, Emacs notices immediately when the second user
4577: starts to change the file, and issues an immediate warning. When this is
4578: not possible, or if the second user has gone on to change the file despite
4579: the warning, Emacs checks later when the file is saved, and issues a second
4580: warning when a user is about to overwrite a file containing another user's
4581: changes. If the editing user takes the proper corrective action at this
4582: point, he can prevent actual loss of work.
4583:
4584: @findex ask-user-about-lock
4585: When you make the first modification in an Emacs buffer that is visiting
4586: a file, Emacs records that you have locked the file. (It does this by
4587: writing another file in a directory reserved for this purpose). The lock
4588: is removed when you save the changes. The idea is that the file is locked
4589: whenever the buffer is modified. If you begin to modify the buffer while
4590: the visited file is locked by someone else, this constitutes a collision,
4591: and Emacs asks you what to do. It does this by calling the Lisp function
4592: @code{ask-user-about-lock}, which you can redefine for the sake of
4593: customization. The standard definition of this function asks you a
4594: question and accepts three possible answers:
4595:
4596: @table @kbd
4597: @item s
4598: Steal the lock. Whoever was already changing the file loses the lock,
4599: and you gain the lock.
4600: @item p
4601: Proceed. Go ahead and edit the file despite its being locked by someone else.
4602: @item q
4603: Quit. This causes an error (@code{file-locked}) and the modification you
4604: were trying to make in the buffer does not actually take place.
4605: @end table
4606:
4607: Note that locking works on the basis of a file name; if a file has
4608: multiple names, Emacs does not realize that the two names are the same file
4609: and cannot prevent two user from editing it simultaneously under different
4610: names. However, basing locking on names means that Emacs can interlock the
4611: editing of new files that will not really exist until they are saved.
4612:
4613: Some systems are not configured to allow Emacs to make locks. On
4614: these systems, Emacs cannot detect trouble in advance, but it still can
4615: detect it in time to prevent you from overwriting someone else's changes.
4616:
4617: Every time Emacs saves a buffer, it first checks the last-modification
4618: date of the existing file on disk to see that it has not changed since the
4619: file was last visited or saved. If the date does not match, it implies
4620: that changes were made in the file in some other way, and these changes are
4621: about to be lost if Emacs actually does save. To prevent this, Emacs
4622: prints a warning message and asks for confirmation before saving.
4623: Occasionally you will know why the file was changed and know that it does
4624: not matter; then you can answer `yes' and proceed. Otherwise, you should
4625: cancel the save with @kbd{C-g} and investigate the situation.
4626:
4627: The first thing you should do when notified that simultaneous editing has
4628: already taken place is to list the directory with @kbd{C-u C-x C-d}
4629: (@pxref{ListDir,,Directory Listing}). This will show the file's current
4630: author. You should attempt to contact him to warn him not to continue
4631: editing. Often the next step is to save the contents of your Emacs buffer
4632: under a different name, and use @code{diff} to compare the two
4633: files.@refill
4634:
4635: Simultaneous editing checks are also made when you visit with @kbd{C-x
4636: C-f} a file that is already visited. This is not strictly necessary, but
4637: it can cause you to find out about the problem earlier, when perhaps
4638: correction takes less work.
4639:
4640: @node Reverting, Auto Save, Saving, Files
4641: @section Reverting a Buffer
4642: @findex revert-buffer
4643: @cindex drastic changes
4644:
4645: If you have made extensive changes to a file and then change your mind
4646: about them, you can get rid of them by reading in the previous version of
4647: the file. To do this, use @kbd{M-x revert-buffer}, which operates on the
4648: current buffer. Since this is a very dangerous thing to do, you must
4649: confirm it with `yes'.
4650:
4651: If the current buffer has been auto-saved more recently than it has been
4652: saved for real, @code{revert-buffer} offers to read the auto save file
4653: instead of the visited file. This question comes before the usual request
4654: for confirmation, and demands @kbd{y} or @kbd{n} as an answer. If you have
4655: started to type @kbd{yes} for confirmation without realizing that the other
4656: question was going to be asked, the @kbd{y} will answer that question, but
4657: the @kbd{es} will not be valid confirmation. So you will have a chance to
4658: cancel the operation with @kbd{C-g} and try it again with the answers that
4659: you really intend.
4660:
4661: @code{revert-buffer} keeps point at the same distance (measured in
4662: characters) from the beginning of the file. If the file was edited only
4663: slightly, you will be at approximately the same piece of text after
4664: reverting as before. If you have made drastic changes, the same value of
4665: point in the old file may address a totally different piece of text.
4666:
4667: A buffer reverted from its visited file is marked ``not modified'' until
4668: another change is made.
4669:
4670: Some kinds of buffers whose contents reflect data bases other than files,
4671: such as Dired buffers, can also be reverted. For them, reverting means
4672: recalculating their contents from the appropriate data base. Buffers
4673: created randomly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
4674: reports an error when asked to do so.
4675:
4676: @node Auto Save, ListDir, Reverting, Files
4677: @section Auto Saving: Protection Against Disasters
4678: @cindex Auto Save mode
4679: @cindex crashes
4680:
4681: Emacs saves all the visited files from time to time (based on counting
4682: your keystrokes) without being asked. This is called @dfn{auto-saving}.
4683: It prevents you from losing more than a limited amount of work if the
4684: system crashes.
4685:
4686: @vindex auto-save-visited-file-name
4687: Auto-saving does not normally save in the files that you visited, because
4688: it can be very undesirable to save a program that is in an inconsistent
4689: state because you have made half of a planned change. Instead, auto-saving
4690: is done in a different file called the @dfn{auto-save file}, and the
4691: visited file is changed only when you request saving explicitly (such as
4692: with @kbd{C-x C-s}). If you want auto-saving to be done in the visited
4693: file, set the variable @code{auto-save-visited-file-name} to be non-@code{nil}.
4694: The file name to be used for auto-saving in a buffer is calculated when
4695: auto-saving is turned on in that buffer, based on the variable values in
4696: effect at that time.
4697:
4698: Normally, the auto-save file name is made by appending @samp{#} to the
4699: front of the visited file name. Thus, a buffer visiting file @file{foo.c}
4700: would be auto-saved in a file @file{#foo.c}. Most buffers that are not
4701: visiting files are auto-saved only if you request it explicitly; when they
4702: are auto-saved, the auto-save file name is made by appending @samp{#%} to
4703: the buffer name. For example, the @samp{*mail*} buffer in which you
4704: compose messages to be sent is auto-saved in a file named @file{#%*mail*}.
4705: Auto-save file names are made this way unless you reprogram parts of Emacs
4706: to do something different.
4707:
4708: @vindex auto-save-default
4709: @findex auto-save-mode
4710: Each time you visit a file, auto saving is turned on for that file's
4711: buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
4712: in batch mode; @pxref{Entering Emacs}). The default for this variable is
4713: @code{t}, so auto-saving is the usual practice for file-visiting buffers.
4714: Auto-saving can be turned on or off for any existing buffer with the
4715: command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x
4716: auto-save-mode} turns auto-saving on with a positive argument, off with a
4717: zero or negative argument; with no argument, it toggles.
4718:
4719: @vindex auto-save-interval
4720: @findex do-auto-save
4721: Emacs does auto-saving every so often, based on counting how many
4722: characters you have typed since the last time auto-saving was done. The
4723: variable @code{auto-save-interval} specifies how many characters there are
4724: between auto-saves. By default, it is 300. Emacs also auto-saves whenever
4725: you call the function @code{do-auto-save}.
4726:
4727: Emacs also does auto-saving whenever it gets a fatal error. This
4728: includes killing the Emacs job with a shell command such as @code{kill
4729: %emacs}, or disconnecting a phone line or network connection.
4730:
4731: When Emacs determines that it is time for auto-saving, each buffer is
4732: considered, and is auto-saved if auto-saving is turned on for it and it has
4733: been changed since the last time it was auto-saved. If any auto-saving is
4734: done, the message @samp{Auto-saving...} is displayed in the echo area until
4735: auto-saving is finished. Errors occurring during auto-saving are trapped
4736: so that they do not interfere with the execution of commands you have been
4737: typing.
4738:
4739: @vindex delete-auto-save-files
4740: A buffer's auto-save file is deleted when you save the buffer in its
4741: visited file. To inhibit this, set the variable @code{delete-auto-save-files}
4742: to @code{nil}.
4743:
4744: @findex recover-file
4745: The way to use the contents of an auto save file to recover from a loss
4746: of data is with the command @kbd{M-x recover-file @key{RET} @var{file}
4747: @key{RET}}. This visits @var{file} and then (after your confirmation) it
4748: from its auto-save file @file{#@var{file}}. You can then save with
4749: @kbd{C-x C-s} to put the recovered text into @var{file} itself. For
4750: example, to recover file @file{foo.c} from its auto-save file
4751: @file{#foo.c}, do:@refill
4752:
4753: @example
4754: M-x recover-file @key{RET} foo.c @key{RET}
4755: C-x C-s
4756: @end example
4757:
4758: @node ListDir, Dired, Auto Save, Files
4759: @section Listing a File Directory
4760:
4761: @cindex file directory
4762: @cindex directory listing
4763: Files are classified by Unix into @dfn{directories}. A @dfn{directory
4764: listing} is a list of all the files in a directory. Emacs provides
4765: directory listings in brief format (file names only) and verbose format
4766: (sizes, dates, and authors included).
4767:
4768: @table @kbd
4769: @item C-x C-d @var{dir-or-pattern}
4770: Print a brief directory listing (@code{list-directory}).
4771: @item C-u C-x C-d @var{dir-or-pattern}
4772: Print a verbose directory listing.
4773: @end table
4774:
4775: @findex list-directory
4776: @kindex C-x C-d
4777: The command to print a directory listing is @kbd{C-x C-d} (@code{list-directory}).
4778: It reads using the minibuffer a file name which is either a directory to be
4779: listed or a wildcard-containing pattern for the files to be listed. For
4780: example,
4781:
4782: @example
4783: C-x C-d /u2/emacs/etc @key{RET}
4784: @end example
4785:
4786: @noindent
4787: lists all the files in directory @file{/u2/emacs/etc}. An example of
4788: specifying a file name pattern is
4789:
4790: @example
4791: C-x C-d /u2/emacs/src/*.c @key{RET}
4792: @end example
4793:
4794: Normally, @kbd{C-x C-d} prints a brief directory listing containing just
4795: file names. A numeric argument (regardless of value) tells it to print a
4796: verbose listing (like @code{ls -l}).
4797:
4798: @vindex list-directory-brief-switches
4799: @vindex list-directory-verbose-switches
4800: The text of a directory listing is obtained by running @code{ls} in an
4801: inferior process. Two Emacs variables control the switches passed to
4802: @code{ls}: @code{list-directory-brief-switches} is a string giving the
4803: switches to use in brief listings (@code{"-CF"} by default), and
4804: @code{list-directory-verbose-switches} is a string giving the switches to
4805: use in a verbose listing (@code{"-l"} by default).
4806:
4807: @node Dired, Misc File Ops, ListDir, Files
4808: @section Dired, the Directory Editor
4809: @cindex Dired
4810: @cindex deletion (of files)
4811:
4812: Dired makes it easy to delete or visit many of the files in a single
4813: directory at once. It makes an Emacs buffer containing a listing of the
4814: directory. You can use the normal Emacs commands to move around in this
4815: buffer, and special Dired commands to operate on the files.
4816:
4817: @findex dired
4818: @kindex C-x d
4819: @vindex dired-listing-switches
4820: To invoke dired, do @kbd{C-x d} or @kbd{M-x dired}. The command reads a
4821: directory name or wildcard file name pattern as a minibuffer argument just
4822: like the @code{list-directory} command, @kbd{C-x C-d}. Where @code{dired}
4823: differs from @code{list-directory} is in naming the buffer after the
4824: directory name or the wildcard pattern used for the listing, and putting
4825: the buffer into Dired mode so that the special commands of Dired are
4826: available in it. The variable @code{dired-listing-switches} is a string
4827: used as an argument to @code{ls} in making the directory; this string
4828: @i{must} contain @samp{-l}.
4829:
4830: @findex dired-other-window
4831: @kindex C-x 4 d
4832: To display the Dired buffer in another window rather than in the selected
4833: window, use @kbd{C-x 4 d} (@code{dired-other-window)} instead of @kbd{C-x d}.
4834:
4835: Once the Dired buffer exists, you can switch freely between it and other
4836: Emacs buffers. Whenever the Dired buffer is selected, certain special
4837: commands are provided that operate on files that are listed. The Dired
4838: buffer is ``read-only'', and inserting text in it is not useful, so
4839: ordinary printing characters such as @kbd{d} and @kbd{x} are used for Dired
4840: commands. Most Dired commands operate on the file described by the line
4841: that point is on. Some commands perform operations immediately; others
4842: ``flag'' the file to be operated on later.
4843:
4844: Most Dired commands that operate on the current line's file also treat a
4845: numeric argument a repeat count, meaning to apply to the files of the next
4846: few lines. A negative argument means to operate on the files of the
4847: preceding lines, and leave point on the first of those lines.
4848:
4849: All the usual Emacs cursor motion commands are available in Dired
4850: buffers. Some special purpose commands are also provided. The keys
4851: @kbd{C-n} and @kbd{C-p} are redefined so that they try to position
4852: the cursor at the beginning of the filename on the line, rather than
4853: at the beginning of the line.
4854:
4855: For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent to
4856: @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. Moving by lines is done so
4857: often in Dired that it deserves to be easy to type. @key{DEL} (move up and
4858: unflag) is often useful simply for moving up.@refill
4859:
4860: @section Deleting Files with Dired
4861:
4862: The primary use of Dired is to flag files for deletion and then delete
4863: them.
4864:
4865: @table @kbd
4866: @item d
4867: Flag this file for deletion.
4868: @item u
4869: Remove deletion-flag on this line.
4870: @item @key{DEL}
4871: Remove deletion-flag on previous line, moving point to that line.
4872: @item x
4873: Delete the files that are flagged for deletion.
4874: @item #
4875: Flag all auto-save files (files whose names start with @samp{#}) for
4876: deletion (@pxref{Auto Save}).
4877: @item ~
4878: Flag all backup files (files whose names end with @samp{~}) for deletion
4879: (@pxref{Backup}).
4880: @item .
4881: Flag excess numeric backup files for deletion. The oldest and newest
4882: few backup files of any one file are exempt; the middle ones are flagged.
4883: @end table
4884:
4885: You can flag a file for deletion by moving to the line describing the
4886: file and typing @kbd{d} or @kbd{C-d}. The deletion flag is visible as a
4887: @samp{D} at the beginning of the line. Point is moved to the beginning of
4888: the next line, so that repeated @kbd{d} commands flag successive files.
4889:
4890: The files are flagged for deletion rather than deleted immediately to
4891: avoid the danger of deleting a file accidentally. Until you direct Dired
4892: to delete the flagged files, you can remove deletion flags using the
4893: commands @kbd{u} and @key{DEL}. @kbd{u} works just like @kbd{d}, but
4894: removes flags rather than making flags. @key{DEL} moves upward, removing
4895: flags; it is like @kbd{u} with numeric argument automatically negated.
4896:
4897: To delete the flagged files, type @kbd{x}. This command first displays a
4898: list of all the file names flagged for deletion, and requests confirmation
4899: with `yes'. Once you confirm, all the flagged files are deleted, and their
4900: lines are deleted from the text of the Dired buffer. The shortened Dired
4901: buffer remains selected. If you answer `no' or quit with @kbd{C-g}, you
4902: return immediately to Dired, with the deletion flags still present and no
4903: files actually deleted.
4904:
4905: The @kbd{#}, @kbd{~} and @kbd{.} commands flags many files for
4906: deletion, based on their names. These commands are useful precisely
4907: because they do not actually delete any files; you can remove the
4908: deletion flags from any flagged files that you really wish to keep.@refill
4909:
4910: @kbd{#} flags for deletion all files that appear to have been made
4911: by auto-saving (that is, files whose names begin with @samp{#}).
4912: @kbd{~} flags for deletion all files that appear to have been made as
4913: backups for files that were edited (that is, files whose names end
4914: with @samp{~}).
4915:
4916: @kbd{.} flags just some of the backup files for deletion: only
4917: numeric backups that are not among the oldest few nor the newest few
4918: backups of any one file. Normally @code{dired-kept-versions}
4919: specifies the number of newest versions of each file to keep, and
4920: @code{kept-old-versions} specifies the number of oldest versions to
4921: keep. A positive numeric argument to @kbd{.} specifies the number of
4922: newest versions to keep, overriding @code{dired-kept-versions}. A
4923: negative numeric argument overrides @code{kept-old-versions}, using
4924: minus the value of the argument to specify the number of oldest
4925: versions of each file to keep.@refill
4926:
4927:
4928: @section Immediate File Operations in Dired
4929:
4930: Some file operations in Dired take place immediately when they are
4931: requested.
4932:
4933: @table @kbd
4934: @item c
4935: Copies the file described on the current line. You must supply a file name
4936: to copy to, using the minibuffer.
4937: @item f
4938: Visits the file described on the current line. It is just like typing
4939: @kbd{C-x C-f} and supplying that file name. If the file on this line is a
4940: subdirectory, @kbd{f} actually causes Dired to be invoked on that
4941: subdirectory. @xref{Visiting}.
4942: @item o
4943: Like @kbd{f}, but uses another window to display the file's buffer. The
4944: Dired buffer remains visible in the first window. This is like using
4945: @kbd{C-x 4 C-f} to visit the file. @xref{Windows}.
4946: @item r
4947: Renames the file described on the current line. You must supply a file
4948: name to rename to, using the minibuffer.
4949: @item v
4950: Views the file described on this line using @kbd{M-x view-file}. Viewing a
4951: file is like visiting it, but is slanted toward moving around in the file
4952: conveniently and does not allow changing the file. @xref{Misc File
4953: Ops,View File}. Viewing a file that is a directory runs Dired on that
4954: directory.@refill
4955: @end table
4956:
4957: @node Misc File Ops,, Dired, Files
4958: @section Miscellaneous File Operations
4959:
4960: Emacs has commands for performing many other operations on files.
4961:
4962: @findex view-file
4963: @cindex viewing
4964: @kbd{M-x view-file} allows you to scan or read a file by sequential
4965: screenfuls. It reads a file name argument using the minibuffer. After
4966: reading the file into an Emacs buffer, @code{view-file} reads and displays
4967: one windowful. You can then type @key{SPC} to scroll forward one windowful,
4968: or @key{DEL} to scroll backward. Various other commands are provided for
4969: moving around in the file, but none for changing it; type @kbd{C-h} while
4970: viewing for a list of them. They are mostly the same as normal Emacs
4971: cursor motion commands. To exit from viewing, type @kbd{C-c}.
4972:
4973: @findex insert-file
4974: @kbd{M-x insert-file} inserts the contents of the specified file into the
4975: current buffer at point, leaving point unchanged before the contents and
4976: the mark after them. @xref{Mark}.
4977:
4978: @findex write-region
4979: @findex append-to-file
4980: @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it copies
4981: the contents of the region into the specified file. @kbd{M-x append-to-file}
4982: adds the text of the region to the end of the specified file.
4983:
4984: @findex delete-file
4985: @cindex deletion (of files)
4986: @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
4987: command in the shell. If you are deleting many files in one directory, it
4988: may be more convenient to use Dired (@pxref{Dired}).
4989:
4990: @findex rename-file
4991: @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
4992: the minibuffer, then renames file @var{old} as @var{new}. If a file named
4993: @var{new} already exists, you must confirm with `yes' or renaming is not
4994: done; this is because renaming causes the old meaning of the name @var{new}
4995: to be lost. If @var{old} and @var{new} are on different file systems, the
4996: file @var{old} is copied and deleted.
4997:
4998: @findex add-name-to-file
4999: The similar command @kbd{M-x add-name-to-file} is used to add an
5000: additional name to an existing file without removing its old name.
5001: The new name must belong on the same file system that the file is on.
5002:
5003: @findex copy-file
5004: @kbd{M-x copy-file} reads the file @var{old} and writes a new file named
5005: @var{new} with the same contents. Confirmation is required if a file named
5006: @var{new} already exists, because copying has the consequence of overwriting
5007: the old contents of the file @var{new}.
5008:
5009: @findex make-symbolic-link
5010: @kbd{M-x make-symbolic-link} reads two file names @var{old} and @var{linkname},
5011: and then creates a symbolic link named @var{linkname} and pointing at @var{old}.
5012: The effect is that future attempts to open file @var{linkname} will refer
5013: to whatever file is named @var{old} at the time the opening is done, or
5014: will get an error if the name @var{old} is not in use at that time.
5015: Confirmation is required when creating the link if @var{linkname} is in
5016: use. Note that not all systems support symbolic links.
5017:
5018: @node Buffers, Windows, Files, Top
5019: @chapter Using Multiple Buffers
5020:
5021: @cindex buffers
5022: The text you are editing in Emacs resides in an object called a
5023: @dfn{buffer}. Each time you visit a file, a buffer is created to hold the
5024: file's text. Each time you invoke Dired, a buffer is created to hold the
5025: directory listing. If you send a message with @kbd{C-x m}, a buffer named
5026: @samp{*mail*} is used to hold the text of the message. When you ask for a
5027: command's documentation, that appears in a buffer called @samp{*Help*}.
5028:
5029: @cindex selected buffer
5030: @cindex current buffer
5031: At any time, one and only one buffer is @dfn{selected}. It is also
5032: called the @dfn{current buffer}. Often we say that a command operates on
5033: ``the buffer'' as if there were only one; but really this means that the
5034: command operates on the selected buffer (most commands do).
5035:
5036: When Emacs makes multiple windows, each window has a chosen buffer which
5037: is displayed there, but at any time only one of the windows is selected and
5038: its chosen buffer is the selected buffer. Each window's mode line displays
5039: the name of the buffer that the window is displaying (@pxref{Windows}).
5040:
5041: Each buffer has a name, which can be of any length, and you can select
5042: any buffer by giving its name. Most buffers are made by visiting files,
5043: and their names are derived from the files' names. But you can also create
5044: an empty buffer with any name you want. A newly started Emacs has a buffer
5045: named @samp{*scratch*} which can be used for evaluating Lisp expressions in
5046: Emacs. The distinction between upper and lower case matters in buffer
5047: names.
5048:
5049: Each buffer records individually what file it is visiting, whether it is
5050: modified, and what major mode and minor modes are in effect in it
5051: (@pxref{Major Modes}). Any Emacs variable can be made @dfn{local to} a
5052: particular buffer, meaning its value in that buffer can be different from
5053: the value in other buffers. @xref{Locals}.
5054:
5055: @menu
5056: * Select Buffer:: Creating a new buffer or reselecting an old one.
5057: * List Buffers:: Getting a list of buffers that exist.
5058: * Misc Buffer:: Renaming; changing read-onliness; copying text.
5059: * Kill Buffer:: Killing buffers you no longer need.
5060: * Several Buffers:: How to go through the list of all buffers
5061: and operate variously on several of them.
5062: @end menu
5063:
5064: @node Select Buffer, List Buffers, Buffers, Buffers
5065: @section Creating and Selecting Buffers
5066:
5067: @table @kbd
5068: @item C-x b @var{buffer} @key{RET}
5069: Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
5070: @item C-x 4 b @var{buffer} @key{RET}
5071: Similar but select a buffer named @var{buffer} in another window
5072: (@code{switch-to-buffer-other-window}).
5073: @end table
5074:
5075: @kindex C-x 4 b
5076: @findex switch-to-buffer-other-window
5077: @kindex C-x b
5078: @findex switch-to-buffer
5079: To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
5080: @key{RET}}. This is the command @code{switch-to-buffer} with argument
5081: @var{bufname}. Because completion is provided for buffer names, you can
5082: abbreviate the buffer name (@pxref{Completion}). An empty argument to
5083: @kbd{C-x b} specifies the most recently selected buffer that is not
5084: displayed in any window.@refill
5085:
5086: Most buffers are created by visiting files, or by Emacs commands that
5087: want to display some text, but you can also create a buffer explicitly by
5088: typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty buffer which
5089: is not visiting any file, and selects it for editing. Such buffers are
5090: used for making notes to yourself. If you try to save one, you are asked
5091: for the file name to use. The new buffer's major mode is determined by the
5092: value of @code{default-major-mode} (@pxref{Major Modes}).
5093:
5094: Note that @kbd{C-x C-f}, and any other command for visiting a file, can
5095: also be used to switch buffers. @xref{Visiting}.
5096:
5097: @node List Buffers, Misc Buffer, Select Buffer, Buffers
5098: @section Listing Existing Buffers
5099:
5100: @table @kbd
5101: @item C-x C-b
5102: List the existing buffers (@code{list-buffers}).
5103: @end table
5104:
5105: @kindex C-x C-b
5106: @findex list-buffers
5107: To print a list of all the buffers that exist, type @kbd{C-x C-b}.
5108: Each line in the list shows one buffer's name, major mode and visited file.
5109: @samp{*} at the beginning of a line indicates the buffer is ``modified''.
5110: If several buffers are modified, it may be time to save some with @kbd{C-x
5111: s} (@pxref{Saving}). @samp{%} indicates a read-only buffer. @samp{.}
5112: marks the selected buffer. Here is an example of a buffer list:@refill
5113:
5114: @smallexample
5115: MR Buffer Size Mode File
5116: -- ------ ---- ---- ----
5117: .* gmacs.tex 421336 Text /u2/emacs/man/gmacs.tex
5118: *Help* 1287 Fundamental
5119: files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
5120: % RMAIL 64042 RMAIL /u/rms/RMAIL
5121: emacs.tex 383402 Text /u2/emacs/man/emacs.tex
5122: *% man 747 Dired
5123: net.emacs 343885 Fundamental /u/rms/net.emacs
5124: fileio.c 27691 C /u2/emacs/src/fileio.c
5125: NEWS 67340 Text /u2/emacs/etc/NEWS
5126: @end smallexample
5127:
5128: @noindent
5129: Note that the buffer @samp{*Help*} was made by a help request; it is not
5130: visiting any file. The buffer @code{man} was made by Dired on the
5131: directory @file{/u2/emacs/man}.
5132:
5133: @node Misc Buffer, Kill Buffer, List Buffers, Buffers
5134: @section Miscellaneous Buffer Operations
5135:
5136: @table @kbd
5137: @item C-x C-q
5138: Toggle read-only status of buffer (@code{toggle-read-only}).
5139: @item M-x rename-buffer
5140: Change the name of the current buffer.
5141: @item M-x view-buffer
5142: Scroll through a buffer.
5143: @end table
5144:
5145: @cindex read-only buffer
5146: @kindex C-x C-q
5147: @findex toggle-read-only
5148: @vindex buffer-read-only
5149: A buffer can be @dfn{read-only}, which means that commands to change its
5150: text are not allowed. Normally, read-only buffers are made by subsystems
5151: such as Dired and Rmail that have special commands to operate on the text;
5152: a read-only buffer is also made if you visit a file that is protected so
5153: you cannot write it. If you wish to make changes in a read-only buffer,
5154: use the command @kbd{C-x C-q} (@code{toggle-read-only}). It makes a
5155: read-only buffer writable, and makes a writable buffer read-only. This
5156: works by setting the variable @code{buffer-read-only}, which has a local
5157: value in each buffer and makes the buffer read-only if its value is
5158: non-@code{nil}.
5159:
5160: @findex rename-buffer
5161: @kbd{M-x rename-buffer} changes the name of the current buffer. Specify
5162: the new name as a minibuffer argument. There is no default. If you
5163: specify a name that is in use for some other buffer, an error happens and
5164: no renaming is done.
5165:
5166: @findex view-buffer
5167: @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc File Ops})
5168: except that it examines an already existing Emacs buffer. View mode
5169: provides commands for scrolling through the buffer conveniently but not
5170: for changing it. When you exit View mode, the value of point that resulted
5171: from your perusal remains in effect.
5172:
5173: The commands @kbd{C-x a} (@code{append-to-buffer}) and @kbd{M-x
5174: insert-buffer} can be used to copy text from one buffer to another.
5175: @xref{Accumulating Text}.@refill
5176:
5177: @node Kill Buffer, Several Buffers, Misc Buffer, Buffers
5178: @section Killing Buffers
5179:
5180: After you use Emacs for a while, you may accumulate a large number of
5181: buffers. You may then find it convenient to eliminate the ones you no
5182: longer need. There are several commands provided for doing this.
5183:
5184: @c WideCommands
5185: @table @kbd
5186: @item C-x k
5187: Kill a buffer, specified by name (@code{kill-buffer}).
5188: @item M-x kill-some-buffers
5189: Offer to kill each buffer, one by one.
5190: @end table
5191:
5192: @findex kill-buffer
5193: @findex kill-some-buffers
5194: @kindex C-x k
5195:
5196: @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you specify
5197: in the minibuffer. The default, used if you type just @key{RET} in the
5198: minibuffer, is to kill the current buffer. If the current buffer is
5199: killed, another buffer is selected; a buffer that has been selected
5200: recently but does not appear in any window now is chosen to be selected.
5201: If the buffer being killed is modified (has unsaved editing) then you are
5202: asked to confirm with `yes' before the buffer is killed.
5203:
5204: The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
5205: one. An answer of @kbd{y} means to kill the buffer. Killing the current
5206: buffer or a buffer containing unsaved changes selects a new buffer or asks
5207: for confirmation just like @code{kill-buffer}.
5208:
5209: @node Several Buffers,, Kill Buffer, Buffers
5210: @section Operating on Several Buffers
5211: @cindex buffer menu
5212:
5213: The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
5214: you to request operations on various Emacs buffers by editing an Emacs
5215: buffer containing a list of them.
5216:
5217: @table @kbd
5218: @item M-x buffer-menu
5219: Begin editing a buffer listing all Emacs buffers.
5220: @end table
5221:
5222: @findex buffer-menu
5223: The command @code{buffer-menu} writes a list of all Emacs buffers into
5224: the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
5225: mode. The buffer is read-only, and can only be changed through the special
5226: commands described in this section. Most of these commands are graphic
5227: characters. The usual Emacs cursor motion commands can be used in the
5228: @samp{*Buffer List*} buffer. The following special commands apply to the
5229: buffer described on the current line.
5230:
5231: @table @kbd
5232: @item k
5233: Request to kill the buffer. The request shows as a @samp{K} on the
5234: line, before the buffer name. Requested kills take place when the
5235: @kbd{x} command is used.
5236: @item s
5237: Request to save the buffer. The request shows as an @samp{S} on the
5238: line. Requested saves take place when the @kbd{x} command is used.
5239: You may request both saving and killing for one buffer.
5240: @item ~
5241: Mark buffer ``unmodified''. The command @kbd{~} does this,
5242: immediately when typed.
5243: @item x
5244: Perform previously requested kills and saves.
5245: @item u
5246: Remove any request made for the current line.
5247: @item @key{DEL}
5248: Move to previous line and remove any request made for that line.
5249: @end table
5250:
5251: There are also special commands to use the buffer list to select another
5252: buffer, and to specify one or more other buffers for display in additional
5253: windows.
5254:
5255: @table @kbd
5256: @item 1
5257: Select the buffer in a full-screen window. This command takes effect
5258: immediately.
5259: @item 2
5260: Set up two windows, with this buffer in one, and the previously
5261: selected buffer (aside from the buffer @samp{*Buffer List*}) in the
5262: other.
5263: @item q
5264: Select this buffer, and also display in other windows any buffers
5265: previously flagged with the @kbd{m} command. If there are no such
5266: buffers, this command is equivalent to @kbd{1}.
5267: @item m
5268: Flag this buffer to be displayed in another window if the @kbd{q}
5269: command is used. The request shows as a @samp{>} at the beginning of
5270: the line. The same buffer may not have both a kill request and a
5271: display request.
5272: @end table
5273:
5274: All the commands that put in flags to request operations later also move
5275: down a line, and accept a numeric argument as a repeat count.
5276:
5277: The command @kbd{u} cancels any request flagged for the current line, and
5278: moves down; @key{DEL} does so for the previous line, and moves up to it.
5279:
5280: All that @code{buffer-menu} does directly is create and select a suitable
5281: buffer, and turn on Buffer Menu mode. Everything else described above is
5282: implemented by the special commands provided in Buffer Menu mode. One
5283: consequence of this is that you can switch from the @samp{*Buffer List*}
5284: buffer to another Emacs buffer, and edit there. You can reselect the
5285: @code{buffer-menu} buffer later, to perform the operations already
5286: requested, or you can kill it, or pay no further attention to it.
5287:
5288: The only difference between @code{buffer-menu} and @code{list-buffers} is
5289: that @code{buffer-menu} selects the @samp{*Buffer List*} buffer and
5290: @code{list-buffers} does not. If you run @code{list-buffers} (that is,
5291: type @kbd{C-x C-b}) and select the buffer list manually, you can use all of
5292: the commands described here.
5293:
5294: @node Windows, Major Modes, Buffers, Top
5295: @chapter Multiple Windows
5296: @cindex windows
5297:
5298: Emacs can split the screen into two or many windows, which can display
5299: parts of different buffers, or different parts of one buffer.
5300:
5301: When multiple windows are being displayed, each window has an Emacs
5302: buffer designated for display in it. The same buffer may appear in more
5303: than one window; if it does, any changes in its text are displayed in all
5304: the windows where it appears. But the windows showing the same buffer can
5305: show different parts of it, because each window has its own value of point.
5306:
5307: @cindex selected window
5308: At any time, one of the windows is the @dfn{selected window}; the buffer
5309: this window is displaying is the current buffer. The terminal's cursor
5310: shows the location of point in this window. Each other window has a
5311: location of point as well, but since the terminal has only one cursor there
5312: is no way to show where those locations are.
5313:
5314: Commands to move point affect the value of point for the selected Emacs
5315: window only. They do not change the value of point in any other Emacs
5316: window, even one showing the same buffer. The same is true for commands
5317: such as @kbd{C-x b} to change the selected buffer in the selected window;
5318: they do not affect other windows at all. However, there are other commands
5319: such as @kbd{C-x 4 b} that select a different window and switch buffers in
5320: it. Also, all commands that display information in a window, including
5321: (for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
5322: (@code{list-buffers}), work by switching buffers in a nonselected window
5323: without affecting the selected window.
5324:
5325: Each window has its own mode line, which displays the buffer name,
5326: modification status and major and minor modes of the buffer that is
5327: displayed in the window. @xref{Mode Line}, for full details on the mode
5328: line.
5329:
5330: @c WideCommands
5331: @table @kbd
5332: @item C-x 2
5333: Split the selected window in two, one window above the other
5334: (@code{split-window-vertically}).
5335: @item C-x 5
5336: Split the selected window into two windows side by side
5337: (@code{split-window-horizontally}).
5338: @item C-x o
5339: Select another window (@code{other-window}). That is @kbd{o}, not zero.
5340: @item C-x 0
5341: Get rid of the selected window (@code{kill-window}). That is a zero.
5342: @item C-x 1
5343: Get rid of all windows except the selected one (@code{delete-other-windows}).
5344: @item C-x 4
5345: Prefix key for commands to select a buffer in various ways ``in
5346: another window''.
5347: @item C-x ^
5348: Make the selected window taller, at the expense of the other(s)
5349: (@code{enlarge-window}).
5350: @item C-x @}
5351: Make the selected window wider (@code{enlarge-window-horizontally}).
5352: @item C-M-v
5353: Scroll the next window (@code{scroll-other-window}).
5354: @item M-x compare-windows
5355: Find next place where the text in the selected window does not match
5356: the text in the next window.
5357: @end table
5358:
5359: @kindex C-x 2
5360: @findex split-window-vertically
5361: The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the
5362: selected window into two windows, one above the other. Both windows start
5363: out displaying the same buffer, with the same value of point. By default
5364: the two windows each get half the height of the window that was split; a
5365: numeric argument specifies how many lines to give to the top window.
5366:
5367: @kindex C-x 5
5368: @findex split-window-horizontally
5369: @kbd{C-x 5} (@code{split-window-horizontally}) breaks the selected
5370: window into two side-by-side windows. A numeric argument specifies
5371: how many columns to give the one on the left. A line of vertical bars
5372: separates the two windows. Windows that are not the full width of the
5373: screen have mode lines, but they are truncated; also, they do not
5374: always appear in inverse video, because, the Emacs display routines
5375: have not been taught how to display a region of inverse video that is
5376: only part of a line on the screen.
5377:
5378: @vindex truncate-partial-width-windows
5379: When a window is less than the full width, text lines too long to fit are
5380: frequent. Continuing all those lines might be confusing. The variable
5381: @code{truncate-partial-width-windows} can be set non-@code{nil} to force
5382: truncation in all windows less than the full width of the screen,
5383: independent of the buffer being displayed and its value for
5384: @code{truncate-lines}. @xref{Continuation Lines}.@refill
5385:
5386: Horizontal scrolling is often used in side-by-side windows.
5387: @xref{Display}.
5388:
5389: @kindex C-x o
5390: @findex other-window
5391: To select a different window, use @kbd{C-x o} (@code{other-window}).
5392: That is an @kbd{o}, for `other', not a zero. When there are more than two
5393: windows, this command moves through all the windows in a cyclic order,
5394: generally top to bottom and left to right. From the rightmost and
5395: bottommost window, it goes back to the one at the upper left corner. A
5396: numeric argument means to move several steps in the cyclic order of
5397: windows. A negative argument moves around the cycle in the opposite order.
5398: When the minibuffer is active, the minibuffer is the last window in the
5399: cycle; you can switch from the minibuffer window to one of the other
5400: windows, and later switch back and finish supplying the minibuffer argument
5401: that is requested. @xref{Minibuffer Edit}.
5402:
5403: @kindex C-M-v
5404: @findex scroll-other-window
5405: The usual scrolling commands (@pxref{Display}) apply to the selected
5406: window only, but there is one command to scroll the next window.
5407: @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that @kbd{C-x o}
5408: would select. The kind of scrolling done is the same as for @kbd{C-v}.
5409:
5410: @kindex C-x 0
5411: @findex delete-window
5412: To delete a window, type @kbd{C-x 0} (@code{delete-window}). The space
5413: it used to occupy is distributed among the other active windows (but not
5414: the minibuffer window, even if that is active at the time). Once a window
5415: is deleted, everything about it is forgotten; there is no automatic way to
5416: make another window showing the same contents.
5417:
5418: @kindex C-x 1
5419: @findex delete-other-windows
5420: @kbd{C-x 1} (@code{delete-other-windows}) is more powerful than @kbd{C-x 0};
5421: it deletes all the windows except the selected one (and the minibuffer);
5422: the selected window expands to use the whole screen except for the echo
5423: area.
5424:
5425: @kindex C-x ^
5426: @findex enlarge-window
5427: @kindex C-x @}
5428: @findex enlarge-window-horizontally
5429: @vindex window-min-height
5430: @vindex window-min-width
5431: To readjust the division of space among existing windows, use @kbd{C-x ^}
5432: (@code{enlarge-window}). It makes the currently selected window get one
5433: line bigger, or as many lines as is specified with a numeric argument.
5434: With a negative argument, it makes the selected window smaller. @kbd{C-x
5435: @}} (@code{enlarge-window-horizontally}) makes the selected window wider
5436: by the specified number of columns. The extra screen space given to a
5437: window comes from one of its neighbors, if that is possible; otherwise, all
5438: the competing windows are shrunk in the same proportion. If this makes any
5439: windows too small, those windows are deleted and their space is divided up.
5440: The minimum size is specified by the variables @code{window-min-height} and
5441: @code{window-min-width}.
5442:
5443: @findex compare-windows
5444: The command @kbd{M-x compare-windows} compares the text in the current
5445: window with that in the next window (the one @kbd{C-M-v} would scroll).
5446: Comparison starts at point in each window. Point moves forward in each
5447: window, a character at a time in each window, until the next characters
5448: in the two windows are different. Then the command is finished.
5449:
5450: @kindex C-x 4
5451: @kbd{C-x 4} is a prefix key for commands that select another window
5452: (splitting the window if there is only one) and select a buffer in that
5453: window. Different @kbd{C-x 4} commands have different ways of finding the
5454: buffer to select.
5455:
5456: @findex switch-to-buffer-other-window
5457: @findex find-file-other-window
5458: @findex find-tag-other-window
5459: @findex dired-other-window
5460: @findex mail-other-window
5461: @table @kbd
5462: @item C-x 4 b @var{bufname} @key{RET}
5463: Select buffer @var{bufname} in another window. This runs
5464: @code{switch-to-buffer-other-window}.
5465: @item C-x 4 f @var{filename} @key{RET}
5466: Visit file @var{filename} and select its buffer in another window. This
5467: runs @code{find-file-other-window}. @xref{Visiting}.
5468: @item C-x 4 d @var{directory} @key{RET}
5469: Select a Dired buffer for directory @var{directory} in another window.
5470: This runs @code{dired-other-window}. @xref{Dired}.
5471: @item C-x 4 m
5472: Start composing a mail message in another window. This runs
5473: @code{mail-other-window}, and its same-window version is @kbd{C-x m}
5474: (@pxref{Sending Mail}).
5475: @item C-x 4 .
5476: Find a tag in the current tag table in another window. This runs
5477: @code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
5478: (@pxref{Tags}).
5479: @end table
5480:
5481: @node Major Modes, Indentation, Windows, Top
5482: @chapter Major Modes
5483: @cindex major modes
5484: @kindex TAB
5485: @kindex DEL
5486: @kindex LFD
5487:
5488: Emacs has many different @dfn{major modes}, each of which customizes
5489: Emacs for editing text of a particular sort. The major modes are mutually
5490: exclusive, and each buffer has one major mode at any time. The mode line
5491: normally contains the name of the current major mode, in parentheses.
5492: @xref{Mode Line}.
5493:
5494: The least specialized major mode is called @dfn{Fundamental mode}. This
5495: mode has no mode-specific redefinitions or variable settings, so that each
5496: Emacs command behaves in its most general manner, and each option is in its
5497: default state. For editing any specific type of text, such as Lisp code or
5498: English text, you should switch to the appropriate major mode, such as Lisp
5499: mode or Text mode.
5500:
5501: Selecting a major mode changes the meanings of a few keys to become more
5502: specifically adapted to the language being edited. The ones which are
5503: changed frequently are @key{TAB}, @key{DEL}, and @key{LFD}. In addition,
5504: the commands which handle comments use the mode to determine how comments
5505: are to be delimited. Many major modes redefine the syntactical properties
5506: of characters appearing in the buffer. @xref{Syntax}.
5507:
5508: The major modes fall into three major groups. Lisp mode (which has
5509: several variants), C mode and Muddle mode are for specific programming
5510: languages. Text mode, Nroff mode, @TeX{} mode and outline mode are for
5511: editing English text. The remaining major modes are not intended for use
5512: on user's files; they are used in buffers created for specific purposes by
5513: Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), and
5514: Mail mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), and Shell
5515: mode for buffers used for communicating with an inferior shell process
5516: (@pxref{Shell}).
5517:
5518: Selecting a new major mode is done with an @kbd{M-x} command. From the
5519: name of a major mode, add @code{-mode} to get the name of a command
5520: function to select that mode. Thus, you can enter Lisp mode by executing
5521: @kbd{M-x lisp-mode}.
5522:
5523: @vindex auto-mode-alist
5524: When you visit a file, Emacs usually chooses the right major mode based
5525: on the file's name. For example, files whose names end in @code{.c} are
5526: edited in C mode. The correspondence between file names and major mode is
5527: controlled by the variable @code{auto-mode-alist}. Its value is a list in
5528: which each element has the form
5529:
5530: @example
5531: (@var{regexp} . @var{mode-function})
5532: @end example
5533:
5534: @noindent
5535: For example, one element normally found in the list has the form
5536: @code{(@t{"\\.c$"} . c-mode)}, and it is responsible for selecting C mode
5537: for files whose names end in @code{.c}. (Note that @samp{\\} is needed in
5538: Lisp syntax to include a @samp{\} in the string.)
5539:
5540: You can specify which major mode should be used for editing a certain
5541: file by a special sort of text in the first nonblank line of the file. The
5542: mode name should appear in this line both preceded and followed by
5543: @samp{-*-}. Other text may appear on the line as well. For example,
5544:
5545: @example
5546: ;-*-Lisp-*-
5547: @end example
5548:
5549: @noindent
5550: tells Emacs to use Lisp mode. Note how the semicolon is used to make Lisp
5551: treat this line as a comment. Such an explicit specification overrides any
5552: defaulting based on the file name.
5553:
5554: Another format of mode specification is
5555:
5556: @example
5557: -*-Mode: @var{modename};-*-
5558: @end example
5559:
5560: @noindent
5561: which allows other things besides the major mode name to be specified.
5562: However, Emacs does not look for anything except the mode name.
5563:
5564: @vindex default-major-mode
5565: When a file is visited that does not specify a major mode to use, or when
5566: a new buffer is created with @kbd{C-x b}, the major mode used is that
5567: specified by the variable @code{default-major-mode}. Normally this value
5568: is the symbol @code{fundamental-mode}, which specifies Fundamental mode.
5569: If @code{default-major-mode} is @code{nil}, the major mode is taken from
5570: the previously selected buffer.
5571:
5572: Most programming language major modes specify that only blank lines
5573: separate paragraphs. This is so that the paragraph commands remain useful.
5574: @xref{Paragraphs}. They also cause Auto Fill mode to use the definition of
5575: @key{TAB} to indent the new lines it creates. This is because most lines
5576: in a program are usually indented. @xref{Indentation}.
5577:
5578: @node Indentation, Text, Major Modes, Top
5579: @chapter Indentation
5580: @cindex indentation
5581:
5582: @c WideCommands
5583: @table @kbd
5584: @item @key{TAB}
5585: Indent current line ``appropriately'' in a mode-dependent fashion.
5586: @item @key{LFD}
5587: Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
5588: @item M-^
5589: Merge two lines (@code{delete-indentation}). This would cancel out
5590: the effect of @key{LFD}.
5591: @item C-M-o
5592: Split line at point; text on the line after point becomes a new line
5593: indented to the same column that it now starts in (@code{split-line}).
5594: @item M-m
5595: Move (forward or back) to the first nonblank character on the current
5596: line (@code{back-to-indentation}).
5597: @item C-M-\
5598: Indent several lines to same column (@code{indent-region}).
5599: @item C-x @key{TAB}
5600: Shift block of lines rigidly right or left (@code{indent-rigidly}).
5601: @item M-i
5602: Indent from point to the next prespecified tab stop column
5603: (@code{tab-to-tab-stop}).
5604: @item M-x indent-relative
5605: Indent from point to under an indentation point in the previous line.
5606: @end table
5607:
5608: @kindex TAB
5609: @cindex indentation
5610: Most programming languages have some indentation convention. For Lisp
5611: code, lines are indented according to their nesting in parentheses. The
5612: same general idea is used for C code, though many details are different.
5613:
5614: Whatever the language, to indent a line, use the @key{TAB} command. Each
5615: major mode defines this command to perform the sort of indentation
5616: appropriate for the particular language. In Lisp mode, @key{TAB} aligns
5617: the line according to its depth in parentheses. No matter where in the
5618: line you are when you type @key{TAB}, it aligns the line as a whole. In C
5619: mode, @key{TAB} implements a subtle and sophisticated indentation style that
5620: knows about many aspects of C syntax.
5621:
5622: @kindex TAB
5623: @kindex LFD
5624: @findex indent-new-line
5625: In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
5626: indents to the next tab stop column. You can set the tab stops with
5627: @kbd{M-x edit-tab-stops}.
5628:
5629: @menu
5630: * Indentation Commands:: Various commands and techniques for indentation.
5631: * Tab Stops:: You can set arbitrary "tab stops" and then
5632: indent to the next tab stop when you want to.
5633: * Just Spaces:: You can request indentation using just spaces.
5634: @end menu
5635:
5636: @node Indentation Commands,, Indentation, Indentation
5637: @section Indentation Commands and Techniques
5638: @c ??? Explain what Emacs has instead of space-indent-flag.
5639:
5640: If you just want to insert a tab character in the buffer, you can type
5641: @kbd{C-q @key{TAB}}.
5642:
5643: @kindex M-m
5644: @findex back-to-indentation
5645: To move over the indentation on a line, do @kbd{Meta-m}
5646: (@code{back-to-indentation}). This command, given anywhere on a line,
5647: positions point at the first nonblank character on the line.
5648:
5649: To insert an indented line before the current line, do @kbd{C-a C-o
5650: @key{TAB}}. To make an indented line after the current line, use @kbd{C-e
5651: @key{LFD}}.
5652:
5653: @kindex C-M-o
5654: @findex split-line
5655: @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
5656: the line vertically down, so that the current line becomes two lines.
5657: @kbd{C-M-o} first moves point forward over any spaces and tabs. Then it
5658: inserts after point a newline and enough indentation to reach the same
5659: column point is on. Point remains before the inserted newline; in this
5660: regard, @kbd{C-M-o} resembles @kbd{C-o}.
5661:
5662: @kindex M-\
5663: @kindex M-^
5664: @findex delete-horizontal-space
5665: @findex delete-indentation
5666: To join two lines cleanly, use the @kbd{Meta-^} (@code{delete-indentation})
5667: command to delete the indentation at the front of the current line, and the
5668: line boundary as well. They are replaced by a single space, or by no space
5669: if at the beginning of a line or before a @samp{)} or after a @samp{(}. To
5670: delete just the indentation of a line, go to the beginning of the line and
5671: use @kbd{Meta-\} (@code{delete-horizontal-space}), which deletes all spaces
5672: and tabs around the cursor.
5673:
5674: @kindex C-M-\
5675: @kindex C-x TAB
5676: @findex indent-region
5677: @findex indent-rigidly
5678: There are also commands for changing the indentation of several lines at
5679: once. @kbd{Control-Meta-\} (@code{indent-region}) gives each line which
5680: begins in the region the ``usual'' indentation by invoking @key{TAB} at the
5681: beginning of the line. A numeric argument specifies the column to indent
5682: to, and each line is shifted left or right so that its first nonblank
5683: character appears in that column. @kbd{C-x @key{TAB}}
5684: (@code{indent-rigidly}) moves all of the lines in the region right by its
5685: argument (left, for negative arguments). The whole group of lines moves
5686: rigidly sideways, which is how the command gets its name.@refill
5687:
5688: @findex indent-relative
5689: @kbd{M-x indent-relative} indents at point based on the previous line
5690: (actually, the last nonempty line.) It inserts whitespace at point, moving
5691: point, until it is underneath an indentation point in the previous line.
5692: An indentation point is the end of a sequence of whitespace or the end of
5693: the line. If point is farther right than any indentation point in the
5694: previous line, the whitespace before point is deleted and the first
5695: indentation point then applicable is used. If no indentation point is
5696: applicable even then, @code{tab-to-tab-stop} is run.
5697:
5698: @code{indent-relative} is the definition of @key{TAB} in Indented Text
5699: mode. @xref{Text}.
5700:
5701: @node Tab Stops, Just Spaces, Indentation Commands, Indentation
5702: @section Tab Stops
5703:
5704: @kindex M-i
5705: @findex tab-to-tab-stop
5706: For typing in tables, you can use Text mode's definition of @key{TAB},
5707: @code{tab-to-tab-stop}. This command inserts indentation before point,
5708: enough to reach the next tab stop column. If you are not in Text mode,
5709: this function can be found on @kbd{M-i} anyway.
5710:
5711: @findex edit-tab-stops
5712: @findex edit-tab-stops-note-changes
5713: @kindex C-x C-s
5714: @vindex tab-stop-list
5715: The tab stops used by @kbd{M-i} can be set arbitrarily by the user.
5716: They are stored in a variable called @code{tab-stop-list}, as a list of
5717: column-numbers in increasing order.
5718:
5719: The convenient way to set the tab stops using @kbd{M-x edit-tab-stops},
5720: which creates and selects a buffer containing a description of the tab stop
5721: settings. You can edit this buffer to specify different tab stops, and
5722: then type @kbd{C-x C-s} to make those new tab stops take effect. In the
5723: tab stop buffer, @kbd{C-x C-s} runs the function
5724: @code{edit-tab-stops-note-changes} rather than its usual definition
5725: @code{save-buffer}. @code{edit-tab-stops} records which buffer was current
5726: when you invoked it, and stores the tab stops back in that buffer; normally
5727: all buffers share the same tab stops and changing them in one buffer
5728: affects all, but if you happen to make @code{tab-stop-list} local in one
5729: buffer then @code{edit-tab-stops} in that buffer will edit the local
5730: settings.
5731:
5732: Here is what the text representing the tab stops looks like for ordinary
5733: tab stops every eight columns.
5734:
5735: @example
5736: : : : : : :
5737: 0 1 2 3 4
5738: 0123456789012345678901234567890123456789012345678
5739: To install changes, type C-x C-s
5740: @end example
5741:
5742: The first line contains a colon at each tab stop. The remaining lines
5743: are present just to help you see where the colons are and know what to do.
5744:
5745: Note that the tab stops that control @code{tab-to-tab-stop} have nothing
5746: to do with displaying tab characters in the buffer. @xref{Display Vars},
5747: for more information on that.
5748:
5749: @node Just Spaces,, Tab Stops, Indentation
5750: @section Tabs vs. Spaces
5751:
5752: @vindex indent-tabs-mode
5753: Emacs normally uses both tabs and spaces to indent lines. If you prefer,
5754: all indentation can be made from spaces only. To request this, set
5755: @code{indent-tabs-mode} to @code{nil}.
5756:
5757: @findex tabify
5758: @findex untabify
5759: There are also commands to convert tabs to spaces or vice versa, always
5760: preserving the columns of all nonblank text. @kbd{M-x tabify} scans the
5761: region for sequences of spaces, and converts sequences of at least three
5762: spaces to tabs if that can be done without changing indentation. @kbd{M-x
5763: untabify} changes all tabs in the region to appropriate numbers of spaces.
5764:
5765: @node Text, Programs, Indentation, Top
5766: @chapter Commands for Human Languages
5767: @cindex text
5768:
5769: The term @dfn{text} has two widespread meanings in our area of the
5770: computer field. One is data that is a sequence of characters. Any file
5771: that you edit with Emacs is text, in this sense of the word. The other
5772: meaning is more restrictive; it is, a sequence of characters in a human
5773: language for humans to read (possibly after processing by a text
5774: formatter), as opposed to a program or commands for a program.
5775:
5776: Human languages have syntactic/stylistic conventions that can be
5777: supported or used to advantage by editor commands: conventions involving
5778: words, sentences, paragraphs, and capital letters. This chapter describes
5779: Emacs commands for all of these things. There are also commands for
5780: @dfn{filling}, or rearranging paragraphs into lines of approximately equal
5781: length.
5782:
5783: The commands for moving over and killing words (@pxref{Words}), sentences
5784: (@pxref{Sentences}) and paragraphs (@pxref{Paragraphs}) are are primarily
5785: intended for human-language text, but are very often useful in editing
5786: programs also.
5787:
5788: Emacs has several major modes for editing human language text.
5789: If the file contains text pure and simple, use Text mode, which customizes
5790: Emacs in small ways for the syntactic conventions of text. For text which
5791: contains embedded commands for text formatters, Emacs has other major modes,
5792: each for a particular text formatter. Thus, for input to @TeX{}, you would
5793: use @TeX{} mode; for input to nroff, Nroff mode.
5794:
5795: @menu
5796: * Text Mode:: The major modes for editing text files.
5797: * Nroff Mode:: The major mode for editing input to the formatter nroff.
5798: * TeX Mode:: The major mode for editing input to the formatter TeX.
5799: * Outline Mode::The major mode for editing outlines.
5800: * Words:: Moving over and killing words.
5801: * Sentences:: Moving over and killing sentences.
5802: * Paragraphs:: Moving over paragraphs.
5803: * Pages:: Moving over pages.
5804: * Filling:: Filling or justifying text
5805: * Case:: Changing the case of text
5806: @end menu
5807:
5808: @node Text Mode, Words, Text, Text
5809: @section Text Mode
5810:
5811: @findex tab-to-tab-stop
5812: @findex edit-tab-stops
5813: @cindex Text mode
5814: @kindex TAB
5815: @findex text-mode
5816: Editing files of text in a human language ought to be done using Text
5817: mode rather than Lisp or Fundamental mode. Invoke @kbd{M-x text-mode} to
5818: enter Text mode. In Text mode, @key{TAB} runs the function
5819: @code{tab-to-tab-stop}, which allows you to use arbitrary tab stops set
5820: with @kbd{M-x edit-tab-stops} (@pxref{Tab Stops}). Features concerned with
5821: comments in programs are turned off except when explicitly invoked. The
5822: syntax table is changed so that periods are not considered part of a word,
5823: while apostrophes, backspaces and underlines are.
5824:
5825: @findex indented-text-mode
5826: A similar variant mode is Indented Text mode, intended for editing text
5827: in which most lines are indented. This mode defines @key{TAB} to run
5828: @code{indent-relative} (@pxref{Indentation}), and makes Auto Fill indent
5829: the lines it creates. The result is that normally a line made by Auto
5830: Filling, or by @key{LFD}, is indented just like the previous line. Use
5831: @kbd{M-x indented-text-mode} to select this mode.
5832:
5833: @vindex text-mode-hook
5834: Entering Text mode or Indented Text mode calls with no arguments the
5835: value of the variable @code{text-mode-hook}, if that value exists and is
5836: not @code{nil}. This value is also called when modes related to Text mode
5837: are entered; this includes Nroff mode, @TeX{} mode, Outline mode and Mail
5838: mode. Your hook can look at the value of @code{major-mode} to see which of
5839: these modes is actually being entered.
5840:
5841: @menu
5842: Two modes similar to Text mode are of use for editing text that is to
5843: be passed through a text formatter before achieving the form in which
5844: humans are to read it.
5845:
5846: * Nroff Mode:: The major mode for editing input to the formatter nroff.
5847: * TeX Mode:: The major mode for editing input to the formatter TeX.
5848:
5849: Another similar mode is used for editing outlines. It allows you
5850: to view the text at various levels of detail. You can view either
5851: the outline headings alone or both headings and text; you can also
5852: hide some of the headings at lower levels from view to make the high
5853: level structure more visible.
5854:
5855: * Outline Mode::The major mode for editing outlines.
5856: @end menu
5857:
5858: @node Nroff Mode, TeX Mode, Text Mode, Text Mode
5859: @subsection Nroff Mode
5860:
5861: @findex nroff-mode
5862: Nroff mode is a mode like Text mode but modified to handle nroff commands
5863: present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It
5864: differs from Text mode in only a few ways. All nroff command lines are
5865: considered paragraph separators, so that filling will never garble the
5866: nroff commands. Pages are separated by @samp{.bp} commands. Also, three
5867: special commands are provided that are not in Text mode:
5868:
5869: @findex forward-text-line
5870: @findex backward-text-line
5871: @findex count-text-lines
5872: @kindex M-n
5873: @kindex M-p
5874: @kindex M-?
5875: @table @kbd
5876: @item M-n
5877: Move to the beginning of the next line that isn't an nroff command
5878: (@code{forward-text-line}). An argument is a repeat count.
5879: @item M-p
5880: Like @kbd{M-n} but move up (@code{backward-text-line}).
5881: @item M-?
5882: Prints in the echo area the number of text lines (lines that are not
5883: nroff commands) in the region (@code{count-text-lines}).
5884: @end table
5885:
5886: @findex electric-nroff-mode
5887: The other feature of Nroff mode is that you can turn on Electric
5888: Nroff newline mode. This is a minor mode that you can turn on or off
5889: with @kbd{M-x electric-nroff-mode} (@pxref{Minor Modes}). When the
5890: mode is on, each time you use @key{RET} to end a line that contains
5891: an nroff command that opens a kind of grouping, the matching
5892: nroff command to close that grouping is automatically inserted on
5893: the following line. For example, if you are at the beginning of
5894: a line and type @kbd{.@: ( b @key{RET}}, the matching command
5895: @samp{.)b} will be inserted on a new line following point.
5896:
5897: @vindex nroff-mode-hook
5898: Entering Nroff mode calls with no arguments the value of the variable
5899: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
5900: does the same with the variable @code{nroff-mode-hook}.
5901:
5902: @node TeX Mode, Outline Mode, Nroff Mode, Text Mode
5903: @subsection @TeX{} Mode
5904: @cindex TeX
5905: @cindex LaTeX
5906: @findex TeX-mode
5907: @findex tex-mode
5908:
5909: @TeX{} is an extremely powerful text formatter written by Donald Knuth;
5910: it is also free, like GNU Emacs. La@TeX{} is a simplified input format for
5911: @TeX{}, implemented by @TeX{} macros. It comes with @TeX{}.@refill
5912:
5913: @TeX{} mode is designed for editing files of input for plain @TeX{} or La@TeX{}.
5914: It provides facilities for checking the balance of delimiters and for
5915: invoking @TeX{} on all or part of the file. Type @kbd{M-x tex-mode} to
5916: enter @TeX{} mode.
5917:
5918: @table @kbd
5919: @item "
5920: Insert @samp{@`@`}, @samp{"} or @samp{@'@'} according to context (@code{TeX-insert-quote}).
5921: @item @key{LFD}
5922: Insert a paragraph break (two newlines) and check the previous
5923: paragraph for unbalanced braces or dollar signs
5924: (@code{TeX-terminate-paragraph}).
5925: @item M-x validate-TeX-buffer
5926: Check each paragraph in the buffer for unbalanced braces or dollar signs.
5927: @item M-@{
5928: Insert @samp{@{@}} and position point between them (@code{TeX-insert-braces}).
5929: @item M-@}
5930: Move forward past the next unmatched close brace (@code{up-list}).
5931: @item C-c C-r
5932: Invoke @TeX{} on the current region, plus the buffer's header
5933: (@code{TeX-region}).
5934: @item C-c C-b
5935: Invoke @TeX{} on the entire current buffer (@code{TeX-buffer}).
5936: @item C-c C-p
5937: Print the output from the last @kbd{C-c C-r} or @kbd{C-c C-b} command
5938: (@code{TeX-print}).
5939: @end table
5940:
5941: @findex TeX-insert-quote
5942: @kindex " (TeX mode)
5943: In @TeX{}, the character @samp{"} is not normally used; one uses @samp{``}
5944: to start a quotation and @samp{''} to end one. @TeX{} mode defines the key
5945: @kbd{"} to insert @samp{``} after whitespace or an open brace, @samp{"}
5946: after a backslash, or @samp{''} otherwise. This is done by the command
5947: @code{TeX-insert-quote}. If you need the character @samp{"} itself in
5948: unusual contexts, use @kbd{C-q} to insert it. Also, @kbd{"} with a
5949: numeric argument always inserts that number of @samp{"} characters.
5950:
5951: In @TeX{} mode, @samp{$} has a special syntax code which attempts to
5952: understand the way @TeX{} math mode delimiters match. When you insert a
5953: @samp{$} that is meant to exit math mode, the position of the matching
5954: @samp{$} that entered math mode is displayed for a second. This is the
5955: same feature that displays the open brace that matches a close brace that
5956: is inserted. However, there is no way to tell whether a @samp{$} enters
5957: math mode or leaves it; so when you insert a @samp{$} that enters math
5958: mode, the previous @samp{$} position is shown as if it were a match, even
5959: though they are actually unrelated.
5960:
5961: @findex TeX-insert-braces
5962: @kindex M-@{
5963: @findex up-list
5964: @kindex M-@}
5965: If you prefer to keep braces balanced at all times, you can use @kbd{M-@{}
5966: (@code{TeX-insert-braces}) to insert a pair of braces. It leaves point
5967: between the two braces so you can insert the text that belongs inside.
5968: Afterward, use the command @kbd{M-@}} (@code{up-list}) to move forward
5969: past the close brace.
5970:
5971: @findex validate-TeX-buffer
5972: @findex TeX-terminate-paragraph
5973: @kindex LFD (TeX mode)
5974: There are two commands for checking the matching of braces. @key{LFD}
5975: (@code{TeX-terminate-paragraph}) checks the paragraph before point, and
5976: inserts two newlines to start a new paragraph. It prints a message in the
5977: echo area if any mismatch is found. @kbd{M-x validate-TeX-buffer} checks
5978: the entire buffer, paragraph by paragraph. When it finds a paragraph that
5979: contains a mismatch, it displays point at the beginning of the paragraph
5980: for a few seconds and pushes a mark at that spot. Scanning continues
5981: until the whole buffer has been checked or until you type another key.
5982: The positions of the last several paragraphs with mismatches can be
5983: found in the mark ring (@pxref{Mark Ring}).
5984:
5985: Note that square brackets and parentheses are matched in @TeX{} mode, not
5986: just braces. This is wrong for the purpose of checking @TeX{} syntax.
5987: However, parentheses and square brackets are likely to be used in text as
5988: matching delimiters and it is useful for the various motion commands and
5989: automatic match display to work with them.
5990:
5991: @findex TeX-buffer
5992: @kindex C-c C-b
5993: @findex TeX-print
5994: @kindex C-c C-p
5995: You can pass the current buffer through an inferior @TeX{} by means of
5996: @kbd{C-c C-b} (@code{TeX-buffer}). The error messages appear in a buffer
5997: called @samp{*TeX-shell*}. The formatted output appears in a file in
5998: @file{/tmp}; to print it, type @kbd{C-c C-p} (@code{TeX-print}).@refill
5999:
6000: @findex TeX-region
6001: @kindex C-c C-r
6002: You can also pass an arbitrary region through an inferior @TeX{} by typing
6003: @kbd{C-c C-r} (@code{TeX-region}). This is tricky, however, because most files
6004: of @TeX{} input contain commands at the beginning to set paramaters and
6005: define macros, without which no later part of the file will format
6006: correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a
6007: part of the file as containing essential commands; it is included before
6008: the specified region as part of the input to @TeX{}. The designated part
6009: of the file is called the @dfn{header}.
6010:
6011: @cindex header (TeX mode)
6012: To indicate the bounds of the header, insert two special strings in the
6013: file. Insert @samp{%**start of header} before the header, and @samp{%**end of
6014: header} after it. Each string must appear entirely on one line, but there
6015: may be other text on the line before or after. The lines containing the
6016: two strings are not included in the header.
6017:
6018: If @samp{%**start of header} does not appear within the first ten lines of
6019: the text in the buffer, @kbd{C-c C-r} assumes that there is no header.
6020:
6021: @vindex TeX-mode-hook
6022: Entering @TeX{} mode calls with no arguments the value of the variable
6023: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
6024: does the same with the variable @code{TeX-mode-hook}.
6025:
6026: @TeX{} for Berkeley Unix can be obtained on a 1600bpi tar tape for a $75
6027: distribution fee from
6028:
6029: @display
6030: Pierre MacKay
6031: Department of Computer Science, FR-35
6032: University of Washington
6033: Seattle, WA 98195
6034: @end display
6035:
6036: @noindent
6037: It would work on system V as well if that version of Unix had a reasonable
6038: Pascal compiler. Outside the U.S., add $10 to cover extra costs.
6039:
6040: @node Outline Mode,, TeX Mode, Text Mode
6041: @subsection Outline Mode
6042: @cindex outlines
6043: @cindex selective display
6044: @cindex invisible lines
6045:
6046: Outline mode is a major mode much like Text mode but intended for editing
6047: outlines. It allows you to make parts of the text temporarily invisible
6048: to that you can see just the overall structure of the outline. Type
6049: @kbd{M-x outline-mode} to turn on Outline mode in the current buffer.
6050:
6051: When a line is invisible in outline mode, it does not appear on the
6052: screen in any form. The screen appears exactly as if the invisible line
6053: were deleted. All editing commands treat the text of the invisible line as
6054: part of the previous visible line. For example, @kbd{C-n} moves onto the
6055: next visible line. Killing an entire visible line, including its
6056: terminating newline, really kills all the following invisible lines along
6057: with it; yanking it all back yanks the invisible lines and they remain
6058: invisible.
6059:
6060: @cindex heading lines (Outline mode)
6061: @cindex body lines (Outline mode)
6062: Outline mode assumes that the lines in the buffer are of two types:
6063: @dfn{heading lines} and @dfn{body lines}. A heading line represents a topic in the
6064: outline. Heading lines start with one or more stars; the number of stars
6065: determines the depth of the heading in the outline structure. Thus, a
6066: heading line with one star is a major topic; all the heading lines with
6067: two stars between it and the next one-star heading are its subtopics; and
6068: so on. Any line that is not a heading line is a body line. Body lines
6069: belong to the preceding heading line. Here is an example:
6070:
6071: @example
6072: * Food
6073:
6074: This is the body,
6075: which says something about the topic of food.
6076:
6077: ** Delicious Food
6078:
6079: This is the body of the second-level header.
6080:
6081: ** Distasteful Food
6082:
6083: This could have
6084: a body too, with
6085: several lines.
6086:
6087: *** Dormitory Food
6088:
6089: * Shelter
6090:
6091: A second first-level topic with its header line.
6092: @end example
6093:
6094:
6095: A heading line together with all following body lines are called
6096: collectively an @dfn{entry}. A heading line together with all following
6097: deeper heading lines and their body lines is called a @dfn{subtree}.
6098:
6099: @table @kbd
6100: @item M-@}
6101: Move point to the next visible heading line (@code{next-visible-heading}).
6102: @item M-@{
6103: Move point to the previous visible heading line
6104: (@code{previous-visible-heading}).
6105: @item M-x hide-body
6106: Make all body lines in the buffer invisible.
6107: @item M-x show-all
6108: Make all lines in the buffer visible.
6109: @item C-c C-h
6110: Make everything under this heading invisible, but not this heading itself
6111: (@code{hide-subtree}).
6112: @item C-c C-s
6113: Make everything under this heading visible, including body, subheadings,
6114: and their bodies (@code{show-subtree}).
6115: @item C-c C-i
6116: Make immediate subheadings (one level down) of this heading line visible
6117: (@code{show-children}).
6118: @item M-x hide-entry
6119: Make this heading line's body invisible.
6120: @item M-x show-entry
6121: Make this heading line's body visible.
6122: @item M-x hide-leaves
6123: Make the body of this heading line, and of all its subheadings, invisible.
6124: @item M-x show-branches
6125: Make all subheadings of this heading line, at all levels, visible.
6126: @end table
6127:
6128: @findex next-visible-heading
6129: @findex previous-visible-heading
6130: @kindex M-@{ (Outline mode)
6131: @kindex M-@} (Outline mode)
6132: There are two special motion commands in Outline mode. @kbd{M-@}}
6133: (@code{next-visible-heading}) moves down to the next heading line.
6134: @kbd{M-@{} (@code{previous-visible-heading}) moves similarly backward.
6135: Both accept numeric arguments as repeat counts. The names emphasize that
6136: invisible headings are skipped, but this is not really a special feature.
6137: All editing commands that look for lines ignore the invisible lines
6138: automatically.@refill
6139:
6140: The other special commands of outline mode are used to make lines visible
6141: or invisible. Their names all start with @code{hide} or @code{show}.
6142: Most of them fall into pairs of opposites. They are not undoable; instead,
6143: you can undo right past them. Making lines visible or invisible is simply
6144: not recorded by the undo mechanism.
6145:
6146: @findex hide-entry
6147: @findex show-entry
6148: Two commands that are exact opposites are @kbd{M-x hide-entry} and
6149: @kbd{M-x show-entry}. They are used with point on a heading line, and
6150: apply only to the body lines of that heading. The subtopics and their
6151: bodies are not affected.
6152:
6153: @findex hide-subtree
6154: @findex show-subtree
6155: @kindex C-c C-s (Outline mode)
6156: @kindex C-c C-h (Outline mode)
6157: @cindex subtree (Outline mode)
6158: Two more powerful opposites are @kbd{C-c C-h} (@code{hide-subtree}) and
6159: @kbd{C-c C-s} (@code{show-subtree}). Both expect to be used when point is
6160: on a heading line, and both apply to all the lines of that heading's
6161: @dfn{subtree}: its body, all its subheadings, both direct and indirect, and
6162: all of their bodies. In other words, the subtree contains everything
6163: following this heading line, up to and not including the next heading of
6164: the same or higher rank.@refill
6165:
6166: @findex hide-leaves
6167: @findex show-branches
6168: Intermediate between a visible subtree and an invisible one is having
6169: all the subheadings visible but none of the body. There are two commands
6170: for doing this, depending on whether you want to hide the bodies or
6171: make the subheadings visible. They are @kbd{M-x hide-leaves} and
6172: @kbd{M-x show-branches}.
6173:
6174: @kindex C-c C-i
6175: @findex show-children
6176: A little weaker than @code{show-branches} is @kbd{C-c C-i}
6177: (@code{show-children}). It makes just the direct subheadings
6178: visible---those one level down. Deeper subheadings remain invisible, if
6179: they were invisible.@refill
6180:
6181: @findex hide-body
6182: @findex show-all
6183: Two commands have a blanket effect on the whole file. @kbd{M-x hide-body}
6184: makes all body lines invisible, so that you see just the outline structure.
6185: @kbd{M-x show-all} makes all lines visible. These commands can be thought
6186: of as a pair of opposites even though @kbd{M-x show-all} applies to more
6187: than just body lines.
6188:
6189: Outline mode makes a line invisible by changing the newline before it
6190: into an ASCII Control-M (code 015). Most editing commands that work on
6191: lines treat an invisible line as part of the previous line because,
6192: strictly speaking, it @i{is} part of that line, since there is no longer a
6193: newline in between. When you save the file in Outline mode, Control-M
6194: characters are saved as newlines, so the invisible lines become ordinary
6195: lines in the file. But saving does not change the visibility status of a
6196: line inside Emacs.
6197:
6198: @vindex outline-mode-hook
6199: Entering Outline mode calls with no arguments the value of the variable
6200: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
6201: does the same with the variable @code{outline-mode-hook}.
6202:
6203: @node Words, Sentences, Text Mode, Text
6204: @section Words
6205: @cindex words
6206: @cindex Meta
6207:
6208: Emacs has commands for moving over or operating on words. By convention,
6209: the keys for them are all @kbd{Meta-} characters.
6210:
6211: @c widecommands
6212: @table @kbd
6213: @item M-f
6214: Move forward over a word (@code{forward-word}).
6215: @item M-b
6216: Move backward over a word (@code{backward-word}).
6217: @item M-d
6218: Kill up to the end of a word (@code{kill-word}).
6219: @item M-@key{DEL}
6220: Kill back to the beginning of a word (@code{backward-kill-word}).
6221: @item M-@@
6222: Mark the end of the next word (@code{mark-word}).
6223: @item M-t
6224: Transpose two words; drag a word forward
6225: or backward across other words (@code{transpose-words}).
6226: @end table
6227:
6228: Notice how these keys form a series that parallels the
6229: character-based @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @kbd{C-t} and
6230: @key{DEL}. @kbd{M-@@} is related to @kbd{C-@@}, which is an alias for
6231: @kbd{C-@key{SPC}}.@refill
6232:
6233: @kindex M-f
6234: @kindex M-b
6235: @findex forward-word
6236: @findex backward-word
6237: The commands @kbd{Meta-f} (@code{forward-word}) and @kbd{Meta-b}
6238: (@code{backward-word}) move forward and backward over words. They are thus
6239: analogous to @kbd{Control-f} and @kbd{Control-b}, which move over single
6240: characters. Like their @kbd{Control-} analogues, @kbd{Meta-f} and
6241: @kbd{Meta-b} move several words if given an argument. @kbd{Meta-f} with a
6242: negative argument moves backward, and @kbd{Meta-b} with a negative argument
6243: moves forward. Forward motion stops right after the last letter of the
6244: word, while backward motion stops right before the first letter.@refill
6245:
6246: @kindex M-d
6247: @findex kill-word
6248: @kbd{Meta-d} (@code{kill-word}) kills the word after point. To be
6249: precise, it kills everything from point to the place @kbd{Meta-f} would
6250: move to. Thus, if point is in the middle of a word, @kbd{Meta-d} kills
6251: just the part after point. If some punctuation comes between point and the
6252: next word, it is killed along with the word. If you wish to kill only the
6253: next word but not the punctuation before it, simply do @kbd{Meta-f} to get
6254: the end, and kill the word backwards with @kbd{Meta-@key{DEL}}.
6255: @kbd{Meta-d} takes arguments just like @kbd{Meta-f}.
6256:
6257: @findex backward-kill-word
6258: @kindex M-DEL
6259: @kbd{Meta-@key{DEL}} (@code{backward-kill-word}) kills the word before
6260: point. It kills everything from point back to where @kbd{Meta-b} would
6261: move to. If point is after the space in @w{@samp{FOO, BAR}}, then
6262: @w{@samp{FOO, }} is killed. If you wish to kill just @samp{FOO}, do
6263: @kbd{Meta-b Meta-d} instead of @kbd{Meta-@key{DEL}}.
6264:
6265: @cindex transposition
6266: @kindex M-t
6267: @findex transpose-words
6268: @kbd{Meta-t} (@code{transpose-words}) exchanges the words before or
6269: containing point with the following word. The delimiter characters between
6270: the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
6271: @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
6272: more on transposition and on arguments to transposition commands.
6273:
6274: @kindex M-@@
6275: @findex mark-word
6276: To operate on the next @var{n} words with an operation which applies
6277: between point and mark, you can either set the mark at point and then move
6278: over the words, or you can use the command @kbd{Meta-@@} (@code{mark-word})
6279: which does not move point, but sets the mark where @kbd{Meta-f} would move
6280: to. It can be given arguments just like @kbd{Meta-f}.
6281:
6282: @cindex syntax table
6283: The word commands' understanding of syntax is completely controlled by
6284: the syntax table. Any character can, for example, be declared to be a word
6285: delimiter. @xref{Syntax}.
6286:
6287: @node Sentences, Paragraphs, Words, Text
6288: @section Sentences
6289: @cindex sentences
6290:
6291: The Emacs commands for manipulating sentences and paragraphs are mostly
6292: on @kbd{Meta-} keys, so as to be like the word-handling commands.
6293:
6294: @table @kbd
6295: @item M-a
6296: Move back to the beginning of the sentence (@code{backward-sentence}).
6297: @item M-e
6298: Move forward to the end of the sentence (@code{forward-sentence}).
6299: @item M-k
6300: Kill forward to the end of the sentence (@code{kill-sentence}).
6301: @item C-x @key{DEL}
6302: Kill back to the beginning of the sentence @*(@code{backward-kill-sentence}).
6303: @end table
6304:
6305: @kindex M-a
6306: @kindex M-e
6307: @findex backward-sentence
6308: @findex forward-sentence
6309: The commands @kbd{Meta-a} and @kbd{Meta-e} (@code{backward-sentence} and
6310: @code{forward-sentence}) move to the beginning and end of the current
6311: sentence, respectively. They were chosen to resemble @kbd{Control-a} and
6312: @kbd{Control-e}, which move to the beginning and end of a line. Unlike
6313: them, @kbd{Meta-a} and @kbd{Meta-e} if repeated or given numeric arguments
6314: move over successive sentences. Emacs considers a sentence to end wherever
6315: there is a @samp{.}, @samp{?} or @samp{!} followed by the end of a line or
6316: two spaces, with any number of @samp{)}, @samp{]}, @samp{'}, or @samp{"}
6317: characters allowed in between. A sentence also begins or ends wherever a
6318: paragraph begins or ends.@refill
6319:
6320: Neither @kbd{M-a} nor @kbd{M-e} moves past the newline or spaces beyond
6321: the sentence edge at which it is stopping.
6322:
6323: @kindex M-k
6324: @kindex C-x DEL
6325: @findex kill-sentence
6326: @findex backward-kill-sentence
6327: Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
6328: with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
6329: @kbd{M-k} (@code{kill-sentence}) which kills from point to the end of the
6330: sentence. With minus one as an argument it kills back to the beginning of
6331: the sentence. Larger arguments serve as a repeat count.@refill
6332:
6333: There is a special command, @kbd{C-x @key{DEL}}
6334: (@code{backward-kill-sentence}) for killing back to the beginning of a
6335: sentence, because this is useful when you change your mind in the middle of
6336: composing text.@refill
6337:
6338: @vindex sentence-end
6339: The variable @code{sentence-end} controls recognition of the end of a
6340: sentence. It is a regexp that matches the last few characters of a
6341: sentence, together with the whitespace following the sentence. Its
6342: normal value is
6343:
6344: @example
6345: "[.?!][]\")]*\\($\\|\t\\| \\)[ \t\n]*"
6346: @end example
6347:
6348: @noindent
6349: (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in the
6350: string.)
6351:
6352: @node Paragraphs, Pages, Sentences, Text
6353: @section Paragraphs
6354: @cindex paragraphs
6355: @kindex M-[
6356: @kindex M-]
6357: @findex backward-paragraph
6358: @findex forward-paragraph
6359:
6360: The Emacs commands for manipulating paragraphs are also @kbd{Meta-}
6361: keys.
6362:
6363: @table @kbd
6364: @item M-[
6365: Move back to previous paragraph beginning @*(@code{backward-paragraph}).
6366: @item M-]
6367: Move forward to next paragraph end (@code{forward-paragraph}).
6368: @item M-h
6369: Put point and mark around this or next paragraph (@code{mark-paragraph}).
6370: @end table
6371:
6372: @kbd{Meta-[} moves to the beginning of the current or previous paragraph,
6373: while @kbd{Meta-]} moves to the end of the current or next paragraph.
6374: Blank lines and text formatter command lines separate paragraphs and are
6375: not part of any paragraph. Also, an indented line starts a new
6376: paragraph.
6377:
6378: In major modes for programs (as opposed to Text mode), paragraphs begin
6379: and end only at blank lines. This makes the paragraph commands continue to
6380: be useful even though there are no paragraphs per se.
6381:
6382: When there is a fill prefix, then paragraphs are delimited by all lines
6383: which don't start with the fill prefix. @xref{Filling}.
6384:
6385: @kindex M-h
6386: @findex mark-paragraph
6387: When you wish to operate on a paragraph, you can use the command
6388: @kbd{Meta-h} (@code{mark-paragraph}) to set the region around it. This
6389: command puts point at the beginning and mark at the end of the paragraph
6390: point was in. If point is between paragraphs (in a run of blank lines, or
6391: at a boundary), the paragraph following point is surrounded by point and
6392: mark. If there are blank lines preceding the first line of the paragraph,
6393: one of these blank lines is included in the region. Thus, for example,
6394: @kbd{M-h C-w} kills the paragraph around or after point.
6395:
6396: @vindex paragraph-start
6397: @vindex paragraph-separate
6398: The precise definition of a paragraph boundary is controlled by the
6399: variables @code{paragraph-separate} and @code{paragraph-start}. The value
6400: of @code{paragraph-start} is a regexp that should match any line that
6401: either starts or separates paragraphs. The value of
6402: @code{paragraph-separate} is another regexp that should match only lines
6403: that separate paragraphs without being part of any paragraph. For example,
6404: normally @code{paragraph-start} is @code{"^[ @t{\}t@t{\}n@t{\}f]"} and
6405: @code{paragraph-separate} is @code{"^[ @t{\}t@t{\}f]*$"}.@refill
6406:
6407: Normally it is desirable for page boundaries to separate paragraphs.
6408: The default values of these variables recognize the usual separator for
6409: pages.
6410:
6411: @node Pages, Filling, Paragraphs, Text
6412: @section Pages
6413:
6414: @cindex pages
6415: @cindex formfeed
6416: Files are often thought of as divided into @dfn{pages} by the
6417: @dfn{formfeed} character (ASCII Control-L, octal code 014). For example,
6418: if a file is printed on a line printer, each page of the file, in this
6419: sense, will start on a new page of paper. Emacs treats a page-separator
6420: character just like any other character. It can be inserted with @kbd{C-q
6421: C-l}, or deleted with @key{DEL}. Thus, you are free to paginate your file,
6422: or not. However, since pages are often meaningful divisions of the file,
6423: commands are provided to move over them and operate on them.
6424:
6425: @c WideCommands
6426: @table @kbd
6427: @item C-x C-p
6428: Put point and mark around this page (or another page) (@code{mark-page}).
6429: @item C-x [
6430: Move point to previous page boundary (@code{backward-page}).
6431: @item C-x ]
6432: Move point to next page boundary (@code{forward-page}).
6433: @item C-x l
6434: Count the lines in this page (@code{count-lines-page}).
6435: @end table
6436:
6437: @kindex C-x [
6438: @kindex C-x ]
6439: @findex forward-page
6440: @findex backward-page
6441: The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
6442: after the previous page delimiter. If point is already right after a page
6443: delimiter, it skips that one and stops at the previous one. A numeric
6444: argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
6445: command moves forward past the next page delimiter.
6446:
6447: @kindex C-x C-p
6448: @findex mark-page
6449: The @kbd{C-x C-p} command (@code{mark-page}) puts point at the beginning
6450: of the current page and the mark at the end. The page delimiter at the end
6451: is included (the mark follows it). The page delimiter at the front is
6452: excluded (point follows it). This command can be followed by @kbd{C-w} to
6453: kill a page which is to be moved elsewhere. If it is inserted after a page
6454: delimiter, at a place where @kbd{C-x ]} or @kbd{C-x [} would take you, then
6455: the page will be properly delimited before and after once again.
6456:
6457: A numeric argument to @kbd{C-x C-p} is used to specify which page to go
6458: to, relative to the current one. Zero means the current page. One means
6459: the next page, and -1 means the previous one.
6460:
6461: @kindex C-x l
6462: @findex count-lines-page
6463: The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
6464: where to break a page in two. It prints in the echo area the total number
6465: of lines in the current page, and then divides it up into those preceding
6466: the current line and those following, as in
6467:
6468: @example
6469: Page has 96 (72+25) lines
6470: @end example
6471:
6472: @noindent
6473: Notice that the sum is off by one; this is correct if point is not at the
6474: front of a line.
6475:
6476: @vindex page-delimiter
6477: The variable @code{page-delimiter} should have as its value a regexp that
6478: matches the beginning of a line that separates pages. This is what defines
6479: where pages begin. The normal value of this variable is @code{"^@t{\}f"},
6480: which matches a formfeed character at the beginning of a line.
6481:
6482: @node Filling, Case, Pages, Text
6483: @section Filling Text
6484: @cindex filling
6485:
6486: @cindex Auto Fill mode
6487: With Auto Fill mode, text can be @dfn{filled} (broken up into lines that
6488: fit in a specified width) as you insert it. If you alter existing text it
6489: may no longer be properly filled; then explicit commands for filling can be
6490: used.
6491:
6492: @table @kbd
6493: @item M-x auto-fill-mode
6494: Enable or disable Auto Fill mode.
6495: @item @key{SPC}
6496: @itemx @key{RET}
6497: In Auto Fill mode, break lines when appropriate.
6498: @item M-q
6499: Fill current paragraph (@code{fill-paragraph}).
6500: @item M-g
6501: Fill each paragraph in the region (@code{fill-region}).
6502: @item M-x fill-region-as-paragraph.
6503: Fill the region, considering it as one paragraph.
6504: @item M-x fill-individual-paragraphs
6505: Fill the region, considering each change of indentation as starting a
6506: new paragraph.
6507: @item M-s
6508: Center a line.
6509: @end table
6510:
6511: @findex auto-fill-mode
6512: @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off if
6513: it was on. With a positive numeric argument it always turns Auto Fill mode
6514: on, and with a negative argument always turns it off. You can see when
6515: Auto Fill mode is in effect by the presence of the word @samp{Fill} in the
6516: mode line, inside the parentheses. Auto Fill mode is a minor mode, turned
6517: on or off for each buffer individually. @xref{Minor Modes}.
6518:
6519: In Auto Fill mode, lines are broken automatically at spaces when they get
6520: longer than the desired width. Line breaking and rearrangement takes place
6521: only when you type @key{SPC} or @key{RET}. If you wish to insert a space
6522: or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} or
6523: @kbd{C-q @key{LFD}} (recall that a newline is really a linefeed). Also,
6524: @kbd{C-o} inserts a newline without line breaking.
6525:
6526: Auto Fill mode works well with Lisp mode, because when it makes a new
6527: line in Lisp mode it indents that line with @key{TAB}. If a line ending in
6528: a comment gets too long, the text of the comment is split into two
6529: comments.
6530:
6531: @kindex M-q
6532: @findex fill-paragraph
6533: Auto Fill mode does not refill entire paragraphs. It can break lines but
6534: cannot merge lines. So editing in the middle of a paragraph can result in
6535: a paragraph that is not correctly filled. To refill a paragraph, use the
6536: command @kbd{Meta-q} (@code{fill-paragraph}). It causes the paragraph that
6537: point is inside, or the one after point if point is between paragraphs, to
6538: be refilled. All the line-breaks are removed, and then new ones are
6539: inserted where necessary. @kbd{M-q} can be undone with @kbd{C-_}.
6540: @xref{Undo}.
6541:
6542: @kindex M-g
6543: @findex fill-region
6544: To refill many paragraphs, use @kbd{M-g} (@code{fill-region}), which
6545: divides the region into paragraphs and fills each of them.
6546:
6547: @findex fill-region-as-paragraph
6548: @kbd{Meta-q} and @kbd{Meta-g} use the same criteria as @kbd{Meta-h} for
6549: finding paragraph boundaries (@pxref{Paragraphs}). For more control, you
6550: can use @kbd{M-x fill-region-as-paragraph}, which refills everything
6551: between point and mark. This command recognizes only blank lines as
6552: paragraph separators.@refill
6553:
6554: @cindex justification
6555: A numeric argument to @kbd{M-g} or @kbd{M-q} causes it to @dfn{justify}
6556: the text as well as filling it. This means that extra spaces are inserted
6557: to make the right margin line up exactly at the fill column. To remove the
6558: extra spaces, use @kbd{M-q} or @kbd{M-g} with no argument.@refill
6559:
6560: @kindex M-s
6561: @cindex centering
6562: @findex center-line
6563: The command @kbd{Meta-s} (@code{center-line}) centers the current line
6564: within the current fill column. With an argument, it centers several lines
6565: individually and moves past them.
6566:
6567: @vindex fill-column
6568: @vindex default-fill-column
6569: The maximum line width for filling is in the variable @code{fill-column}.
6570: This variable has a separate value in each buffer; setting it in one buffer
6571: has no effect on any other buffer. The initial value in a new buffer is
6572: taken from the variable @code{default-fill-column}.
6573:
6574: @kindex C-x f
6575: @findex set-fill-column
6576: The easiest way to set @code{fill-column} is to use the command @kbd{C-x
6577: f} (@code{set-fill-column}). With no argument, it sets @code{fill-column}
6578: to the current horizontal position of point. With a numeric argument, it
6579: uses that as the new fill column.
6580:
6581: @cindex fill prefix
6582: @kindex C-x .
6583: @findex set-fill-prefix
6584: @vindex fill-prefix
6585: To fill a paragraph in which each line starts with a special marker
6586: (which might be a few spaces, giving an indented paragraph), use the
6587: @dfn{fill prefix} feature. The fill prefix is a string which Emacs expects
6588: every line to start with, and which is not included in filling. It is
6589: stored in the variable @code{fill-prefix}.
6590:
6591: To specify a fill prefix, move to a line that starts with the desired
6592: prefix, put point at the end of the prefix, and give the command
6593: @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). That's a period after the
6594: @kbd{C-x}. To turn off the fill prefix, specify an empty prefix: type
6595: @w{@kbd{C-x .}}@: with point at the beginning of a line.@refill
6596:
6597: When a fill prefix is in effect, the fill commands remove the fill prefix
6598: from each line before filling and insert it on each line after filling. In
6599: Auto Fill mode, @key{SPC} also inserts the fill prefix on any new line.
6600: Lines that do not start with the fill prefix are considered to start
6601: paragraphs, both in @kbd{M-q} and the paragraph commands; this is just
6602: right if you are using paragraphs with hanging indentation (every line
6603: indented except the first one). Lines which are blank or indented once the
6604: prefix is removed also separate or start paragraphs; this is what you want
6605: if you are writing multi-paragraph comments with a comment delimiter on
6606: each line.
6607:
6608: @findex fill-individual-paragraphs
6609: Another way to use fill prefixes is through @kbd{M-x
6610: fill-individual-paragraphs}. This function divides the region into groups
6611: of consecutive lines with the same amount and kind of indentation and fills
6612: each group as a paragraph using its indentation as a fill prefix.
6613:
6614: Many users like Auto Fill mode and want to use it in all text files.
6615: Execute the following Lisp expression, perhaps in your init file, to cause
6616: Auto Fill mode to be turned on whenever Text mode is entered:
6617:
6618: @lisp
6619: (setq text-mode-hook 'turn-on-auto-fill)
6620: @end lisp
6621:
6622: @node Case,, Filling, Text
6623: @section Case Conversion Commands
6624: @cindex case conversion
6625:
6626: Emacs has commands for converting either a single word or any arbitrary
6627: range of text to upper case or to lower case.
6628:
6629: @c WideCommands
6630: @table @kbd
6631: @item M-l
6632: Convert following word to lower case (@code{downcase-word}).
6633: @item M-u
6634: Convert following word to upper case (@code{upcase-word}).
6635: @item M-c
6636: Capitalize the following word (@code{capitalize-word}).
6637: @item C-x C-l
6638: Convert region to lower case (@code{downcase-region}).
6639: @item C-x C-u
6640: Convert region to upper case (@code{upcase-region}).
6641: @end table
6642:
6643: @kindex M-l
6644: @kindex M-u
6645: @kindex M-c
6646: @cindex words
6647: @findex downcase-word
6648: @findex upcase-word
6649: @findex capitalize-word
6650: The word conversion commands are the most useful. @kbd{Meta-l}
6651: (@code{downcase-word}) converts the word after point to lower case, moving
6652: past it. Thus, repeating @kbd{Meta-l} converts successive words.
6653: @kbd{Meta-u} (@code{upcase-word}) converts to all capitals instead, while
6654: @kbd{Meta-c} (@code{capitalize-word}) puts the first letter of the word
6655: into upper case and the rest into lower case. All these commands convert
6656: several words at once if given an argument. They are especially convenient
6657: for converting a large amount of text from all upper case to mixed case,
6658: because you can move through the text using @kbd{M-l}, @kbd{M-u} or
6659: @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
6660: to skip a word.
6661:
6662: When given a negative argument, the word case conversion commands apply
6663: to the appropriate number of words before point, but do not move point.
6664: This is convenient when you have just typed a word in the wrong case: you
6665: can give the case conversion command and continue typing.
6666:
6667: If a word case conversion command is given in the middle of a word, it
6668: applies only to the part of the word which follows point. This is just
6669: like what @kbd{Meta-d} (@code{kill-word}) does. With a negative argument,
6670: case conversion applies only to the part of the word before point.
6671:
6672: @kindex C-x C-l
6673: @kindex C-x C-u
6674: @cindex region
6675: @findex downcase-region
6676: @findex upcase-region
6677: The other basic case conversion commands are @kbd{C-x C-u}
6678: (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
6679: convert everything between point and mark to the specified case. Point and
6680: mark do not move.@refill
6681:
6682: @node Programs, Running, Text, Top
6683: @chapter Editing Programs
6684: @cindex Lisp
6685: @cindex C
6686:
6687: Emacs has many commands designed to understand the syntax of programming
6688: languages such as Lisp and C. These commands can
6689:
6690: @itemize @bullet
6691: @item
6692: Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
6693: @item
6694: Move over or mark top-level balanced expressions (@dfn{defuns}, in Lisp;
6695: functions, in C).
6696: @item
6697: Show how parentheses balance (@pxref{Matching}).
6698: @item
6699: Insert, kill or align comments (@pxref{Comments}).
6700: @item
6701: Follow the usual indentation conventions of the language
6702: (@pxref{Grinding}).
6703: @end itemize
6704:
6705: The commands for words, sentences and paragraphs are very useful in
6706: editing code even though their canonical application is for editing human
6707: language text. Most symbols contain words (@pxref{Words}); sentences can
6708: be found in strings and comments (@pxref{Sentences}). Paragraphs per se
6709: are not present in code, but the paragraph commands are useful anyway,
6710: because Lisp mode and C mode define paragraphs to begin and end at blank
6711: lines (@pxref{Paragraphs}). Judicious use of blank lines to make the
6712: program clearer will also provide interesting chunks of text for the
6713: paragraph commands to work on.
6714:
6715: The selective display feature is useful for looking at the overall
6716: structure of a function (@pxref{Selective Display}). This feature causes
6717: only the lines that are indented less than a specified amount to appear
6718: on the screen.
6719:
6720: @menu
6721: * Program Modes:: Major modes for editing programs.
6722: * Lists:: Expressions with balanced parentheses.
6723: There are editing commands to operate on them.
6724: * Defuns:: Each program is made up of separate functions.
6725: There are editing commands to operate on them.
6726: * Grinding:: Adjusting indentation to show the nesting.
6727: * Matching:: Insertion of a close-delimiter flashes matching open.
6728: * Comments:: Inserting, illing and aligning comments.
6729: * Balanced Editing:: Inserting two matching parentheses at once, etc.
6730: * Documentation:: Getting documentation of functions you plan to call.
6731: * Change Log:: Maintaining a change history for your program.
6732: * Tags:: Go direct to any function in your program in one
6733: command. Tags remembers which file it is in.
6734: @end menu
6735:
6736: @node Program Modes, Lists, Programs, Programs
6737: @section Major Modes for Programming Languages
6738:
6739: @cindex Lisp mode
6740: @cindex C mode
6741: @cindex Scheme mode
6742: Emacs also has major modes for the programming languages Lisp, Scheme (a
6743: variant of Lisp), C and Muddle. Ideally, a major mode should be
6744: implemented for each programming language that you might want to edit with
6745: Emacs; but often the mode for one language can serve for other
6746: syntactically similar languages. The language modes that exist are those
6747: that someone decided to take the trouble to write.
6748:
6749: There are several forms of Lisp mode, which differ in the way they
6750: interface to Lisp execution. @xref{Lisp Modes}.
6751:
6752: Each of the programming language modes defines the @key{TAB} key to run
6753: an indentation function that knows the indentation conventions of that
6754: language and updates the current line's indentation accordingly. For
6755: example, in C mode @key{TAB} is bound to @code{c-indent-line}. @key{LFD}
6756: is normally defined to do @key{RET} followed by @key{TAB}; thus, it too
6757: indents in a mode-specific fashion.
6758:
6759: @kindex DEL
6760: @findex backward-delete-char-untabify
6761: In most programming languages, indentation is likely to vary from line to
6762: line. So the major modes for those languages rebind @key{DEL} to treat a
6763: tab as if it were the equivalent number of spaces (using the command
6764: @code{backward-delete-char-untabify}). This makes it possible to rub out
6765: indentation one column at a time without worrying whether it is made up of
6766: spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point,
6767: in these modes.
6768:
6769: Programming language modes define paragraphs to be separated only by
6770: blank lines, so that the paragraph commands remain useful. Auto Fill mode,
6771: if enabled in a programming language major mode, indents the new lines
6772: which it creates.
6773:
6774: @cindex mode hook
6775: @vindex c-mode-hook
6776: @vindex lisp-mode-hook
6777: @vindex emacs-lisp-mode-hook
6778: @vindex lisp-interaction-mode-hook
6779: @vindex scheme-mode-hook
6780: @vindex muddle-mode-hook
6781: Turning on a major mode calls a user-supplied function called the
6782: @dfn{mode hook}, which is the value of a Lisp variable. For example,
6783: turning on C mode calls the value of the variable @code{c-mode-hook} if
6784: that value exists and is non-@code{nil}. Mode hook variables for other
6785: programming language modes include @code{lisp-mode-hook},
6786: @code{emacs-lisp-mode-hook}, @code{lisp-interaction-mode-hook},
6787: @code{scheme-mode-hook} and @code{muddle-mode-hook}. The mode hook
6788: function receives no arguments.@refill
6789:
6790: @node Lists, Defuns, Program Modes, Programs
6791: @section Lists and Sexps
6792:
6793: @c doublewidecommands
6794: @table @kbd
6795: @item C-M-f
6796: Move forward over a sexp (@code{forward-sexp}).
6797: @item C-M-b
6798: Move backward over a sexp (@code{backward-sexp}).
6799: @item C-M-k
6800: Kill sexp forward (@code{kill-sexp}).
6801: @item C-M-u
6802: Move up and backward in list structure (@code{backward-up-list}).
6803: @item C-M-d
6804: Move down and forward in list structure (@code{down-list}).
6805: @item C-M-n
6806: Move forward over a list (@code{forward-list}).
6807: @item C-M-p
6808: Move backward over a list (@code{backward-list}).
6809: @item C-M-t
6810: Transpose expressions (@code{transpose-sexps}).
6811: @item C-M-@@
6812: Put mark after following expression (@code{mark-sexp}).
6813: @end table
6814:
6815: @cindex Control-Meta
6816: By convention, Emacs keys for dealing with balanced expressions are
6817: usually @kbd{Control-Meta-} characters. They tend to be analogous in
6818: function to their @kbd{Control-} and @kbd{Meta-} equivalents. These commands
6819: are usually thought of as pertaining to expressions in programming
6820: languages, but can be useful with any language in which some sort of
6821: parentheses exist (including English).
6822:
6823: @cindex list
6824: @cindex sexp
6825: @cindex expression
6826: These commands fall into two classes. Some deal only with @dfn{lists}
6827: (parenthetical groupings). They see nothing except parentheses, brackets,
6828: braces, and escape characters that might be used to quote those. The other
6829: commands deal with expressions or @dfn{sexps} (short for @dfn{s-expression}, the
6830: ancient term for a balanced expression in Lisp). A parenthetical grouping
6831: is one kind of sexp, but a symbol name is also a sexp, and so is a string.
6832: Numbers and character constants can also be sexps. The idea is to define
6833: the major mode for a language so that the expressions of that language
6834: count as sexps, as much as possible.
6835:
6836: Except in Lisp-like languages, not all expressions can be sexps. For
6837: example, C mode does not recognize @samp{foo + bar} as a sexp, even though
6838: it @i{is} a C expression; it recognizes @samp{foo} as one sexp and @samp{bar} as
6839: another, with the @samp{+} as punctuation between them. This is a
6840: fundamental ambiguity: both @samp{foo + bar} and @samp{foo} are legitimate
6841: choices for the sexp to move over if point is at the @samp{f}. Note that
6842: @samp{(foo + bar)} is a sexp in C mode.
6843:
6844: Some languages have obscure forms of syntax for expressions that nobody
6845: has bothered to make Emacs understand properly.
6846:
6847: @kindex C-M-f
6848: @kindex C-M-b
6849: @findex forward-sexp
6850: @findex backward-sexp
6851: To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If
6852: the first significant character after point is an opening delimiter
6853: (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
6854: moves past the matching closing delimiter. If the character begins a
6855: symbol, string, or number, @kbd{C-M-f} moves over that. If the character
6856: after point is a closing delimiter, @kbd{C-M-f} just moves past it. (This
6857: last is not really moving across a sexp; it is an exception which is
6858: included in the definition of @kbd{C-M-f} because it is as useful a
6859: behavior as anyone can think of for that situation.)@refill
6860:
6861: The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
6862: sexp. The detailed rules are like those above for @kbd{C-M-f}, but with
6863: directions reversed. If there are any prefix characters (singlequote,
6864: backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
6865: over them as well.
6866:
6867: @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
6868: specified number of times; with a negative argument, it moves in the
6869: opposite direction.
6870:
6871: The sexp commands move across comments as if they were whitespace, in
6872: languages such as C where the comment-terminator can be recognized. In
6873: Lisp, and other languages where comments run until the end of a line, it is
6874: very difficult to ignore comments when parsing backwards; therefore, in
6875: such languages the sexp commands treat the text of comments as if it were
6876: code.
6877:
6878: @kindex C-M-k
6879: @findex kill-sexp
6880: Killing a sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}).
6881: @kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over.
6882:
6883: @kindex C-M-n
6884: @kindex C-M-p
6885: @findex forward-list
6886: @findex backward-list
6887: The @dfn{list commands} move over lists like the sexp commands but skip
6888: blithely over any number of other kinds of sexps (symbols, strings, etc).
6889: They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
6890: (@code{backward-list}). The main reason they are useful is that they
6891: usually ignore comments (since the comments usually do not contain any
6892: lists).@refill
6893:
6894: @kindex C-M-u
6895: @kindex C-M-d
6896: @findex backward-up-list
6897: @findex down-list
6898: @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
6899: that's possible. To move @i{up} one (or @var{n}) levels, use @kbd{C-M-u}
6900: (@code{backward-up-list}).
6901: @kbd{C-M-u} moves backward up past one unmatched opening delimiter. A
6902: positive argument serves as a repeat count; a negative argument reverses
6903: direction of motion and also requests repetition, so it moves forward and
6904: up one or more levels.@refill
6905:
6906: To move @i{down} in list structure, use @kbd{C-M-d} (@code{down-list}). In Lisp mode,
6907: where @samp{(} is the only opening delimiter, this is nearly the same as
6908: searching for a @samp{(}.
6909:
6910: @cindex transposition
6911: @kindex C-M-t
6912: @findex transpose-sexps
6913: A somewhat random-sounding command which is nevertheless easy to use is
6914: @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp across
6915: the next one. An argument serves as a repeat count, and a negative
6916: argument drags backwards (thus canceling out the effect of @kbd{C-M-t} with
6917: a positive argument). An argument of zero, rather than doing nothing,
6918: transposes the sexps ending after point and the mark.
6919:
6920: @kindex C-M-@@
6921: @findex mark-sexp
6922: To make the region be the next sexp in the buffer, use @kbd{C-M-@@}
6923: (@code{mark-sexp}) which sets mark at the same place that @kbd{C-M-f} would
6924: move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In particular, a
6925: negative argument is useful for putting the mark at the beginning of the
6926: previous sexp.
6927:
6928: The list and sexp commands' understanding of syntax is completely
6929: controlled by the syntax table. Any character can, for example, be
6930: declared to be an opening delimiter and act like an open parenthesis.
6931: @xref{Syntax}.
6932:
6933: @node Defuns, Grinding, Lists, Programs
6934: @section Defuns
6935: @cindex defuns
6936:
6937: In Emacs, a list at the top level in the buffer is called a @dfn{defun}.
6938: The name derives from the fact that most top level lists in a Lisp file are
6939: instances of the special form @code{defun}, but any top level list counts
6940: as a defun in Emacs parlance regardless of what its contents are, and
6941: regardless of the programming language in use. For example, in C, the body
6942: of a function definition is a defun.
6943:
6944: @c doublewidecommands
6945: @table @kbd
6946: @item C-M-a
6947: Move to beginning of current or preceding defun
6948: (@code{beginning-of-defun}).
6949: @item C-M-e
6950: Move to end of current or following defun (@code{end-of-defun}).
6951: @item C-M-h
6952: Put region around whole current or following defun (@code{mark-defun}).
6953: @end table
6954:
6955: @kindex C-M-a
6956: @kindex C-M-e
6957: @kindex C-M-h
6958: @findex beginning-of-defun
6959: @findex end-of-defun
6960: @findex mark-defun
6961: The commands to move to the beginning and end of the current defun are
6962: @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
6963:
6964: If you wish to operate on the current defun, use @kbd{C-M-h}
6965: (@code{mark-defun}) which puts point at the beginning and mark at the end
6966: of the current or next defun. For example, this is the easiest way to get
6967: ready to move the defun to a different place in the text. In C mode,
6968: @kbd{C-M-h} runs the function @code{mark-c-function}, which is almost the
6969: same as @code{mark-defun}; the difference is that it backs up over the
6970: argument declarations, function name and returned data type so that the
6971: entire C function is inside the region.
6972:
6973: Emacs assumes that any open-parenthesis found in the leftmost column is
6974: the start of a defun. Therefore, @b{never put an open-parenthesis at the
6975: left margin in a Lisp file unless it is the start of a top level list.
6976: Never put an open-brace or other opening delimiter at the beginning of a
6977: line of C code unless it starts the body of a function.} The most likely
6978: problem case is when you want an opening delimiter at the start of a line
6979: inside a string. To avoid trouble, put an escape character (@samp{\}, in C
6980: and Emacs Lisp, @samp{/} in some other Lisp dialects) before the opening
6981: delimiter. It will not affect the contents of the string.
6982:
6983: In the remotest past, the original Emacs found defuns by moving upward a
6984: level of parentheses until there were no more levels to go up. This always
6985: required scanning all the way back to the beginning of the buffer, even for
6986: a small function. To speed up the operation, Emacs was changed to assume
6987: that any @samp{(} (or other character assigned the syntactic class of
6988: opening-delimiter) at the left margin is the start of a defun. This
6989: heuristic was nearly always right and avoided the costly scan; however,
6990: it mandated the convention described above.
6991:
6992: @node Grinding, Matching, Defuns, Programs
6993: @section Indentation for Programs
6994: @cindex indentation
6995: @cindex grinding
6996:
6997: The best way to keep a program properly indented (``ground'') is to use
6998: Emacs to re-indent it as you change it. Emacs has commands to indent
6999: properly either a single line, a specified number of lines, or all of the
7000: lines inside a single parenthetical grouping.
7001:
7002: @c WideCommands
7003: @table @kbd
7004: @item @key{TAB}
7005: Adjust indentation of current line.
7006: @item @key{LFD}
7007: Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
7008: @item C-M-q
7009: Re-indent all the lines within one list (@code{indent-sexp}).
7010: @item C-u @key{TAB}
7011: Shift an entire list rigidly sideways so that its first line
7012: is properly indented.
7013: @item C-M-\
7014: Re-indent all lines in the region (@code{indent-region}).
7015: @end table
7016:
7017: @kindex TAB
7018: @findex c-indent-line
7019: @findex lisp-indent-line
7020: The basic indentation command is @key{TAB}, which gives the current line
7021: the correct indentation as determined from the previous lines. The
7022: function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
7023: in Lisp mode, @code{c-indent-line} in C mode, etc. These functions
7024: understand different syntaxes for different languages, but they all do
7025: about the same thing. @key{TAB} in any programming language major mode
7026: inserts or deletes whitespace at the beginning of the current line,
7027: independent of where point is in the line. If point is inside the
7028: whitespace at the beginning of the line, @key{TAB} leaves it at the end of
7029: that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
7030: the characters around it.
7031:
7032: Use @kbd{C-q @key{TAB}} to insert a tab at point.
7033:
7034: @kindex LFD
7035: @findex newline-and-indent
7036: When entering a large amount of new code, use @key{LFD} (@code{newline-and-indent}),
7037: which is equivalent to a @key{RET} followed by a @key{TAB}. @key{LFD} creates
7038: a blank line, and then gives it the appropriate indentation.
7039:
7040: @key{TAB} indents the second and following lines of the body of an
7041: parenthetical grouping each under the preceding one; therefore, if you
7042: alter one line's indentation to be nonstandard, the lines below will tend
7043: to follow it. This is the right behavior in cases where the standard
7044: result of @key{TAB} is unaesthetic.
7045:
7046: Remember that an open-parenthesis, open-brace or other opening delimiter
7047: at the left margin is assumed by Emacs (including the indentation routines)
7048: to be the start of a function. Therefore, you must never have an opening
7049: delimiter in column zero that is not the beginning of a function; not even
7050: inside a string. This restriction is vital for making the indentation
7051: commands fast; you must simply accept it. @xref{Defuns}, for more
7052: information on this.
7053:
7054: @subsection Indenting Several Lines
7055:
7056: When you wish to re-indent code which has been altered or moved to a
7057: different level in the list structure, you have several commands available.
7058:
7059: @kindex C-M-q
7060: @findex indent-sexp
7061: @findex indent-c-exp
7062: You can re-indent the contents of a single list by positioning point
7063: before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
7064: Lisp mode, @code{indent-c-exp} in C mode; also bound to other suitable
7065: functions in other modes). The indentation of the line the sexp starts on
7066: is not changed; therefore, only the relative indentation within the list,
7067: and not its position, is changed. To correct the position as well, type a
7068: @key{TAB} before the @kbd{C-M-q}.
7069:
7070: @kindex C-u TAB
7071: If the relative indentation within a list is correct but the indentation
7072: of its beginning is not, go to the line the list begins on and type
7073: @kbd{C-u @key{TAB}}. When @key{TAB} is given a numeric argument, it moves all the
7074: lines in the grouping starting on the current line sideways the same amount
7075: that the current line moves. It is clever, though, and does not move lines
7076: that start inside strings, or C preprocessor lines when in C mode.
7077:
7078: @kindex C-M-\
7079: @findex indent-region
7080: Another way to specify the range to be re-indented is with point and
7081: mark. The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to every line
7082: whose first character is between point and mark.
7083:
7084: @subsection Customizing Lisp Indentation
7085: @cindex customization
7086:
7087: The indentation pattern for a Lisp expression can depend on the function
7088: called by the expression. For each Lisp function, you can choose among
7089: several predefined patterns of indentation, or define an arbitrary one with
7090: a Lisp program.
7091:
7092: The standard pattern of indentation is as follows: the second line of the
7093: expression is indented under the first argument, if that is on the same
7094: line as the beginning of the expression; otherwise, the second line is
7095: indented underneath the function name. Each following line is indented
7096: under the previous line whose nesting depth is the same.
7097:
7098: @vindex lisp-indent-offset
7099: If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
7100: the usual indentation pattern for the second line of an expression, so that
7101: such lines are always indented @code{lisp-indent-offset} more columns than
7102: the containing list.
7103:
7104: @vindex lisp-body-indention
7105: The standard pattern is overridded for certain functions. Functions
7106: whose names start with @code{def} always indent the second line by
7107: @code{lisp-body-indention} extra columns beyond the open-parenthesis
7108: starting the expression.
7109:
7110: The standard pattern can be overridden in various ways for individual
7111: functions, according to the @code{lisp-indent-hook} property of the
7112: function name. There are four possibilities for this property:
7113:
7114: @table @asis
7115: @item @code{nil}
7116: This is the same as no property; the standard indentation pattern is used.
7117: @item @code{defun}
7118: The pattern used for function names that start with @code{def} is used for
7119: this function also.
7120: @item a number, @var{number}
7121: The first @var{number} arguments of the function are
7122: @dfn{distinguished} arguments; the rest are considered the @dfn{body}
7123: of the expression. A line in the expression is indented according to
7124: whether the first argument on it is distinguished or not. If the
7125: argument is part of the body, the line is indented @code{lisp-body-indent}
7126: more columns than the open-parenthesis starting the containing
7127: expression. If the argument is distinguished and is either the first
7128: or second argument, it is indented @i{twice} that many extra columns.
7129: If the argument is distinguished and not the first or second argument,
7130: the standard pattern is followed for that line.
7131: @item a symbol, @var{symbol}
7132: @var{symbol} should be a function name; that function is called to
7133: calculate the indentation of a line within this expression. The
7134: function receives two arguments:
7135: @table @asis
7136: @item @var{state}
7137: The value returned by @code{parse-partial-sexp} (a Lisp primitive for
7138: indentation and nesting computation) when it parses up to the
7139: beginning of this line.
7140: @item @var{pos}
7141: The position at which the line being indented begins.
7142: @end table
7143: @noindent
7144: It should return either a number, which is the number of columns of
7145: indentation for that line, or a list whose car is such a number. The
7146: difference between returning a number and returning a list is that a
7147: number says that all following lines at the same nesting level should
7148: be indented just like this one; a list says that following lines might
7149: call for different indentations. This makes a difference when the
7150: indentation is being computed by @kbd{C-M-q}; if the value is a
7151: number, @kbd{C-M-q} need not recalculate indentation for the following
7152: lines until the end of the list.
7153: @end table
7154:
7155: @subsection Customizing C Indentation
7156:
7157: C does not have anything analogous to particular function names for which
7158: special forms of indentation are desirable. However, it has a different
7159: need for customization facilities: many different styles of C indentation
7160: are in common use. There are six variables you can set to control the
7161: style that Emacs C mode will use.
7162:
7163: @vindex c-indent-level
7164: The variable @code{c-indent-level} controls the indentation for C
7165: statements with respect to the surrounding block. In the example
7166:
7167: @example
7168: @{
7169: foo ();
7170: @end example
7171:
7172: @noindent
7173: the difference in indentation between the lines is @code{c-indent-level}.
7174: Its standard value is 2.
7175:
7176: If the open-brace beginning the compound statement is not at the beginning
7177: of its line, the @code{c-indent-level} is added to the indentation of the
7178: line, not the column of the open-brace. For example,
7179:
7180: @example
7181: if (losing) @{
7182: do_this ();
7183: @end example
7184:
7185: @noindent
7186: One popular indentation style is that which results from setting
7187: @code{c-indent-level} to 8 and putting open-braces at the end of a line in
7188: this way.
7189:
7190: @vindex c-brace-imaginary-offset
7191: In fact, the value of the variable @code{c-brace-imaginary-offset} is
7192: also added to the indentation of such a statement. Normally this variable
7193: is zero. Think of this variable as the imaginary position of the open
7194: brace, relative to the first nonblank character on the line. By setting
7195: this variable to 4 and @code{c-indent-level} to 0, you can get this style:
7196:
7197: @example
7198: if (x == y) @{
7199: do_it ();
7200: @}
7201: @end example
7202:
7203: When @code{c-indent-level} is zero, the statements inside most braces
7204: will line up right under the open brace. But there is an exception made
7205: for braces in column zero, such as surrounding a function's body. The
7206: statements just inside it do not go at column zero. Instead,
7207: @code{c-brace-offset} and @code{c-continued-statement-offset} (see below)
7208: are added to produce a typical offset between brace levels, and the
7209: statements are indented that far.
7210:
7211: @vindex c-continued-statement-offset
7212: @code{c-continued-statement-offset} controls the extra indentation for a
7213: line that starts within a statement (but not within parentheses or
7214: brackets). These lines are usually statements that are within other
7215: statements, such as the then-clauses of @code{if} statements and the bodies
7216: of @code{while} statements. This parameter is the difference in
7217: indentation between the two lines in
7218:
7219: @example
7220: if (x == y)
7221: do_it ();
7222: @end example
7223:
7224: @noindent
7225: Its standard value is 2. Some popular indentation styles correspond to a
7226: value of zero for @code{c-continued-statement-offset}.
7227:
7228: @vindex c-brace-offset
7229: @code{c-brace-offset} is the extra indentation given to a line that
7230: starts with an open-brace. Its standard value is zero;
7231: compare
7232:
7233: @example
7234: if (x == y)
7235: @{
7236: @end example
7237:
7238: @noindent
7239: with
7240:
7241: @example
7242: if (x == y)
7243: do_it ();
7244: @end example
7245:
7246: @noindent
7247: if @code{c-brace-offset} were set to 4, the first example would become
7248:
7249: @example
7250: if (x == y)
7251: @{
7252: @end example
7253:
7254: @vindex c-argdecl-indent
7255: @code{c-argdecl-indent} controls the indentation of declarations of the
7256: arguments of a C function. It is absolute: argument declarations receive
7257: exactly @code{c-argdecl-indent} spaces. The standard value is 5, resulting
7258: in code like this:
7259:
7260: @example
7261: char *
7262: index (string, char)
7263: char *string;
7264: int char;
7265: @end example
7266:
7267: @vindex c-label-offset
7268: @code{c-label-offset} is the extra indentation given to a line that
7269: contains a label, a case statement, or a default statement. Its standard
7270: value is -2, resulting in code like this
7271:
7272: @example
7273: switch (c)
7274: @{
7275: case 'x':
7276: @end example
7277:
7278: @noindent
7279: If @code{c-label-offset} were zero, the same code would be indented as
7280:
7281: @example
7282: switch (c)
7283: @{
7284: case 'x':
7285: @end example
7286:
7287: @noindent
7288: This example assumes that the other variables above also have their
7289: standard values.
7290:
7291: I strongly recommend that you try out the indentation style produced by
7292: the standard settings of these variables, together with putting open braces
7293: on separate lines. You can see how it looks in all the C source files of
7294: GNU Emacs.
7295:
7296: @vindex c-auto-newline
7297: One other variable, @code{c-auto-newline}, does not affect the style of
7298: indentation that is used, but makes insertion of certain characters insert
7299: newlines automatically. When this variable is non-@code{nil}, newlines are
7300: inserted both before and after braces that you insert, and after colons and
7301: semicolons. Correct C indentation is done on all the lines that are made
7302: this way.
7303:
7304: @node Matching, Comments, Grinding, Programs
7305: @section Automatic Display Of Matching Parentheses
7306: @cindex matching parentheses
7307: @cindex parentheses
7308:
7309: The Emacs parenthesis-matching feature is designed to show automatically
7310: how parentheses match in the text. When ever a self-inserting character
7311: that is a closing delimiter is typed, the cursor moves momentarily to the
7312: location of the matching opening delimiter, provided that is on the screen.
7313: If it is not on the screen, some text starting with that opening delimiter
7314: is displayed in the echo area. Either way, you can tell what grouping is
7315: being closed off.
7316:
7317: In Lisp, automatic matching applies only to parentheses. In C, it
7318: applies to braces and brackets too. Emacs knows which characters to regard
7319: as matching delimiters based on the syntax table, which is set by the major
7320: mode. @xref{Syntax}.
7321:
7322: If the opening delimiter and closing delimiter are mismatched---such as,
7323: in @samp{[x)}---a warning message is displayed in the echo area. The
7324: correct matches are specified in the syntax table.
7325:
7326: @vindex blink-matching-paren
7327: @vindex blink-matching-paren-distance
7328: Two variables control parenthesis match display. @code{blink-matching-paren}
7329: turns the feature on or off; @code{nil} turns it off, but the default is
7330: @code{t} to turn match display on. @code{blink-matching-paren-distance}
7331: specifies how many characters back to search to find the matching opening
7332: delimiter. If the match is not found in that far, scanning stops, and
7333: nothing is displayed. This is to prevent scanning for the matching
7334: delimiter from wasting lots of time when there is no match.
7335:
7336: @node Comments, Balanced Editing, Matching, Programs
7337: @section Manipulating Comments
7338: @cindex comments
7339: @kindex M-;
7340: @cindex indentation
7341: @findex indent-for-comment
7342:
7343: The comment commands insert, kill and align comments. There are also
7344: commands for moving through existing code and inserting comments.
7345:
7346: @c WideCommands
7347: @table @kbd
7348: @item M-;
7349: Insert or align comment (@code{indent-for-comment}).
7350: @item C-x ;
7351: Set comment column (@code{set-comment-column}).
7352: @item C-u - C-x ;
7353: Kill comment on current line (@code{kill-comment}). With region, kill
7354: comments in region.
7355: @item M-@key{LFD}
7356: Like @key{RET} followed by inserting and aligning the @code{comment-start}
7357: string (@code{indent-new-comment-line}).
7358: @end table
7359:
7360: The command that creates a comment is @kbd{Meta-;} (@code{indent-for-comment}).
7361: If there is no comment already on the line, a new comment is created,
7362: aligned at a specific column called the @dfn{comment column}. The comment
7363: is created by inserting the string Emacs thinks comments should start with
7364: (the value of @code{comment-start}; see below). Point is left after that
7365: string. If the text of the line extends past the comment column, then the
7366: indentation is done to a suitable boundary (usually, at least one space is
7367: inserted). If the major mode has specified a string to terminate comments,
7368: that is inserted after point, to keep the syntax valid.
7369:
7370: @kbd{Meta-;} can also be used to align an existing comment. If a line
7371: already contains the string that starts comments, then @kbd{M-;} just moves
7372: point after it and re-indents it to the right column. Exception: comments
7373: starting in column 0 are not moved. Also, in particular modes, there are
7374: special rules for indenting certain kinds of comments in certain contexts.
7375:
7376: For example, in Lisp code, comments which start with two semicolons are
7377: indented as if they were lines of code, instead of at the comment column.
7378: Comments which start with three semicolons are supposed to start at the
7379: left margin. Emacs understands these conventions by indenting a
7380: double-semicolon comment using @key{TAB}, and by not changing the
7381: indentation of a triple-semicolon comment at all.
7382:
7383: In C code, a comment preceded on its line by nothing but whitespace
7384: is indented like a line of code.
7385:
7386: Even when an existing comment is properly aligned, @kbd{M-;} is still
7387: useful for moving directly to the start of the comment.
7388:
7389: @kindex C-u - C-x ;
7390: @findex kill-comment
7391: @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line,
7392: if there is one. The indentation before the start of the comment is killed
7393: as well. If there does not appear to be a comment in the line, nothing is
7394: done. To reinsert the comment on another line, move to the end of that
7395: line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that
7396: @kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
7397: with a negative argument. That command is programmed so that when it
7398: receives a negative argument it calls @code{kill-comment}. However,
7399: @code{kill-comment} is a valid command which you could bind directly to a
7400: key if you wanted to.
7401:
7402: @subsection Multiple Lines of Comments
7403:
7404: If you wish to align a large number of comments, give @kbd{Meta-;} an
7405: argument, and it indents what comments exist on that many lines, creating
7406: none. Point is left after the last line processed (unlike the no-argument
7407: case).
7408:
7409: @kindex M-LFD
7410: @cindex blank lines
7411: @cindex Auto Fill mode
7412: @findex indent-new-comment-line
7413: If you are typing a comment and find that you wish to continue it on
7414: another line, you can use the command @kbd{Meta-@key{LFD}} (@code{indent-new-comment-line}),
7415: which terminates the comment you are typing, creates a new blank line
7416: afterward, and begins a new comment indented under the old one. When Auto
7417: Fill mode is on, going past the fill column while typing a comment causes
7418: the comment to be continued in just this fashion. If point is not at the
7419: end of the line when @kbd{M-@key{LFD}} is typed, the text on the rest of
7420: the line becomes part of the new comment line.
7421:
7422: @subsection Options Controlling Comments
7423:
7424: @vindex comment-column
7425: @kindex C-x ;
7426: @findex set-comment-column
7427: The comment column is stored in the variable @code{comment-column}. You
7428: can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
7429: (@code{set-comment-column}) sets the comment column to the column point is
7430: at. @kbd{C-u C-x ;} sets the comment column to match the last comment
7431: before point in the buffer, and then does a @kbd{Meta-;} to align the
7432: current line's comment under the previous one. Note that @kbd{C-u - C-x ;}
7433: runs the function @code{kill-comment} as described above.
7434:
7435: @cindex major modes
7436: Many major modes supply default local values for the comment column.
7437: @xref{Locals}.
7438:
7439: @vindex comment-start-skip
7440: The comment commands recognize comments based on the regular expression
7441: that is the value of the variable @code{comment-start-skip}. This regexp
7442: should not match the null string. It may match more than the comment
7443: starting delimiter in the strictest sense of the word; for example, in C
7444: mode the value of the variable is @code{@t{"/\\*+ *"}}, which matches extra
7445: stars and spaces after the @samp{/*} itself. (Note that @samp{\\} is
7446: needed in Lisp syntax to include a @samp{\} in the string, which is needed
7447: to deny the first star its special meaning in regexp syntax; @pxref{Regexps})
7448:
7449: @vindex comment-start
7450: @vindex comment-end
7451: When a comment command makes a new comment, it inserts the value of
7452: @code{comment-start} to begin it. The value of @code{comment-end} is
7453: inserted after point, so that it will follow the text that you will insert
7454: into the comment. In C mode, @code{comment-start} has the value
7455: @code{"/* "} and @code{comment-end} has the value @code{" */"}.
7456:
7457: @vindex comment-multi-line
7458: @code{comment-multi-line} controls how @kbd{M-@key{LFD}} (@code{indent-new-comment-line})
7459: behaves when used inside a comment. If @code{comment-multi-line} is
7460: @code{nil}, as it normally is, then the comment on the starting line is
7461: terminated and a new comment is started on the new following line. If
7462: @code{comment-multi-line} is not @code{nil}, then the new following line is
7463: set up as part of the same comment that was found on the starting line.
7464: This is done by not inserting a terminator on the old line, and not
7465: inserting a starter on the new line. In languages where multi-line comments
7466: work, the choice of value for this variable is a matter of taste.
7467:
7468: @vindex comment-indent-hook
7469: The variable @code{comment-indent-hook} should contain a function that
7470: will be called to compute the indentation for a newly inserted comment or
7471: for aligning an existing comment. It is set differently by various major
7472: modes. The function is called with no arguments, but with point at the
7473: beginning of the comment, or at the end of a line if a new comment is to be
7474: inserted. It should return the column in which the comment ought to start.
7475: For example, in Lisp mode, the indent hook function bases its decision
7476: on how many semicolons begin an existing comment, and on the code in the
7477: preceding lines.
7478:
7479: @node Balanced Editing, Documentation, Comments, Programs
7480: @section Editing Without Unbalanced Parentheses
7481:
7482: @table @kbd
7483: @item M-(
7484: Put parentheses around next sexp(s) (@code{insert-parentheses}).
7485: @item M-)
7486: Move past next close parenthesis and re-indent
7487: (@code{move-over-close-and-reindent}).
7488: @end table
7489:
7490: @kindex M-(
7491: @kindex M-)
7492: @findex insert-parentheses
7493: @findex move-over-close-and-reindent
7494: The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
7495: (@code{move-over-close-and-reindent}) are designed to facilitate a style of
7496: editing which keeps parentheses balanced at all times. @kbd{M-(} inserts a
7497: pair of parentheses, either together as in @samp{()}, or, if given an
7498: argument, around the next several sexps, and leaves point after the open
7499: parenthesis. Instead of typing @kbd{( F O O )}, you can type @kbd{M-( F O
7500: O}, which has the same effect except for leaving the cursor before the
7501: close parenthesis. Then you would type @kbd{M-)}, which moves past the
7502: close parenthesis, deleting any indentation preceding it (in this example
7503: there is none), and indenting with @key{LFD} after it.
7504:
7505: @node Documentation, Change Log, Balanced Editing, Programs
7506: @section Documentation Commands
7507:
7508: @kindex C-h f
7509: @findex describe-function
7510: @kindex C-h v
7511: @findex describe-variable
7512: As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
7513: (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
7514: be used to print documentation of functions and variables that you want to
7515: call. These commands use the minibuffer to read the name of a function or
7516: variable to document, and display the documentation in a window.
7517:
7518: For extra convenience, these commands provide default arguments based on
7519: the code in the neighborhood of point. @kbd{C-h f} sets the default to the
7520: function called in the innermost list containing point. @kbd{C-h v} uses
7521: the symbol name around or adjacent to point as its default.
7522:
7523: @findex manual-entry
7524: Documentation on Unix commands, system calls and libraries can be
7525: obtained with the @kbd{M-x manual-entry} command. This reads a topic as an
7526: argument, and displays the text on that topic from the Unix manual.
7527: @code{manual-entry} always searches all 8 sections of the manual, and
7528: concatenates all the entries that are found. For example, the topic
7529: @samp{termcap} finds the description of the termcap library from section 3,
7530: followed by the description of the termcap data base from section 5.
7531:
7532: @node Change Log, Tags, Documentation, Programs
7533: @section Change Logs
7534:
7535: @cindex change log
7536: @findex add-change-log-entry
7537: The Emacs command @kbd{M-x add-change-log-entry} helps you keep a record
7538: of when and why you have changed a program. It assumes that you have a
7539: file in which you write a chronological sequence of entries describing
7540: individual changes. The default is to store the change entries in a file
7541: called @file{ChangeLog} in the same directory as the file you are editing.
7542: The same @file{ChangeLog} file therefore records changes for all the files
7543: in the directory.
7544:
7545: A change log entry starts with a header line that contains your name and
7546: the current date. Aside from these header lines, every line in the change
7547: log starts with a tab. One entry can describe several changes; each change
7548: starts with a line starting with a tab and a star. @kbd{M-x add-change-log-entry}
7549: visits the change log file and creates a new entry unless the most recent
7550: entry is for today's date and your name. In either case, it adds a new
7551: line to start the description of another change just after the header line
7552: of the entry. When @kbd{M-x add-change-log-entry} is finished, all is
7553: prepared for you to edit in the description of what you changed and how.
7554: You must then save the change log file yourself.
7555:
7556: The change log file is always visited in Indented Text mode, which means
7557: that @key{LFD} and auto-filling indent each new line like the previous
7558: line. This is convenient for entering the contents of an entry, which must
7559: all be indented. @xref{Text Mode}.
7560:
7561: Here is an example of the formatting conventions used in the change log
7562: for Emacs:
7563:
7564: @smallexample
7565: Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep)
7566:
7567: * xdisp.c (try_window_id):
7568: If C-k is done at end of next-to-last line,
7569: this fn updates window_end_vpos and cannot leave
7570: window_end_pos nonnegative (it is zero, in fact).
7571: If display is preempted before lines are output,
7572: this is inconsistent. Fix by setting
7573: blank_end_of_window to nonzero.
7574:
7575: Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep)
7576:
7577: * cmds.c (Fnewline):
7578: Call the auto fill hook if appropriate.
7579:
7580: * xdisp.c (try_window_id):
7581: If point is found by compute_motion after xp, record that
7582: permanently. If display_text_line sets point position wrong
7583: (case where line is killed, point is at eob and that line is
7584: not displayed), detect and set it again in final compute_motion.
7585: @end smallexample
7586:
7587: @node Tags,, Change Log, Programs
7588: @section Tag Tables
7589: @cindex tag table
7590:
7591: A @dfn{tag table} is a description of how a multi-file program is broken
7592: up into files. It lists the names of the component files and the names and
7593: positions of the functions in each file. Grouping the related files makes
7594: it possible to search or replace through all the files with one command.
7595: Recording the function names and positions makes possible the @kbd{Meta-.}
7596: command which you can use to find the definition of a function without
7597: having to know which of the files it is in.
7598:
7599: Tag tables are stored in files called @dfn{tag table files}. The
7600: conventional name for a tag table file is @code{TAGS}.
7601:
7602: Each entry in the tag table records the name of one tag, the name of the
7603: file that the tag is defined in (implicitly), and the position in that file
7604: of the tag's definition.
7605:
7606: Just what names from the described files are recorded in the tag table
7607: depends on the programming language of the described file. They normally
7608: include all functions and subroutines, and may also include global
7609: variables, data types, and anything else convenient. In any case, each
7610: name recorded is called a @dfn{tag}.
7611:
7612: In Lisp code, any function defined with @code{defun}, any variable
7613: defined with @code{defvar} or @code{defconst}, and in general the first
7614: argument of any expression that starts with @samp{(def} in column zero, is
7615: a tag.
7616:
7617: In C code, any C function is a tag, and so is any typedef if @code{-t} is
7618: specified when the tag table is constructed.
7619:
7620: In Fortran code, functions and subroutines are tags.
7621:
7622: @subsection Creating Tag Tables
7623: @cindex etags program
7624:
7625: The @code{etags} program is used to create a tag table file. It knows
7626: the syntax of C, Fortran and Emacs Lisp. To use @code{etags}, type
7627:
7628: @example
7629: etags @var{inputfiles}@dots{}
7630: @end example
7631:
7632: @noindent
7633: as a shell command. It reads the specified files and writes a tag table
7634: named @code{TAGS} in the current working directory. @code{etags}
7635: recognizes the language used in an input file based on its file name and
7636: contents; there are no switches for specifying the language. The @code{-t}
7637: switch tells @code{etags} to record typedefs in C code as tags.
7638:
7639: If the tag table data become outdated due to changes in the files
7640: described in the table, the way to update the tag table is the same way it
7641: was made in the first place. It is not necessary to do this often.
7642:
7643: If the tag table fails to record a tag, or records it for the wrong file,
7644: then Emacs cannot possibly find its definition. However, if the position
7645: recorded in the tag table becomes a little bit wrong (due to some editing
7646: in the file that the tag definition is in), the only consequence is to slow
7647: down finding the tag slightly. Even if the stored position is very wrong,
7648: Emacs will still find the tag, but it must search the entire file for it.
7649:
7650: So you should update a tag table when you define new tags that you want
7651: to have listed, or when you move tag definitions from one file to another,
7652: or when changes become substantial. Normally there is no need to update
7653: the tag table after each edit, or even every day.
7654:
7655: @subsection Selecting a Tag Table
7656:
7657: @vindex tags-file-name
7658: @findex visit-tags-table
7659: Emacs has at any time one @dfn{selected} tag table, and all the commands
7660: for working with tag tables use the selected one. To select a tag table,
7661: type @kbd{M-x visit-tags-table}, which reads the tag table file name as an
7662: argument. The name @code{TAGS} in the default directory is used as the
7663: default file name.
7664:
7665: All this command does is store the file name in the variable
7666: @code{tags-file-name}. Emacs does not actually read in the tag table
7667: contents until you try to use them. Setting this variable yourself is just
7668: as good as using @code{visit-tags-table}. The variable's initial value is
7669: @code{nil}; this value tells all the commands for working with tag tables
7670: that they must ask for a tag table file name to use.
7671:
7672: @subsection Finding a Tag
7673:
7674: The most important thing that a tag table enables you to do is to find
7675: the definition of a specific tag.
7676:
7677: @table @kbd
7678: @item M-.@: @var{tag}
7679: Find first definition of @var{tag} (@code{find-tag}).
7680: @item C-u M-.
7681: Find next alternate definition of last tag specified.
7682: @item C-x 4 .@: @var{tag}
7683: Find first definition of @var{tag}, but display it in another window
7684: (@code{find-tag-other-window}).
7685: @end table
7686:
7687: @kindex M-.
7688: @findex find-tag
7689: @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of a
7690: specified tag. It searches through the tag table for that tag, as a
7691: string, and then uses the tag table info to determine the file that the
7692: definition is in and the approximate character position in the file of the
7693: definition. Then @code{find-tag} visits that file, moves point to the
7694: approximate character position, and starts searching ever-increasing
7695: distances away for the the text that should appear at the beginning of the
7696: definition.
7697:
7698: If an empty argument is given (just type @key{RET}), the sexp in the
7699: buffer before or around point is used as the name of the tag to find.
7700: @xref{Lists}, for info on sexps.
7701:
7702: The argument to @code{find-tag} need not be the whole tag name; it can be
7703: a substring of a tag name. However, there can be many tag names containing
7704: the substring you specify. Since @code{find-tag} works by searching the
7705: text of the tag table, it finds the first tag in the table that the
7706: specified substring appears in. The way to find other tags that match the
7707: substring is to give @code{find-tag} a numeric argument, as in @kbd{M-0 M-.};
7708: this does not read a tag name, but continues searching the tag table's text
7709: for another tag containing the same substring last used.
7710:
7711: @kindex C-x 4 .
7712: @findex find-tag-other-window
7713: Like most commands that can switch buffers, @code{find-tag} has another
7714: similar command that displays the new buffer in another window. @kbd{C-x 4
7715: .}@: invokes the function @code{find-tag-other-window}.
7716:
7717: @subsection Searching and Replacing with Tag Tables
7718:
7719: The commands in this section visit and search all the files listed in the
7720: selected tag table, one by one.
7721:
7722: @table @kbd
7723: @item M-x tags-search
7724: Search for the specified regexp through the files in the selected tag
7725: table.
7726: @item M-x tags-query-replace
7727: Perform a @code{query-replace} on each file in the selected tag table.
7728: @item M-,
7729: Restart one of the commands above, from the current location of point
7730: (@code{tags-loop-continue}).
7731: @end table
7732:
7733: @findex tags-search
7734: @kbd{M-x tags-search} reads a regexp using the minibuffer, then visits
7735: the files of the selected tag table one by one, and searches through each
7736: one for that regexp. As soon as an occurrence is found, @code{tags-search}
7737: returns.
7738:
7739: @kindex M-,
7740: @findex tags-loop-continue
7741: Having found one match, you probably want to find all the rest. To find
7742: one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
7743: @code{tags-search}. This searches the rest of the current buffer, followed
7744: by the remaining files of the tag table.
7745:
7746: @findex tags-query-replace
7747: @kbd{M-x tags-query-replace} performs a single @code{query-replace}
7748: through all the files in the tag table. It reads a string to search for
7749: and a string to replace with, just like ordinary @kbd{M-x query-replace}.
7750: It searches much like @kbd{M-x tags-search} but repeatedly, processing
7751: matches according to your input. @xref{Replace}, for more information on
7752: @code{query-replace}.@refill
7753:
7754: It is possible to get through all the files in the tag table with a
7755: single invocation of @kbd{M-x tags-query-replace}. But since any
7756: unrecognized character causes the command to exit, you may need to continue
7757: where you left off. @kbd{M-,} can be used for this. It resumes the last
7758: tags search or replace command that you did.
7759:
7760: It may have struck you that @code{tags-search} is a lot like @code{grep}.
7761: You can also run @code{grep} itself as an inferior of Emacs and have Emacs
7762: show you the matching lines one by one. This works mostly the same as
7763: running a compilation and having Emacs show you where the errors were.
7764: @xref{Compilation}.
7765:
7766: @subsection Stepping Through a Tag Table
7767: @findex next-file
7768:
7769: If you wish to process all the files in the selected tag table, but
7770: @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} in particular are not what
7771: you want, you can use @kbd{M-x next-file}.
7772:
7773: @table @kbd
7774: @item C-u M-x next-file
7775: With a numeric argument, regardless of its value, visit the first
7776: file in the tag table, and prepare to advance sequentially by files.
7777: @item M-x next-file
7778: Visit the next file in the selected tag table.
7779: @end table
7780:
7781: @subsection Tag Table Inquiries
7782:
7783: @table @kbd
7784: @item M-x list-tags
7785: Display a list of the tags defined in a specific program file.
7786: @item M-x tags-apropos
7787: Display a list of all tags matching a specified regexp.
7788: @end table
7789:
7790: @findex list-tags
7791: @kbd{M-x list-tags} reads the name of one of the files described by the
7792: selected tag table, and displays a list of all the tags defined in that
7793: file. The ``file name'' argument is really just a string to compare
7794: against the names recorded in the tag table; it is read as a string rather
7795: than as a file name. Therefore, completion and defaulting are not
7796: available, and you must enter the string the same way it appears in the tag
7797: table. Do not include a directory as part of the file name unless the file
7798: name recorded in the tag table includes a directory.
7799:
7800: @findex tags-apropos
7801: @kbd{M-x tags-apropos} is like @code{apropos} for tags. It reads a regexp,
7802: then finds all the tags in the selected tag table whose entries match that
7803: regexp, and displays the tag names found.
7804:
7805: @node Running, Abbrevs, Programs, Top
7806: @chapter Compiling and Testing Programs
7807:
7808: The previous chapter discusses the Emacs commands that are useful for
7809: making changes in programs. This chapter deals with commands that assist
7810: in the larger process of developing and maintaining programs.
7811:
7812: @menu
7813: * Compilation:: Compiling programs in languages other than Lisp
7814: (C, Pascal, etc.)
7815: * Modes: Lisp Modes. Various modes for editing Lisp programs, with
7816: different facilities for running the Lisp programs.
7817: * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
7818: * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
7819: * Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
7820: * Debug: Lisp Debug. Debugging Lisp programs running in Emacs.
7821: * External Lisp:: Communicating through Emacs with a separate Lisp.
7822: @end menu
7823:
7824: @node Compilation, Lisp Modes, Running, Running
7825: @section Running `make', or Compilers Generally
7826: @cindex inferior process
7827: @cindex make
7828: @cindex compilation errors
7829: @cindex error log
7830:
7831: Emacs can run compilers for noninteractive languages such as C and
7832: Fortran as inferior processes, feeding the error log into an Emacs buffer.
7833: It can also parse the error messages and visit the files in which errors
7834: are found, moving point right to the line where the error occurred.
7835:
7836: @table @kbd
7837: @item M-x compile
7838: Run a compiler asynchronously under Emacs, with error messages to
7839: @samp{*compilation*} buffer.
7840: @item M-x grep
7841: Run @code{grep} asynchronously under Emacs, with matching lines
7842: listed in the @samp{*compilation*} buffer.
7843: @item M-x kill-compiler
7844: @itemx M-x kill-grep
7845: Kill the running compilation or @code{grep} subprocess.
7846: @item C-x `
7847: Visit the locus of the next compiler error message or @code{grep} match.
7848: @end table
7849:
7850: @findex compile
7851: To run @code{make} or another compiler, do @kbd{M-x compile}. This command
7852: reads a shell command line using the minibuffer, and then executes the
7853: specified command line in an inferior shell with output going to the buffer
7854: named @samp{*compilation*}. The current buffer's default directory is used
7855: as the working directory for the execution of the command; normally,
7856: therefore, the makefile comes from this directory.
7857:
7858: @vindex compile-command
7859: When the shell command line is read, the minibuffer appears containing a
7860: default command line, which is the command you used the last time you did
7861: @kbd{M-x compile}. If you type just @key{RET}, the same command line is used
7862: again. The first @kbd{M-x compile} provides @code{make -k} as the default.
7863: The default is taken from the variable @code{compile-command}; if the
7864: appropriate compilation command for a file is something other than
7865: @code{make -k}, it can be useful to have the file specify a local value for
7866: @code{compile-command} (@pxref{File Variables}).
7867:
7868: Starting a compilation causes the buffer @samp{*compilation*} to be
7869: displayed in another window but not selected. Its mode line tells you
7870: whether compilation is finished, with the word @samp{run} or @samp{exit} inside
7871: the parentheses. You do not have to keep this buffer visible; compilation
7872: continues in any case.
7873:
7874: @findex kill-compilation
7875: To kill the compilation process, do @kbd{M-x kill-compilation}. You will
7876: see that the mode line of the @samp{*compilation*} buffer changes to say
7877: @samp{signal} instead of @samp{run}. Starting a new compilation also kills
7878: any running compilation, as only one can exist at any time. However, this
7879: requires confirmation before actually killing a compilation that is
7880: running.@refill
7881:
7882: @kindex C-x `
7883: @findex next-error
7884: To parse the compiler error messages, type @kbd{C-x `} (@code{next-error}). The
7885: character following the @kbd{C-x} is the grave accent, not the single
7886: quote. This command displays the buffer @samp{*compilation*} in one window
7887: and the buffer in which the next error occurred in another window. Point
7888: in that buffer is moved to the line where the error was found. The
7889: corresponding error message is scrolled to the top of the window in which
7890: @samp{*compilation*} is displayed.
7891:
7892: The first time @kbd{C-x `} is used, after the start of a compilation, it
7893: parses all the error messages, visits all the files that have error
7894: messages, and makes markers pointing at the lines that the error messages
7895: refer to. Then it moves to the first error message location. Subsequent
7896: uses of @kbd{C-x `} advance down the data set up by the first use. When
7897: the preparsed error messages are exhausted, the next @kbd{C-x `} checks for
7898: any more error messages that have come in; this is useful if you start
7899: editing the compiler errors while the compilation is still going on. If no
7900: more error messages have come in, @kbd{C-x `} reports an error.
7901:
7902: @kbd{C-u C-x `} discards the preparsed error message data and parses the
7903: @samp{*compilation*} buffer over again, then displaying the first error.
7904: This way, you can process the same set of errors again.
7905:
7906: Instead of running a compiler, you can run @code{grep} and see the lines
7907: on which matches were found. To do this, type @kbd{M-x grep} with an argument
7908: line that contains the same arguments you would give @code{grep} when running
7909: it normally: a @code{grep}-style regexp (usually in doublequotes to quote
7910: the shell's special characters) followed by filenames which may use wildcards.
7911: The output from @code{grep} goes in the @samp{*compilation*} buffer and the
7912: lines that matched can be found with @kbd{C-x `} as if they were compilation
7913: errors.
7914:
7915: Note: a shell is used to run the compile command, but the shell is told
7916: that it should be noninteractive. This means in particular that the shell
7917: starts up with no prompt. If you find your usual shell prompt making an
7918: unsightly appearance in the @samp{*compilation*} buffer, it means you have
7919: made a mistake in your shell's init file (@file{.cshrc} or @file{.shrc} or
7920: @dots{}) by setting the prompt unconditionally. The shell init file should
7921: set the prompt only if there already is a prompt. In @code{csh}, here is
7922: how to do it:
7923:
7924: @example
7925: if ($?prompt) set prompt = ...
7926: @end example
7927:
7928: @node Lisp Modes, Lisp Libraries, Compilation, Running
7929: @section Major Modes for Lisp
7930:
7931: Emacs has four different major modes for Lisp. They are the same in
7932: terms of editing commands, but differ in the commands for executing Lisp
7933: expressions.
7934:
7935: @table @asis
7936: @item Emacs-Lisp mode
7937: The mode for editing source files of programs to run in Emacs Lisp.
7938: This mode defines @kbd{C-M-x} to evaluate the current defun.
7939: @xref{Lisp Libraries}.
7940: @item Lisp Interaction mode
7941: The mode for an interactive session with Emacs Lisp. It defines
7942: @key{LFD} to evaluate the sexp before point and insert its value in the
7943: buffer. @xref{Lisp Interaction}.
7944: @item Lisp mode
7945: The mode for editing source files of programs that run in Lisps other
7946: than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
7947: to an inferior Lisp process. @xref{External Lisp}.
7948: @item Inferior Lisp mode
7949: The mode for an interactive session with an inferior Lisp process.
7950: This mode combines the special features of Lisp mode and Shell mode
7951: (@pxref{Shell}).
7952: @end table
7953:
7954: @node Lisp Libraries, Lisp Eval, Lisp Modes, Running
7955: @section Libraries of Lisp Code for Emacs
7956: @cindex libraries
7957: @cindex loading Lisp code
7958:
7959: Lisp code for Emacs editing commands is stored in files whose names
7960: conventionally end in @file{.el}. This ending tells Emacs to edit them in
7961: Emacs-Lisp mode, so you can use the @kbd{C-M-x} command described in the
7962: following section to install changed functions.
7963:
7964: @findex load
7965: Only the maintainers of such a file will want to edit its contents or
7966: evaluate text from it, but every user must be able to load the file. This
7967: is done with @kbd{M-x load}.
7968:
7969: @kbd{M-x load} reads a file name using the minibuffer and executes the
7970: specified file as Lisp code. But it has an important difference from all
7971: other Emacs commands that read file names: it searches a sequence of
7972: directories, and tries three file names in each directory.
7973:
7974: Because normally one does not want the argument to @code{load} to contain
7975: an explicit directory name, the usual mechanism for reading file names
7976: cannot be used, and therefore file name completion is not available.
7977: (Which directory would it complete in, anyway?)
7978:
7979: The argument you give to @kbd{M-x load} is usually not the full file
7980: name. Usually you omit the @file{.el} that the file name ends in.
7981: @kbd{M-x load} tries three file names in each directory: first, the name
7982: you specified; second, that name with @file{.elc} appended; third, that
7983: name with @file{.el} appended. A @file{.elc} file would be the result of
7984: compiling the Lisp file into byte code; it is loaded if possible in
7985: preference to the Lisp file itself because the compiled file will load and
7986: run faster.
7987:
7988: @vindex load-path
7989: The sequence of directories searched by @kbd{M-x load} is specified by
7990: the variable @code{load-path}, a list of strings that are directory names.
7991: Normally the first element of this list is @code{nil}, which means to
7992: search the current default directory at that point; the remaining elements
7993: are the names of the directories in which the Lisp code of Emacs itself is
7994: stored. Therefore, you can load an installed Emacs library without having
7995: to specify a directory name.
7996:
7997: Often you do not have to run the @code{load} command yourself, because
7998: the commands in a library have permanent definitions to @dfn{autoload}
7999: that library. Running any of those commands causes @code{load} to be
8000: called to load the library; this replaces the autoload definitions with
8001: the real ones from the library.
8002:
8003: If autoloading a file does not finish, either because of an error or
8004: because of a @kbd{C-g} quit, all function definitions made by the file are
8005: undone automatically. So are any calls to @code{provide}. As a consequence,
8006: if you use one of the autoloadable commands again, the entire file will be
8007: loaded a second time. This prevents problems where the command is no
8008: longer autoloading but it works wrong because not all the file was loaded.
8009: Function definitions are undone only for autoloading; explicit calls to
8010: @code{load} do not undo anything if loading is not completed.
8011:
8012: @findex byte-compile-file
8013: The way to make a byte-code compiled file from an Emacs-Lisp source file
8014: is with @kbd{M-x byte-compile-file}. The default argument for this
8015: function is the file visited in the current buffer. It reads the specified
8016: file, compiles it into byte code, and writes an output file whose name is
8017: made by appending @file{c} to the input file name. Thus, the file
8018: @file{rmail.el} would be compiled into @file{rmail.elc}.
8019:
8020: @findex byte-recompile-directory
8021: To recompile the changed Lisp files in a directory, use @kbd{M-x
8022: byte-recompile-directory}. Specify just the directory name as an argument.
8023: Each @file{.el} file that has been byte-compiled before is byte-compiled
8024: again if it has changed since the previous compilation. A numeric argument
8025: to this command tells it to offer to compile each @file{.el} file that has
8026: not already been compiled. You must answer @kbd{y} or @kbd{n} to each
8027: offer.
8028:
8029: @findex batch-byte-compile
8030: Emacs can be invoked noninteractively from the shell to do byte compilation
8031: with the aid of the function @code{batch-byte-compile}. In this case,
8032: the files to be compiled are specified with command-line arguments.
8033: Use a shell command of the form
8034:
8035: @example
8036: emacs -batch -f batch-byte-compile @var{files}...
8037: @end example
8038:
8039: Directory names may also be given as arguments;
8040: @code{byte-recompile-directory} is invoked (in effect) on each such directory.
8041: @code{batch-byte-compile} uses all the remaining command-line arguments as
8042: file or directory names, then kills the Emacs process.
8043:
8044: @cindex mocklisp
8045: GNU Emacs can run Mocklisp files by converting them to Emacs Lisp first.
8046: To convert a Mocklisp file, visit it and then type @kbd{M-x
8047: convert-mocklisp-buffer}. Then save the resulting buffer of Lisp file in a
8048: file whose name ends in @file{.el} and use the new file as a Lisp library.
8049:
8050: @node Lisp Eval, Lisp Debug, Lisp Libraries, Running
8051: @section Evaluating Emacs-Lisp Expressions
8052: @cindex Emacs-Lisp mode
8053:
8054: @findex emacs-lisp-mode
8055: Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp
8056: mode; normally this will happen based on the file name that ends in
8057: @file{.el}. By contrast, Lisp mode itself is used for editing Lisp programs
8058: intended for other Lisp systems. Emacs-Lisp mode can be selected with the
8059: command @kbd{M-x emacs-lisp-mode}.
8060:
8061: For testing of Lisp programs to run in Emacs, it is useful to be able to
8062: evaluate part of the program as it is found in the Emacs buffer. For
8063: example, after changing the text of a Lisp function definition, evaluating
8064: the definition installs the change for future calls to the function.
8065: Evaluation of Lisp expressions is also useful in any kind of editing task
8066: for invoking noninteractive functions (functions that are not commands).
8067:
8068: @table @kbd
8069: @item M-@key{ESC}
8070: Read a Lisp expression in the minibuffer, evaluate it, and print the
8071: value in the minibuffer (@code{eval-expression}).
8072: @item C-x C-e
8073: Evaluate the Lisp expression before point, and print the value in the
8074: minibuffer (@code{eval-last-sexp}).
8075: @item C-M-x
8076: Evaluate the defun containing or after point, and print the value in
8077: the minibuffer (@code{eval-defun}).
8078: @item M-x eval-region
8079: Evaluate all the Lisp expressions in the region.
8080: @item M-x eval-current-buffer
8081: Evaluate all the Lisp expressions in the buffer.
8082: @end table
8083:
8084: @kindex M-ESC
8085: @findex eval-expression
8086: @kbd{M-@key{ESC}} (@code{eval-expression}) is the most basic command for evaluating
8087: a Lisp expression interactively. It reads the expression using the
8088: minibuffer, so you can execute any expression on a buffer regardless of
8089: what the buffer contains. When the expression is evaluated, the current
8090: buffer is once again the buffer that was current when @kbd{M-@key{ESC}} was
8091: typed.
8092:
8093: @kbd{M-@key{ESC}} can easily confuse users who do not understand it,
8094: especially on keyboards with autorepeat where it can result from holding
8095: down the @key{ESC} key for too long. Therefore, @code{eval-expression} is
8096: normally a disabled command. Attempting to use this command asks for
8097: confirmation and gives you the option of enabling it; once you enable the
8098: command, confirmation will no longer be required for it.
8099: @xref{Disabling}.@refill
8100:
8101: @kindex C-M-x
8102: @findex eval-defun
8103: In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the function @code{eval-defun},
8104: which parses the defun containing or following point as a Lisp expression
8105: and evaluates it. The value is printed in the echo area. This command is
8106: convenient for installing in the Lisp environment changes that you have
8107: just made in the text of a function definition.
8108:
8109: @kindex C-x C-e
8110: @findex eval-last-sexp
8111: The command @kbd{C-x C-e} (@code{eval-last-sexp}) performs a similar job
8112: but is available in all major modes, not just Emacs-Lisp mode. It finds
8113: the sexp before point, reads it as a Lisp expression, evaluates it, and
8114: prints the value in the echo area. It is sometimes useful to type in an
8115: expression and then, with point still after it, type @kbd{C-x C-e}.
8116:
8117: If @kbd{C-M-x} or @kbd{C-x C-e} is given a numeric argument, it prints the value
8118: by insertion into the current buffer at point, rather than in the echo
8119: area. The argument value does not matter.
8120:
8121: @findex eval-region
8122: @findex eval-current-buffer
8123: The most general command for evaluating Lisp expressions from a buffer is
8124: @code{eval-region}. @kbd{M-x eval-region} parses the text of the region as one or
8125: more Lisp expressions, evaluating them one by one. @kbd{M-x eval-current-buffer}
8126: is similar but evaluates the entire buffer. This is a reasonable way to
8127: install the contents of a file of Lisp code that you are just ready to
8128: test. After finding and fixing a bug, use @kbd{C-M-x} on each function
8129: that you change, to keep the Lisp world in step with the source file.
8130:
8131: @node Lisp Debug, Lisp Interaction, Lisp Eval, Running
8132: @section The Lisp Debugger
8133: @cindex debugger
8134:
8135: @vindex debug-on-error
8136: @vindex debug-on-quit
8137: GNU Emacs contains a debugger for Lisp programs executing inside it.
8138: This debugger is normally not used; many commands frequently get Lisp
8139: errors when invoked in inappropriate contexts (such as @kbd{C-f} at the end
8140: of the buffer) and it would be very unpleasant for that to enter a special
8141: debugging mode. When you want to make Lisp errors invoke the debugger, you
8142: must set the variable @code{debug-on-error} to non-@code{nil}. Quitting
8143: with @kbd{C-g} is not considered an error, and @code{debug-on-error} has no
8144: effect on the handling of @kbd{C-g}. However, if you set
8145: @code{debug-on-quit} non-@code{nil}, @kbd{C-g} will invoke the debugger.
8146: This can be useful for debugging an infinite loop; type @kbd{C-g} once the
8147: loop has had time to reach its steady state. @code{debug-on-quit} has no
8148: effect on errors.@refill
8149:
8150: @findex debug-on-entry
8151: @findex cancel-debug-on-entry
8152: @findex debug
8153: You can also cause the debugger to be entered when a specified function
8154: is called, or at a particular place in Lisp code. Use @kbd{M-x
8155: debug-on-entry} with argument @var{fun-name} to cause function
8156: @var{fun-name} to enter the debugger as soon as it is called. Use
8157: @kbd{M-x cancel-debug-on-entry} to make the function stop entering the
8158: debugger when called. (Redefining the function also does this.) To enter
8159: the debugger from some other place in Lisp code, you must insert the
8160: expression @code{(debug)} there and install the changed code with
8161: @kbd{C-M-x}. @xref{Lisp Eval}.@refill
8162:
8163: When the debugger is entered, it displays the previously selected buffer
8164: in one window and a buffer named @samp{*Backtrace*} in another window. The
8165: backtrace buffer contains one line for each level of Lisp function
8166: execution currently going on. At the beginning of this buffer is a message
8167: describing the reason that the debugger was invoked (such as, what error
8168: message if it was invoked due to an error).
8169:
8170: The backtrace buffer is read-only, and is in a special major mode,
8171: Backtrace mode, in which letters are defined as debugger commands. The
8172: usual Emacs editing commands are available; you can switch windows to
8173: examine the buffer that was being edited at the time of the error, and you
8174: can also switch buffers, visit files, and do any other sort of editing.
8175: However, the debugger is a recursive editing level (@pxref{Recursive Edit})
8176: and it is wise to go back to the backtrace buffer and exit the debugger
8177: officially when you don't want to use it any more. Exiting the debugger
8178: kills the backtrace buffer.
8179:
8180: @cindex current stack frame
8181: The contents of the backtrace buffer show you the functions that are
8182: executing and the arguments that were given to them. It has the additional
8183: purpose of allowing you to specify a stack frame by moving point to the line
8184: describing that frame. The frame whose line point is on is considered the
8185: @dfn{current frame}. Some of the debugger commands operate on the current
8186: frame. Debugger commands are mainly used for stepping through code an
8187: expression at a time. Here is a list of them.
8188:
8189: @table @kbd
8190: @item c
8191: Exit the debugger and continue execution. In most cases, execution of the
8192: program continues as if the debugger had never been entered (aside from the
8193: effect of any variables or data structures you may have changed while
8194: inside the debugger). This includes entry to the debugger due to function
8195: entry or exit, explicit invocation, quitting or certain errors. Most
8196: errors cannot be continued; trying to continue one of them causes the same
8197: error to occur again.
8198: @item d
8199: Continue execution, but enter the debugger the next time a Lisp
8200: function is called. This allows you to step through the
8201: subexpressions of an expression, seeing what values the subexpressions
8202: compute and what else they do.
8203:
8204: The stack frame made for the function call which enters the debugger
8205: in this way will be flagged automatically for the debugger to be called
8206: when the frame is exited. You can use the @kbd{u} command to cancel
8207: this flag.
8208: @item b
8209: Set up to enter the debugger when the current frame is exited. Frames
8210: that will invoke the debugger on exit are flagged with stars.
8211: @item u
8212: Don't enter the debugger when the current frame is exited. This
8213: cancels a @kbd{b} command on that frame.
8214: @item e
8215: Read a Lisp expression in the minibuffer, evaluate it, and print the
8216: value in the echo area. The same as the command @kbd{M-@key{ESC}},
8217: except that @kbd{e} is not normally disabled like @kbd{M-@key{ESC}}.
8218: @item q
8219: Terminate the program being debugged; return to top level Emacs
8220: command execution.
8221:
8222: If the debugger was entered due to a @kbd{C-g} but you really want
8223: to quit, not to debug, use the @kbd{q} command.
8224: @item r
8225: Return a value from the debugger. The value is computed by reading an
8226: expression with the minibuffer and evaluating it.
8227:
8228: The value returned by the debugger makes a difference when the debugger
8229: was invoked due to exit from a Lisp call frame (as requested with @kbd{b});
8230: then the value specified in the @kbd{r} command is used as the value of
8231: that frame.
8232:
8233: The debugger's return value also matters with many errors. For example,
8234: @code{wrong-type-argument} errors will use the debugger's return value
8235: instead of the invalid argument; @code{no-catch} errors will use the
8236: debugger value as a throw tag instead of the tag that was not found.
8237: If an error was signaled by calling the Lisp function @code{signal},
8238: the debugger's return value is returned as the value of @code{signal}.
8239: @end table
8240:
8241: @node Lisp Interaction, External Lisp, Lisp Debug, Running
8242: @section Lisp Interaction Buffers
8243:
8244: The buffer @samp{*scratch*} which is selected when Emacs starts up is
8245: provided for evaluating Lisp expressions interactively inside Emacs. Both
8246: the expressions you evaluate and their output goes in the buffer.
8247:
8248: The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
8249: is the same as Emacs-Lisp mode except for one command, @key{LFD}. In
8250: Emacs-Lisp mode, @key{LFD} is an indentation command, as usual. In Lisp
8251: Interaction mode, @key{LFD} is bound to @code{eval-print-last-sexp}. This
8252: function reads the Lisp expression before point, evaluates it, and inserts
8253: the value in printed representation before point.
8254:
8255: Thus, the way to use the @samp{*scratch*} buffer is to insert Lisp expressions
8256: at the end, ending each one with @key{LFD} so that it will be evaluated.
8257: The result is a complete typescript of the expressions you have evaluated
8258: and their values.
8259:
8260: @findex lisp-interaction-mode
8261: The rationale for this feature is that Emacs must have a buffer when it
8262: starts up, but that buffer is not useful for editing files since a new
8263: buffer is made for every file that you visit. The Lisp interpreter
8264: typescript is the most useful thing I can think of for the initial buffer
8265: to do. @kbd{M-x lisp-interaction-mode} will put any buffer in Lisp
8266: Interaction mode.
8267:
8268: @node External Lisp,, Lisp Interaction, Running
8269: @section Running an External Lisp
8270:
8271: Emacs has facilities for running programs in other Lisp systems. You can
8272: run a Lisp process as an inferior of Emacs, and pass expressions to it to
8273: be evaluated. You can also pass changed function definitions directly from
8274: the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
8275: process.
8276:
8277: @findex run-lisp
8278: To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs the
8279: program named @code{lisp}, the same program you would run by typing
8280: @code{lisp} as a shell command, with both input and output going through an
8281: Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal output''
8282: from Lisp will go into the buffer, advancing point, and any ``terminal
8283: input'' for Lisp comes from text in the buffer. To give input to Lisp, go
8284: to the end of the buffer and type the input, terminated by @key{RET}. The
8285: @samp{*lisp*} buffer is in Inferior Lisp mode, a mode which has all the
8286: special characteristics of Lisp mode and Shell mode (@pxref{Shell}).
8287:
8288: @findex lisp-mode
8289: For the source files of programs to run in external Lisps, use Lisp mode.
8290: This mode can be selected with @kbd{M-x lisp-mode}, and is used automatically
8291: for files whose names end in @file{.l} or @file{.lisp}, as most Lisp
8292: systems usually expect.
8293:
8294: @kindex C-M-x
8295: @findex lisp-send-defun
8296: When you edit a function in a Lisp program you are running, the easiest
8297: way to send the changed definition to the inferior Lisp process is the key
8298: @kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-send-defun},
8299: which finds the defun around or following point and sends it as input to
8300: the Lisp process. (Emacs can send input to any inferior process regardless
8301: of what buffer is current.)
8302:
8303: Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs
8304: to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
8305: programs to be run in Emacs): in both modes it has the effect of installing
8306: the function definition that point is in, but the way of doing so is
8307: different according to where the relevant Lisp environment is found.
8308: @xref{Lisp Modes}.
8309:
8310: @node Abbrevs, Picture, Running, Top
8311: @chapter Abbrevs
8312: @cindex abbrevs
8313: @cindex expansion (of abbrevs)
8314:
8315: An @dfn{abbrev} is a word which @dfn{expands}, if you insert it, into some
8316: different text. Abbrevs are defined by the user to expand in specific
8317: ways. For example, you might define @samp{foo} as an abbrev expanding to
8318: @samp{find outer otter}. With this abbrev defined, you would be able to
8319: get @samp{find outer otter } into the buffer by typing @kbd{f o o @key{SPC}}.
8320:
8321: @findex abbrev-mode
8322: @vindex abbrev-mode
8323: Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
8324: Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
8325: but they do not expand until Abbrev mode is enabled again. The command
8326: @kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
8327: turns Abbrev mode on if the argument is positive, off otherwise.
8328: @xref{Minor Modes}. @code{abbrev-mode} is also a variable, local to each
8329: buffer; Abbrev mode is on when the variable is non-@code{nil}.
8330:
8331: Abbrev definitions can be @dfn{mode-specific}---active only in one major
8332: mode. Abbrevs can also have @dfn{global} definitions that are active in
8333: all major modes. The same abbrev can have a global definition and various
8334: mode-specific definitions for different major modes. A mode specific
8335: definition for the current major mode overrides a global definition.
8336:
8337: Abbrevs can be defined interactively during the editing session. Lists
8338: of abbrev definitions can also be saved in files and reloaded in later
8339: sessions. Some users keep extensive lists of abbrevs that they load in
8340: every session.
8341:
8342: @menu
8343: * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
8344: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
8345: * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
8346: * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
8347: @end menu
8348:
8349: @node Defining Abbrevs, Expanding Abbrevs, Abbrevs, Abbrevs
8350: @section Defining Abbrevs
8351:
8352: @table @kbd
8353: @item C-x +
8354: Define an abbrev to expand into some text before point
8355: (@code{add-global-abbrev}).
8356: @item C-x C-a
8357: Similar, but define an abbrev available only in the current major mode
8358: (@code{add-mode-abbrev}).
8359: @item C-x -
8360: Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
8361: @item C-x C-h
8362: Define a word in the buffer as a mode-specific abbrev
8363: (@code{inverse-add-mode-abbrev}).
8364: @item M-x kill-all-abbrevs
8365: After this command, there are no abbrev definitions in effect.
8366: @end table
8367:
8368: @kindex C-x +
8369: @findex add-global-abbrev
8370: The usual way to define an abbrev is to enter the text you want the
8371: abbrev to expand to, position point after it, and type @kbd{C-x +}
8372: (@code{add-global-abbrev}). This reads the abbrev itself using the
8373: minibuffer, and then defines it as an abbrev for one or more words before
8374: point. Use a numeric argument to say how many words before point should be
8375: taken as the expansion. For example, to define the abbrev @samp{foo} as
8376: mentioned above, insert the text @samp{find outer otter} and then type
8377: @kbd{C-u 3 C-x + f o o @key{RET}}.
8378:
8379: An argument of zero to @kbd{C-x +} means to use the contents of the
8380: region as the expansion of the abbrev being defined.
8381:
8382: @kindex C-x C-a
8383: @findex add-mode-abbrev
8384: The command @kbd{C-x C-a} (@code{add-mode-abbrev}) is similar, but
8385: defines a mode-specific abbrev. Mode specific abbrevs are active only in a
8386: particular major mode. @kbd{C-x C-a} defines an abbrev for the major mode
8387: in effect at the time @kbd{C-x C-a} is typed. The arguments work the same
8388: as for @kbd{C-x +}.
8389:
8390: @kindex C-x -
8391: @findex inverse-add-global-abbrev
8392: @kindex C-x C-h
8393: @findex inverse-add-mode-abbrev
8394: If the text of the abbrev you want is already in the buffer instead of
8395: the expansion, use command @kbd{C-x -} (@code{inverse-add-global-abbrev})
8396: instead of @kbd{C-x +}, or use @kbd{C-x C-h}
8397: (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x C-a}. These commands
8398: are called ``inverse'' because they invert the meaning of the argument
8399: found in the buffer and the argument read using the minibuffer.@refill
8400:
8401: To change the definition of an abbrev, just add the new definition. You
8402: will be asked to confirm if the abbrev has a prior definition. To remove
8403: an abbrev definition, give a negative argument to @kbd{C-x +} or @kbd{C-x
8404: C-a}. You must choose the command to specify whether to kill a global
8405: definition or a mode-specific definition for the current mode, since those
8406: two definitions are independent for one abbrev.
8407:
8408: @findex kill-all-abbrevs
8409: @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there are.
8410:
8411: @node Expanding Abbrevs, Editing Abbrevs, Defining Abbrevs, Abbrevs
8412: @section Controlling Abbrev Expansion
8413:
8414: An abbrev expands whenever it is present in the buffer just before point
8415: and a self-inserting punctuation character (@key{SPC}, comma, etc.@:) is
8416: typed. Most often the way an abbrev is used is to insert the abbrev
8417: followed by punctuation.
8418:
8419: @vindex abbrev-all-caps
8420: Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
8421: outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
8422: @samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
8423: variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first
8424: of the two expansions).@refill
8425:
8426: These two commands are used to control abbrev expansion:
8427:
8428: @table @kbd
8429: @item M-'
8430: Separate a prefix from a following abbrev to be expanded
8431: (@code{abbrev-prefix-mark}).
8432: @item M-x unexpand-abbrev
8433: Undo last abbrev expansion.
8434: @item M-x expand-region-abbrevs
8435: Expand some or all abbrevs found in the region.
8436: @end table
8437:
8438: @kindex M-'
8439: @findex abbrev-prefix-mark
8440: You may wish to expand an abbrev with a prefix attached; for example, if
8441: @samp{cnst} expands into @samp{construction}, you might want to use it to
8442: enter @samp{reconstruction}. It does not work to type @kbd{recnst},
8443: because that is not necessarily a defined abbrev. What does work is to use
8444: the command @kbd{M-'} (@code{abbrev-prefix-mark}) in between the prefix
8445: @samp{re} and the abbrev @samp{cnst}. First, insert @samp{re}. Then type
8446: @kbd{M-'}; this inserts a minus sign in the buffer to indicate that it has
8447: done its work. Then insert the abbrev @samp{cnst}; the buffer now contains
8448: @samp{re-cnst}. Now insert a punctuation character to expand the abbrev
8449: @samp{cnst} into @samp{construction}. The minus sign is deleted at this
8450: point, because @kbd{M-'} left word for this to be done. The resulting text
8451: is the desired @samp{reconstruction}.@refill
8452:
8453: If you actually want the text of the abbrev in the buffer, rather than
8454: its expansion, you can accomplish this by inserting the following
8455: punctuation with @kbd{C-q}. Thus, @kbd{foo C-q -} leaves @samp{foo-} in the
8456: buffer.
8457:
8458: @findex unexpand-abbrev
8459: If you expand an abbrev by mistake, you can undo the expansion (replace
8460: the expansion by the original abbrev text) with @kbd{M-x unexpand-abbrev}.
8461: @kbd{C-_} (@code{undo}) can also be used to undo the expansion; but first
8462: it will undo the insertion of the following punctuation character!
8463:
8464: @findex expand-region-abbrevs
8465: @kbd{M-x expand-region-abbrevs} searches through the region for defined
8466: abbrevs, and for each one found offers to replace it with its expansion.
8467: This command is useful if you have typed in text using abbrevs but forgot
8468: to turn on Abbrev mode first. It may also be useful together with a
8469: special set of abbrev definitions for making several global replacements at
8470: once.
8471:
8472: @node Editing Abbrevs, Saving Abbrevs, Expanding Abbrevs, Abbrevs
8473: @section Examining and Editing Abbrevs
8474:
8475: @table @kbd
8476: @item M-x list-abbrevs
8477: Print a list of all abbrev definitions.
8478: @item M-x edit-abbrevs
8479: Edit a list of abbrevs; you can add, alter or remove definitions.
8480: @end table
8481:
8482: @findex list-abbrevs
8483: The output from @kbd{M-x list-abbrevs} looks like this:
8484:
8485: @example
8486: (lisp-mode-abbrev-table)
8487: "dk" 0 "define-key"
8488: (global-abbrev-table)
8489: "dfn" 0 "definition"
8490: @end example
8491:
8492: @noindent
8493: (Some blank lines of no semantic significance, and some other abbrev
8494: tables, have been omitted.)
8495:
8496: A line containing a name in parentheses is the header for abbrevs in a
8497: particular abbrev table; @code{global-abbrev-table} contains all the global
8498: abbrevs, and the other abbrev tables that are named after major modes
8499: contain the mode-specific abbrevs.
8500:
8501: Within each abbrev table, each nonblank line defines one abbrev. The
8502: word at the beginning is the abbrev. The number that appears is the number
8503: of times the abbrev has been expanded. Emacs keeps track of this to help
8504: you see which abbrevs you actually use, in case you decide to eliminate
8505: those that you don't use often. The string at the end of the line is the
8506: expansion.
8507:
8508: @findex edit-abbrevs
8509: @kindex C-x C-s
8510: @findex edit-abbrevs-redefine
8511: @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
8512: definitions by editing a list of them in an Emacs buffer. The list has the
8513: same format described above. The buffer of abbrevs is called @samp{*Abbrevs*},
8514: and is in Edit-Abbrevs mode. This mode redefines the key @kbd{C-x C-s} to
8515: install the abbrev definitions as specified in the buffer. The command
8516: that does this is @code{edit-abbrevs-redefine}. Any abbrevs not described
8517: in the buffer are eliminated when this is done.
8518:
8519: @code{edit-abbrevs} is actually the same as @code{list-abbrevs} except
8520: that it selects the buffer @samp{*Abbrevs*} whereas @code{list-abbrevs}
8521: merely displays it in another window.
8522:
8523: @node Saving Abbrevs,, Editing Abbrevs, Abbrevs
8524: @section Saving Abbrevs
8525:
8526: These commands allow you to keep abbrev definitions between editing
8527: sessions.
8528:
8529: @table @kbd
8530: @item M-x write-abbrev-file
8531: Write a file describing all defined abbrevs.
8532: @item M-x read-abbrev-file
8533: Read such a file and define abbrevs as specified there.
8534: @item M-x quietly-read-abbrev-file
8535: Similar but do not display a message about what is going on.
8536: @item M-x define-abbrevs
8537: Define abbrevs from buffer.
8538: @item M-x insert-abbrevs
8539: Insert all abbrevs and their expansions into the buffer.
8540: @end table
8541:
8542: @findex write-abbrev-file
8543: @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and
8544: writes a description of all current abbrev definitions into that file. The
8545: text stored in the file looks like the output of @kbd{M-x list-abbrevs}.
8546: This is used to save abbrev definitions for use in a later session.
8547:
8548: @findex read-abbrev-file
8549: @findex quietly-read-abbrev-file
8550: @vindex abbrev-file-name
8551: @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and
8552: reads the file, defining abbrevs according to the contents of the file.
8553: @kbd{M-x quietly-read-abbrev-file} is the same except that it does not
8554: display a message in the echo area saying that it is doing its work; it
8555: is actually useful primarily in the @file{.emacs} file. If an empty
8556: argument is given to either of these functions, the file name used is the
8557: value of the variable @code{abbrev-file-name}, which is by default
8558: @code{"~/.abbrev_defs"}.
8559:
8560: @vindex save-abbrevs
8561: Emacs will offer to save abbrevs automatically if you have changed any of
8562: them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
8563: C-c}). This feature can be inhibited by setting the variable
8564: @code{save-abbrevs} to @code{nil}.
8565:
8566: @findex insert-abbrevs
8567: @findex define-abbrevs
8568: The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
8569: similar to the previous commands but work on text in an Emacs buffer.
8570: @kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
8571: describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
8572: the entire current buffer and defines abbrevs accordingly.@refill
8573:
8574: @node Picture, Sending Mail, Abbrevs, Top
8575: @chapter Editing Pictures
8576: @cindex pictures
8577: @findex edit-picture
8578:
8579: If you want to create a picture made out of text characters (for example,
8580: a picture of the division of a register into fields, as a comment in a
8581: program), use the command @code{edit-picture} to enter Picture mode.
8582:
8583: In Picture mode, editing is based on the @dfn{quarter-plane} model of
8584: text, according to which the text characters lie studded on an area that
8585: stretches infinitely far to the left and downward. The concept of the end
8586: of a line does not exist in this model; the most you can say is where the
8587: last nonblank character on the line is found.
8588:
8589: Of course, Emacs really always considers text as a sequence of
8590: characters, and lines really do have ends. But in Picture mode most
8591: frequently-used keys are rebound to commands that simulate the
8592: quarter-plane model of text. They do this by inserting spaces or by
8593: converting tabs to spaces.
8594:
8595: Most of the basic editing commands of Emacs are redefined by Picture mode
8596: to do essentially the same thing but in a quarter-plane way. In addition,
8597: Picture mode defines various keys starting with the @kbd{C-c} prefix to
8598: run special picture editing commands.
8599:
8600: One of these keys, @kbd{C-c C-c}, is pretty important. Often a picture
8601: is part of a larger file that is usually edited in some other major mode.
8602: @kbd{M-x edit-picture} records the name of the previous major mode, and
8603: then you can use the @kbd{C-c C-c} command (@code{Picture-mode-exit}) to
8604: restore that mode. @kbd{C-c C-c} also deletes spaces from the ends of
8605: lines, unless given a numeric argument.
8606:
8607: The commands used in Picture mode all work in other modes (provided the
8608: @file{picture} library is loaded), but are not bound to keys except in
8609: Picture mode. Note that the descriptions below talk of moving ``one
8610: column'' and so on, but all the picture mode commands handle numeric
8611: arguments as their normal equivalents do.
8612:
8613: @vindex picture-mode-hook
8614: Turning on Picture mode calls the value of the variable @code{picture-mode-hook}
8615: as a function, with no arguments, if that value exists and is non-@code{nil}.
8616:
8617: @menu
8618: * Basic Picture:: Basic concepts and simple commands of Picture Mode.
8619: * Insert in Picture:: Controlling direction of cursor motion
8620: after "self-inserting" characters.
8621: * Tabs in Picture:: Various features for tab stops and indentation.
8622: * Rectangles in Picture:: Clearing and superimposing rectangles.
8623: @end menu
8624:
8625: @node Basic Picture, Insert in Picture, Picture Mode, Picture
8626: @section Basic Editing in Picture Mode
8627:
8628: @findex Picture-forward-column
8629: @findex Picture-backward-column
8630: @findex Picture-move-down
8631: @findex Picture-move-up
8632: Most keys do the same thing in Picture mode that they usually do, but do
8633: it in a quarter-plane style. For example, @kbd{C-f} is rebound to run
8634: @code{Picture-forward-column}, which is defined to move point one column to
8635: the right, by inserting a space if necessary, so that the actual end of the
8636: line makes no difference. @kbd{C-b} is rebound to run
8637: @code{Picture-backward-column}, which always moves point left one column,
8638: converting a tab to multiple spaces if necessary. @kbd{C-n} and @kbd{C-p}
8639: are rebound to run @code{Picture-move-down} and @code{Picture-move-up},
8640: which can either insert spaces or convert tabs as necessary to make sure
8641: that point stays in exactly the same column. @kbd{C-e} runs
8642: @code{Picture-end-of-line}, which moves to after the last nonblank
8643: character on the line. There is no need to change @kbd{C-a}, as the choice
8644: of screen model does not affect beginnings of lines.@refill
8645:
8646: @findex Picture-newline
8647: Insertion of text is adapted to the quarter-plane screen model through
8648: the use of Overwrite mode (@pxref{Minor Modes}). Self-inserting characters
8649: replace existing text, column by column, rather than pushing existing text
8650: to the right. @key{RET} runs @code{Picture-newline}, which just moves to
8651: the beginning of the following line so that new text will replace that
8652: line.
8653:
8654: @findex Picture-backward-clear-column
8655: @findex Picture-clear-column
8656: @findex Picture-clear-line
8657: Deletion and killing of text are replaced with erasure. @key{DEL}
8658: (@code{Picture-backward-clear-column}) replaces the preceding character
8659: with a space rather than removing it. @kbd{C-d}
8660: (@code{Picture-clear-column}) does the same thing in a forward direction.
8661: @kbd{C-k} (@code{Picture-clear-line}) really kills the contents of lines,
8662: but does not ever remove the newlines from the buffer.@refill
8663:
8664: @findex Picture-open-line
8665: To do actual insertion, you must use special commands. @kbd{C-o}
8666: (@code{Picture-open-line}) still creates a blank line, but does so after
8667: the current line; it never splits a line. @kbd{C-M-o}, @code{split-line},
8668: makes sense in Picture mode, so it is not changed. @key{LFD}
8669: (@code{Picture-duplicate-line}) inserts below the current line another line
8670: with the same contents.@refill
8671:
8672: @kindex C-c C-d
8673: @findex delete-char
8674: Real deletion can be done with @kbd{C-w}, or with @kbd{C-c C-d} (which is
8675: defined as @code{delete-char}, as @kbd{C-d} is in other modes), or with one
8676: of the picture rectangle commands (@pxref{Rectangles in Picture}).
8677:
8678: @node Insert in Picture, Tabs in Picture, Basic Picture, Picture
8679: @section Controlling Motion after Insert
8680:
8681: @findex Picture-movement-up
8682: @findex Picture-movement-down
8683: @findex Picture-movement-left
8684: @findex Picture-movement-right
8685: @findex Picture-movement-nw
8686: @findex Picture-movement-ne
8687: @findex Picture-movement-sw
8688: @findex Picture-movement-se
8689: @kindex M-`
8690: @kindex M-'
8691: @kindex M--
8692: @kindex M-=
8693: @kindex C-c `
8694: @kindex C-c '
8695: @kindex C-c /
8696: @kindex C-c \
8697: Since ``self-inserting'' characters in Picture mode just overwrite and
8698: move point, there is no essential restriction on how point should be moved.
8699: Normally point moves right, but you can specify any of the eight orthogonal
8700: or diagonal directions for motion after a ``self-inserting'' character.
8701: This is useful for drawing lines in the buffer.
8702:
8703: @table @kbd
8704: @item M-`
8705: Move left after insertion (@code{Picture-movement-left}).
8706: @item M-'
8707: Move right after insertion (@code{Picture-movement-right}).
8708: @item M--
8709: Move up after insertion (@code{Picture-movement-up}).
8710: @item M-=
8711: Move down after insertion (@code{Picture-movement-down}).
8712: @item C-c `
8713: Move up and left (``northwest'') after insertion @*(@code{Picture-movement-nw}).
8714: @item C-c '
8715: Move up and right (``northeast'') after insertion @*
8716: (@code{Picture-movement-ne}).
8717: @item C-c /
8718: Move down and left (``southwest'') after insertion
8719: @*(@code{Picture-movement-sw}).
8720: @item C-c \
8721: Move down and right (``southeast'') after insertion
8722: @*(@code{Picture-movement-se}).
8723: @end table
8724:
8725: @kindex C-c C-f
8726: @kindex C-c C-b
8727: @findex Picture-motion
8728: @findex Picture-motion-reverse
8729: Two motion commands move based on the current Picture insertion
8730: direction. @kbd{C-c C-f} (@code{Picture-motion}) moves in the same
8731: direction as motion after ``insertion'' currently does, while @kbd{C-c C-b}
8732: (@code{Picture-motion-reverse}) moves in the opposite direction.
8733:
8734: @node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
8735: @section Picture Mode Tabs
8736:
8737: @kindex M-TAB
8738: @findex Picture-tab-search
8739: @vindex picture-tab-chars
8740: Two kinds of tab-like action are provided in Picture mode.
8741: Context-based tabbing is done with @kbd{M-@key{TAB}}
8742: (@code{Picture-tab-search}). With no argument, it moves to a point
8743: underneath the next ``interesting'' character that follows whitespace in
8744: the previous nonblank line. ``Next'' here means ``appearing at a
8745: horizontal position greater than the one point starts out at''. With an
8746: argument, as in @kbd{C-u M-@key{TAB}}, this command moves to the next such
8747: interesting character in the current line. @kbd{M-@key{TAB}} does not
8748: change the text; it only moves point. ``Interesting'' characters are
8749: defined by the variable @code{picture-tab-chars}, which contains a string
8750: whose characters are all considered interesting. Its default value is
8751: @code{"!-~"}.@refill
8752:
8753: @findex Picture-tab
8754: @key{TAB} itself runs @code{Picture-tab}, which operates based on the
8755: current tab stop settings; it is the Picture mode equivalent of
8756: @code{tab-to-tab-stop}. Normally it just moves point, but with a numeric
8757: argument it clears the text that it moves over.
8758:
8759: @kindex C-c TAB
8760: @findex Picture-set-tab-stops
8761: The context-based and tab-stop-based forms of tabbing are brought
8762: together by the command @kbd{C-c @key{TAB}}, @code{Picture-set-tab-stops}.
8763: This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
8764: would consider significant in the current line. The use of this command,
8765: together with @key{TAB}, can get the effect of context-based tabbing. But
8766: @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
8767:
8768: @node Rectangles in Picture,, Tabs in Picture, Picture
8769: @section Picture Mode Rectangle Commands
8770: @cindex rectangle
8771:
8772: Picture mode defines commands for working on rectangular pieces of the
8773: text in ways that fit with the quarter-plane model. The standard rectangle
8774: commands may also be useful (@pxref{Rectangles}).
8775:
8776: @table @kbd
8777: @item C-c C-k
8778: Clear out the region-rectangle (@code{Picture-clear-rectangle}). With
8779: argument, kill it.
8780: @item C-c C-w @var{r}
8781: Similar but save rectangle contents in register @var{r} first
8782: (@code{Picture-clear-rectangle-to--register}).
8783: @item C-c C-y
8784: Overwrite last killed rectangle into the buffer, with upper left corner at
8785: point (@code{Picture-yank-rectangle}). With argument, insert instead.
8786: @item C-c C-x @var{r}
8787: Similar, but take the rectangle from register @var{r}
8788: (@code{Picture-yank-rectangle-from-register}).
8789: @end table
8790:
8791: @kindex C-c C-k
8792: @kindex C-c C-w
8793: @findex Picture-clear-rectangle
8794: @findex Picture-clear-rectangle-to-register
8795: The picture rectangle commands @kbd{C-c C-k}
8796: (@code{Picture-clear-rectangle}) and @kbd{C-c C-w}
8797: (@code{Picture-clear-rectangle-to-register}) differ from the standard
8798: rectangle commands in that they normally clear the rectangle instead of
8799: deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
8800: mode.@refill
8801:
8802: However, deletion of rectangles can be useful in Picture mode, so these
8803: commands delete the rectangle if given a numeric argument.
8804:
8805: @kindex C-c C-y
8806: @kindex C-c C-x
8807: @findex Picture-yank-rectangle
8808: @findex Picture-yank-rectangle-from-register
8809: The Picture mode commands for yanking rectangles differ from the standard
8810: ones in overwriting instead of inserting. This is the same way that
8811: Picture mode insertion of other text is different from other modes.
8812: @kbd{C-c C-y} (@code{Picture-yank-rectangle}) inserts (by overwriting) the
8813: rectangle that was most recently killed, while @kbd{C-c C-x}
8814: (@code{Picture-yank-rectangle-from-register}) does likewise for the
8815: rectangle found in a specified register.
8816:
8817: @node Sending Mail, Rmail, Picture, Top
8818: @chapter Sending Mail
8819: @cindex mail
8820: @cindex message
8821:
8822: To send a message in Emacs, you start by typing a command (@kbd{C-x m})
8823: to select and initialize the @samp{*mail*} buffer. Then you edit the text
8824: and headers of the message in this buffer, and type another command
8825: (@kbd{C-c C-c}) to send the message.
8826:
8827: @table @kbd
8828: @item C-x m
8829: Begin composing a message to send (@code{mail}).
8830: @item C-x 4 m
8831: Likewise, but display the message in another window
8832: (@code{mail-other-window}).
8833: @end table
8834:
8835: @kindex C-x m
8836: @findex mail
8837: @kindex C-x 4 m
8838: @findex mail-other-window
8839: The command @kbd{C-x m} (@code{mail}) selects a buffer named
8840: @samp{*mail*} and initializes it with the skeleton of an outgoing message.
8841: @kbd{C-x 4 m} (@code{mail-other-window}) selects the @samp{*mail*} buffer
8842: in a different window, leaving the previous current buffer visible.@refill
8843:
8844: @cindex headers (of message)
8845: In addition to the @dfn{text} or contents, a message has @dfn{header
8846: fields} which say who sent it, when, to whom, why, and so on. Some header
8847: fields such as the date and sender are created automatically after the
8848: message is sent. Others, such as the recipient names, must be specified by
8849: you in order to send the message properly.
8850:
8851: The line in the buffer that says
8852:
8853: @example
8854: --text follows this line--
8855: @end example
8856:
8857: @vindex mail-header-separator
8858: @noindent
8859: is a special delimiter that separates the headers you have specified from
8860: the text. Whatever follows this line is the text of the message; the
8861: headers precede it. The delimiter line itself does not appear in the
8862: message actually sent. The text used for the delimiter line is controlled
8863: by the variable @code{mail-header-separator}.
8864:
8865: Here is an example of what the headers and text in the @samp{*mail*} buffer
8866: might look like.
8867:
8868: @example
8869: To: rms@@mc
8870: CC: mly@@mc, rg@@oz
8871: Subject: The Emacs Manual
8872: --Text follows this line--
8873: Please ignore this message.
8874: @end example
8875:
8876: Because the mail composition buffer is an ordinary Emacs buffer, you can
8877: switch to other buffers while in the middle of composing mail, and switch
8878: back later (or never). If you use the @kbd{C-x m} command again when you
8879: have been composing another message but have not sent it, you are asked to
8880: confirm before the old message is erased. If you answer @kbd{n}, the
8881: @samp{*mail*} buffer is left selected with its old contents, so you can
8882: finish the old message and send it. @kbd{C-u C-x m} is another way to do
8883: this. Sending the message marks the @samp{*mail*} buffer ``unmodified'',
8884: which avoids the need for confirmation when @kbd{C-x m} is next used.
8885:
8886: @section Mail Header Fields
8887:
8888: There are several header fields you can use in the @samp{*mail*} buffer.
8889: Each header field starts with a field name at the beginning of a line,
8890: terminated by a colon. It does not matter whether you use upper or lower
8891: case in the field name. After the colon and optional whitespace comes the
8892: contents of the field.
8893:
8894: @table @samp
8895: @item To
8896: This field contains the mailing addresses to which the message is
8897: addressed.
8898:
8899: @item Subject
8900: The contents of the @samp{Subject} field should be a piece of text
8901: that says what the message is about. The reason @samp{Subject} fields
8902: are useful is that most mail-reading programs can provide a summary of
8903: messages, listing the subject of each message but not its text.
8904:
8905: @item CC
8906: This field contains additional mailing addresses to send the message
8907: to, but whose readers should not regard the message as addressed to
8908: them.
8909:
8910: @item BCC
8911: This field contains additional mailing addresses to send the message
8912: to, but which should not appear in the header of the message actually
8913: sent.
8914:
8915: @item FCC
8916: This field contains the name of one file (in Unix mail file format) to
8917: which a copy of the message should be appended when the message is
8918: sent.
8919:
8920: @item From
8921: Use the @samp{From} field to say who you are, when the account you are
8922: using to send the mail is not your own. The contents of the
8923: @samp{From} field should be a valid mailing address, since replies
8924: will normally go there.
8925:
8926: @item Reply-To
8927: Use the @samp{Reply-to} field to direct replies to a different
8928: address, not your own. There is no difference between @samp{From} and
8929: @samp{Reply-to} in their effect on where replies go, but they convey a
8930: different meaning to the human who reads the message.
8931:
8932: @item In-Reply-To
8933: This field contains a piece of text describing a message you are
8934: replying to. Some mail systems can use this information to correlate
8935: related pieces of mail. Normally this field is filled in by Rmail
8936: when you are replying to a message in Rmail, and you never need to
8937: think about it.
8938: @end table
8939:
8940: @noindent
8941: The @samp{To}, @samp{CC}, @samp{BCC} and @samp{FCC} fields can appear
8942: any number of times, to specify many places to send the message.
8943:
8944: @noindent
8945: The @samp{To}, @samp{CC}, and @samp{BCC} fields can have continuation
8946: lines. All the lines starting with whitespace, following the line on
8947: which the field starts, are considered part of the field. For
8948: example,@refill
8949:
8950: @group
8951: @example
8952: To: foo@@bar, this@@that,
8953: me@@here
8954: @end example
8955: @end group
8956:
8957: @noindent
8958: If you have a @file{~/.mailrc} file, Rmail will scan it for mail aliases
8959: the first time you try to send mail in an Rmail session. Aliases found
8960: in the @samp{To}, @samp{CC}, and @samp{BCC} fields will be expanded where
8961: appropriate.
8962:
8963: @vindex mail-archive-file-name
8964: If the variable @code{mail-archive-file-name} is non-@code{nil}, it should be a
8965: string, naming a file; every time you start to edit a message to sent,
8966: an @samp{FCC} field will be put in for that file. Unless you remove the
8967: @samp{FCC} field, every message will be written into that file when it is
8968: sent.
8969:
8970: @section Mail Mode
8971:
8972: The major mode used in the @samp{*mail*} buffer is Mail mode, which is
8973: much like Text mode except that various special commands are provided on
8974: the @kbd{C-c} prefix. These commands all have to do specifically with
8975: editing or sending the message.
8976:
8977: @table @kbd
8978: @item C-c C-s
8979: Send the message, and leave the @samp{*mail*} buffer selected
8980: (@code{mail-send}).
8981: @item C-c C-c
8982: Send the message, and select some other buffer (@code{mail-send-and-exit}).
8983: @item C-c t
8984: Move to the @samp{To} header field, creating one if there is none
8985: (@code{mail-to}).
8986: @item C-c s
8987: Move to the @samp{Subject} header field, creating one if there is
8988: none (@code{mail-subject}).
8989: @item C-c c
8990: Move to the @samp{CC} header field, creating one if there is none
8991: (@code{mail-cc}).
8992: @item C-c w
8993: Insert the file @file{~/.signature} at the end of the message text
8994: (@code{mail-signature}).
8995: @item C-c y
8996: Yank the selected message from Rmail (@code{mail-yank-original}).
8997: This command does nothing unless your command to start sending a
8998: message was issued with Rmail.
8999: @item C-c q
9000: Fill all paragraphs of yanked old messages, each individually
9001: (@code{mail-fill-yanked-message}).
9002: @end table
9003:
9004: @kindex C-c C-s
9005: @kindex C-c C-c
9006: @findex mail-send
9007: @findex mail-send-and-exit
9008: There are two ways to send the message. @kbd{C-c C-s} (@code{mail-send})
9009: sends the message and marks the @samp{*mail*} buffer unmodified, but leaves
9010: that buffer selected so that you can modify the message (perhaps with new
9011: recipients) and send it again. @kbd{C-c C-c} (@code{mail-send-and-exit})
9012: sends and then deletes the window (if there is another window) or switches
9013: to another buffer. It puts the @samp{*mail*} buffer at the lowest priority
9014: for automatic reselection, since you are finished with using it. This is
9015: the usual way to send the message.
9016:
9017: @kindex C-c t
9018: @findex mail-to
9019: @kindex C-c s
9020: @findex mail-subject
9021: @kindex C-c c
9022: @findex mail-cc
9023: Mail mode provides some other special commands that are useful for
9024: editing the headers and text of the message before you send it. There are
9025: four commands defined to move point to particular header fields: @kbd{C-c
9026: t} (@code{mail-to}) to move to the @samp{To} field, @kbd{C-c s}
9027: (@code{mail-subject}) for the @samp{Subject} field, and @kbd{C-c c}
9028: (@code{mail-cc}) for the @samp{CC} field.@refill
9029:
9030: @kindex C-c w
9031: @findex mail-signature
9032: @kbd{C-c w} (@code{mail-signature}) adds a standard piece text at the end of the
9033: message to say more about who you are. The text comes from the file
9034: @file{.signature} in your home directory.
9035:
9036: @kindex C-c y
9037: @findex mail-yank-original
9038: When mail sending is invoked from the Rmail mail reader using an Rmail
9039: command, @kbd{C-c y} can be used inside the @samp{*mail*} buffer to insert
9040: the text of the message you are replying to. Normally it indents each line
9041: of that message four spaces and eliminates most header fields. A numeric
9042: argument specifies the number of spaces to indent. An argument of just
9043: @kbd{C-u} says not to indent at all and not to eliminate anything.
9044: @kbd{C-c y} always uses the current message from the @samp{rmail} buffer,
9045: so you can insert several old messages by selecting one in @samp{rmail},
9046: switching to @samp{*mail*} and yanking it, then switching back to
9047: @samp{rmail} to select another.@refill
9048:
9049: @kindex C-c q
9050: @findex mail-fill-yanked-message
9051: After using @kbd{C-c y}, the command @kbd{C-c q} (@code{mail-fill-yanked-message}) can
9052: be used to fill the paragraphs of the yanked old message or messages. One
9053: use of @kbd{C-c q} fills all such paragraphs, each one separately.
9054:
9055: @vindex mail-mode-hook
9056: Turning on Mail mode (which @kbd{C-x m} does automatically) calls the
9057: value of @code{text-mode-hook}, if it is not void or @code{nil}, and then calls
9058: the value of @code{mail-mode-hook} if that is not void or @code{nil}.
9059:
9060: @node Rmail, Recursive Edit, Sending Mail, Top
9061: @chapter Reading Mail with Rmail
9062: @cindex Rmail
9063: @cindex message
9064:
9065: Rmail is an Emacs subsystem for reading and disposing of mail that you
9066: receive. Rmail stores mail messages in files called Rmail files. Reading
9067: the message in an Rmail file is done in a special major mode, Rmail mode,
9068: which redefines most letters to run commands for managing mail.
9069:
9070: @cindex primary mail file
9071: Using Rmail in the simplest fashion, you have one Rmail file @file{~/RMAIL}
9072: in which all of your mail is saved. It is called your @dfn{primary mail
9073: file}. In more sophisticated usage, you can copy messages into other Rmail
9074: files and then edit those files with Rmail.
9075:
9076: Rmail displays only one message at a time. It is called the @dfn{current
9077: message}. Rmail mode's special commands can do such things as move to
9078: another message, delete the message, copy the message into another file, or
9079: send a reply.
9080:
9081: @cindex message number
9082: Within the Rmail file, messages are arranged sequentially in order
9083: of receipt. They are also assigned consecutive integers as their
9084: @dfn{message numbers}. The number of the current message is displayed
9085: in Rmail's mode line, followed by the total number of messages in the
9086: file. You can move to a message by specifying its message number
9087: using the @kbd{j} key (@pxref{Rmail Motion}).
9088:
9089: @kindex s (Rmail)
9090: @findex rmail-save
9091: Following the usual conventions of Emacs, changes in an Rmail file become
9092: permanent only when the file is saved. You can do this with @kbd{s}
9093: (@code{rmail-save}), which also expunges deleted messages from the file
9094: first (@pxref{Rmail Deletion}). To save the file without expunging, use
9095: @kbd{C-x C-s}. Rmail saves the Rmail file spontaneously when moving new
9096: mail from an inbox file (@pxref{Rmail Inbox}).
9097:
9098: @kindex q (Rmail)
9099: @findex rmail-quit
9100: You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and saves the
9101: Rmail file and then switches to another buffer. But there is no need to
9102: `exit' formally. If you switch from Rmail to editing in other buffers, and
9103: never happen to switch back, you have exited. Just make sure to save the
9104: Rmail file eventually (like any other file you have changed). @kbd{C-x s}
9105: is a good enough way to do this (@pxref{Saving}).
9106:
9107: @menu
9108: * Scroll: Rmail Scrolling. Scrolling through a message.
9109: * Motion: Rmail Motion. Moving to another message.
9110: * Deletion: Rmail Deletion. Deleting and expunging messages.
9111: * Inbox: Rmail Inbox. How mail gets into the Rmail file.
9112: * Files: Rmail Files. Using multiple Rmail files.
9113: * Labels: Rmail Labels. Classifying messages by labeling them.
9114: * Summary: Rmail Summary. Summaries show brief info on many messages.
9115: * Reply: Rmail Reply. Sending replies to messages you are viewing.
9116: * Editing: Rmail Editing. Editing message text and headers in Rmail.
9117: * Digest: Rmail Digest. Extracting the messages from a digest message.
9118: @end menu
9119:
9120: @node Rmail Scrolling, Rmail Motion, Rmail, Rmail
9121: @section Scrolling Within a Message
9122:
9123: When Rmail displays a message that does not fit on the screen, it is
9124: necessary to scroll through it. This could be done with @kbd{C-v}, @kbd{M-v}
9125: and @kbd{M-<}, but in Rmail scrolling is so frequent that it deserves to be
9126: easier to type.
9127:
9128: @table @kbd
9129: @item @key{SPC}
9130: Scroll forward (@code{scroll-up}).
9131: @item @key{DEL}
9132: Scroll backward (@code{scroll-down}).
9133: @item .
9134: Scroll to start of message (@code{rmail-beginning-of-message}).
9135: @end table
9136:
9137: @kindex SPC (Rmail)
9138: @kindex DEL (Rmail)
9139: Since the most common thing to do while reading a message is to scroll
9140: through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
9141: @kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down})
9142:
9143: @kindex . (Rmail)
9144: @findex rmail-beginning-of-message
9145: The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
9146: beginning of the selected message. This is not quite the same as @kbd{M-<}:
9147: for one thing, it does not set the mark; for another, it resets the buffer
9148: boundaries to the current message if you have changed them.
9149:
9150: @node Rmail Motion, Rmail Deletion, Rmail Scrolling, Rmail
9151: @section Moving Among Messages
9152:
9153: The most basic thing to do with a message is to read it. The way to do
9154: this in Rmail is to make the message current. You can make any message
9155: current given its message number using the @kbd{j} command, but the usual
9156: thing to do is to move sequentially through the file, since this is the
9157: order of receipt of messages. When you enter Rmail, you are positioned at
9158: the first new message (new messages are those received since the previous
9159: use of Rmail), or at the last message if there are no new messages this
9160: time. Move forward to see the other new messages; move backward to
9161: reexamine old messages.
9162:
9163: @table @kbd
9164: @item n
9165: Move to the next nondeleted message, skipping any intervening
9166: deleted messages (@code{rmail-next-undeleted-message}).
9167: @item p
9168: Move to the previous nondeleted message @*
9169: (@code{rmail-previous-undeleted-message}).
9170: @item M-n
9171: Move to the next message, including deleted messages
9172: (@code{rmail-next-message}).
9173: @item M-p
9174: Move to the previous message, including deleted messages
9175: (@code{rmail-previous-message}).
9176: @item j
9177: Move to the first message. With argument @var{n}, move to
9178: message number @var{n} (@code{rmail-show-message}).
9179: @item >
9180: Move to the last message (@code{rmail-last-message}).
9181:
9182: @item M-s @var{regexp} @key{RET}
9183: Move to the next message containing a match for @var{regexp}
9184: (@code{rmail-search}). If @var{regexp} is empty, the last regexp used is
9185: used again.
9186:
9187: @item - M-s @var{regexp} @key{RET}
9188: Move to the previous message containing a match for @var{regexp}.
9189: If @var{regexp} is empty, the last regexp used is used again.
9190: @end table
9191:
9192: @kindex n (Rmail)
9193: @kindex p (Rmail)
9194: @kindex M-n (Rmail)
9195: @kindex M-p (Rmail)
9196: @findex rmail-next-undeleted-message
9197: @findex rmail-previous-undeleted-message
9198: @findex rmail-next-message
9199: @findex rmail-previous-message
9200: @kbd{n} and @kbd{p} are the usual way of moving among messages in Rmail. They
9201: move through the messages sequentially, but skipping over deleted messages,
9202: which is usually what you want to do. Their command definitions are named
9203: @code{rmail-next-undeleted-message} and @code{rmail-previous-undeleted-message}. If
9204: you do not want to skip deleted messages---for example, if you want to move
9205: to a message to undelete it---use the variants @kbd{M-n} and @kbd{M-p}
9206: (@code{rmail-next-message} and @code{rmail-previous-message}). A numeric
9207: argument to any of these commands serves as a repeat count.@refill
9208:
9209: @kindex M-s (Rmail)
9210: @findex rmail-search
9211: The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of search. The
9212: usual incremental search command @kbd{C-s} works in Rmail, but it searches
9213: only within the current message. The purpose of @kbd{M-s} is to search for
9214: another message. It reads a regular expression (@pxref{Regexps})
9215: nonincrementally, then searches starting at the beginning of the following
9216: message for a match. The message containing the match is selected.
9217:
9218: To search backward in the file for another message, give @kbd{M-s} a
9219: negative argument. In Rmail this can be done with @kbd{- M-s}.
9220:
9221: @kindex j (Rmail)
9222: @kindex > (Rmail)
9223: @findex rmail-show-message
9224: @findex rmail-last-message
9225: To move to a message specified by absolute message number, use @kbd{j}
9226: (@code{rmail-show-message}) with the message number as argument. With no
9227: argument, @kbd{j} selects the first message. @kbd{>} (@code{rmail-last-message}) selects
9228: the last message.
9229:
9230: @node Rmail Deletion, Rmail Inbox, Rmail Motion, Rmail
9231: @section Deleting Messages
9232:
9233: @cindex deletion (Rmail)
9234: When you no longer need to keep a message, you can @dfn{delete} it. This
9235: flags it as ignorable, and some Rmail commands will pretend it is no longer
9236: present; but it still has its place in the Rmail file, and still has its
9237: message number.
9238:
9239: @cindex expunging (Rmail)
9240: @dfn{Expunging} the Rmail file actually removes the deleted messages.
9241: The remaining messages are renumbered consecutively. Expunging is the only
9242: action that changes the message number of any message, except for
9243: undigestifying (@pxref{Rmail Digest}).
9244:
9245: @table @kbd
9246: @item d
9247: Delete the current message, and move to the next nondeleted message
9248: (@code{rmail-delete-forward}).
9249: @item C-d
9250: Delete the current message, and move to the previous nondeleted
9251: message (@code{rmail-delete-backward}).
9252: @item u
9253: Move back to a deleted message and undelete it
9254: (@code{rmail-undelete-previous-message}).
9255: @item e
9256: Expunge the Rmail file (@code{rmail-expunge}).
9257: @end table
9258:
9259: @kindex d (Rmail)
9260: @kindex C-d (Rmail)
9261: @findex rmail-delete-forward
9262: @findex rmail-delete-backward
9263: There are two Rmail commands for deleting messages. Both delete the
9264: current message and select another message. @kbd{d} (@code{rmail-delete-forward})
9265: moves to the following message, skipping messages already deleted, while
9266: @kbd{C-d} (@code{rmail-delete-backward}) moves to the previous nondeleted message.
9267: If there is no nondeleted message to move to in the specified direction,
9268: the message that was just deleted remains current.
9269:
9270: @cindex undeletion (Rmail)
9271: @kindex e (Rmail)
9272: @findex rmail-expunge
9273: To make all the deleted messages finally vanish from the Rmail file,
9274: type @kbd{e} (@code{rmail-expunge}). Until you do this, you can still @dfn{undelete}
9275: the deleted messages.
9276:
9277: @kindex u (Rmail)
9278: @findex rmail-undelete-previous-message
9279: To undelete, type
9280: @kbd{u} (@code{rmail-undelete-previous-message}), which is designed to cancel the
9281: effect of a @kbd{d} command (usually). It undeletes the current message
9282: if the current message is deleted. Otherwise it moves backward to previous
9283: messages until a deleted message is found, and undeletes that message.
9284:
9285: You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} moves
9286: back to and undeletes the message that the @kbd{d} deleted. But this does
9287: not work when the @kbd{d} skips a few already-deleted messages that follow
9288: the message being deleted; then the @kbd{u} command will undelete the last
9289: of the messages that were skipped. There is no clean way to avoid this
9290: problem. However, by repeating the @kbd{u} command, you can eventually get
9291: back to the message that you intended to undelete.@refill
9292:
9293: A deleted message has the @samp{deleted} attribute, and as a result
9294: @samp{deleted} appears in the mode line when the current message is
9295: deleted. In fact, deleting or undeleting a message is nothing more than
9296: adding or removing this attribute. @xref{Rmail Labels}.
9297:
9298: @node Rmail Inbox, Rmail Files, Rmail Deletion, Rmail
9299: @section Rmail Files and Inboxes
9300: @cindex inbox file
9301:
9302: Unix places incoming mail for you in a file that we call your @dfn{inbox}.
9303: When you start up Rmail, it copies the new messages from your inbox into
9304: your primary mail file, an Rmail file, which also contains other messages
9305: saved from previous Rmail sessions. It is in this file that you actually
9306: read the mail with Rmail. This operation is called @dfn{getting new mail}.
9307: It can be repeated at any time using the @kbd{g} key in Rmail.
9308:
9309: There are two reason for having separate Rmail files and inboxes.
9310:
9311: @enumerate
9312: @item
9313: The format in which Unix delivers the mail in the inbox is not
9314: adequate for Rmail mail storage. It has no way to record attributes
9315: (such as @samp{deleted}) or user-specified labels; it has no way to record
9316: old headers and reformatted headers; it has no way to record cached
9317: summary line information.
9318:
9319: @item
9320: It is very cumbersome to access an inbox file without danger of losing
9321: mail, because it is necessary to interlock with mail delivery.
9322: Moreover, different Unix systems use different interlocking
9323: techniques. The strategy of moving mail out of the inbox once and for
9324: all into a separate Rmail file avoids the need for interlocking in all
9325: the rest of Rmail, since only Rmail operates on the Rmail file.
9326: @end enumerate
9327:
9328: When getting new mail, Rmail first copies the new mail from the inbox
9329: file to the Rmail file; then it saves the Rmail file; then it deletes the
9330: inbox file. This way, a system crash may cause duplication of mail between
9331: the inbox and the Rmail file, but cannot lose mail.
9332:
9333: @node Rmail Files, Rmail Labels, Rmail Inbox, Rmail
9334: @section Multiple Mail Files
9335:
9336: Rmail operates by default on your @dfn{primary mail file}, which is named
9337: @file{~/RMAIL} and receives your incoming mail from your system inbox file.
9338: But you can also have other mail files and edit them with Rmail. These
9339: files can receive mail through their own inboxes, or you can move messages
9340: into them by explicit command in Rmail.
9341:
9342: @table @kbd
9343: @item i @var{file} @key{RET}
9344: Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
9345:
9346: @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
9347: Specify inbox file names of current Rmail file.
9348:
9349: @item g
9350: Merge new mail from current Rmail file's inboxes
9351: (@code{rmail-get-new-mail}).
9352:
9353: @item C-u g @var{file}
9354: Merge new mail from inbox file @var{file}.
9355:
9356: @item o @var{file} @key{RET}
9357: Append a copy of the current message to the file @var{file},
9358: writing it in Rmail file format (@code{rmail-output-to-rmail-file}).
9359:
9360: @item C-o @var{file} @key{RET}
9361: Append a copy of the current message to the file @var{file},
9362: writing it in Unix mail file format (@code{rmail-output}).
9363: @end table
9364:
9365: @kindex i (Rmail)
9366: @findex rmail-input
9367: To run Rmail on a file other than your primary mail file, you may use the
9368: @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file, puts it in
9369: Rmail mode, and then gets new mail from the file's inboxes if any.
9370:
9371: The file you read with @kbd{i} does not have to be in Rmail file format.
9372: It could also be Unix mail format, or mmdf format; or it could be a mixture
9373: of all three, as long as each message belongs to one of the three formats.
9374: Rmail recognizes all three and converts all the messages to proper Rmail
9375: format before showing you the file.
9376:
9377: @findex set-rmail-inbox-list
9378: Each Rmail file can contain a list of inbox file names; you can specify
9379: this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
9380: @key{RET}}. The argument can contain any number of file names, separated
9381: by commas. It can also be empty, which specifies that this file should
9382: have no inboxes.@refill
9383:
9384: @kindex g (Rmail)
9385: @findex rmail-get-new-mail
9386: If an Rmail file has inboxes, new mail is merged in from the inboxes when
9387: the Rmail file is brought into Rmail, and when the @kbd{g} (@code{rmail-get-new-mail})
9388: command is used. If the Rmail file specifies no inboxes, then no new mail
9389: is merged in at these times. A special exception is made for your primary
9390: mail file, in using the standard system inbox for it if it does not specify
9391: any.
9392:
9393: Inboxes usually contain messages in Unix mail format, but they can just
9394: as well contain Rmail or mmdf format messages. Each message that is not in
9395: Rmail format is converted, just as when an Rmail file is read in.
9396:
9397: To merge mail from a file that is not the usual inbox, give the @kbd{g}
9398: key a numeric argument, as in @kbd{C-u g}. Then it reads a file name and
9399: merges mail from that file. The inbox file is not deleted or changed in
9400: any way when @kbd{g} with an argument is used. This is, therefore, a
9401: general way of merging one file of messages into another.
9402:
9403: @kindex o (Rmail)
9404: @findex rmail-output-to-rmail-file
9405: @kindex C-o (Rmail)
9406: @findex rmail-output
9407: If an Rmail file has no inboxes, how does it get anything in it? By
9408: explicit @kbd{o} or @kbd{C-o} commands in Rmail, or the like in other mail
9409: processors.
9410:
9411: The @kbd{C-o} (@code{rmail-output}) command in Rmail writes a copy of the current
9412: message into a specified file, in Unix mail file format. This is useful
9413: for moving messages into files to be read by other mail processors that do
9414: not understand Rmail format. @kbd{o} (@code{rmail-output-to-rmail-file}) is
9415: another command that writes the message into a file in Rmail format. This
9416: is the best command to use to move messages between Rmail files.
9417:
9418: If you use @kbd{C-o} to move a message into an Rmail file, nothing bad
9419: happens. It's true that the Rmail file will contain a message in Unix
9420: format, which is not strictly valid for an Rmail file; but next time Rmail
9421: reads the mail file in, it will recognize the Unix format message and
9422: convert it to Rmail format. However, using @kbd{o} preserves any labels
9423: the message has (@pxref{Rmail Labels}).
9424:
9425: Copying a message with @kbd{o} or @kbd{C-o} gives the original copy of the
9426: message the @samp{filed} attribute, so that @samp{filed} appears in the mode
9427: line when such a message is current.
9428:
9429: @node Rmail Labels, Rmail Summary, Rmail Files, Rmail
9430: @section Labels
9431: @cindex label (Rmail)
9432: @cindex attribute (Rmail)
9433:
9434: Each message can have various @dfn{labels} assigned to it as a means of
9435: classification. A label has a name; different names mean different labels.
9436: Any given label is either present or absent on a particular message. A few
9437: label names have standard meanings and are given to messages automatically
9438: by Rmail when appropriate; these special labels are called @dfn{attributes}.
9439: All other labels are assigned by the user.
9440:
9441: @table @kbd
9442: @item a @var{label} @key{RET}
9443: Assign the label @var{label} to the current message (@code{rmail-add-label}).
9444: @item k @var{label} @key{RET}
9445: Remove the label @var{label} to the current message (@code{rmail-kill-label}).
9446: @item C-M-n @var{labels} @key{RET}
9447: Move to the next message that has one of the labels @var{labels}
9448: (@code{rmail-next-labeled-message}).
9449: @item C-M-p @var{labels} @key{RET}
9450: Move to the previous message that has one of the labels @var{labels}
9451: (@code{rmail-previous-labeled-message}).
9452: @item C-M-l @var{labels} @key{RET}
9453: Make a summary of all messages containing any of the labels @var{labels}
9454: (@code{rmail-summary-by-labels}).
9455: @end table
9456:
9457: @noindent
9458: Specifying an empty string for one these commands means to use the last
9459: label specified for any of these commands.
9460:
9461: @kindex a (Rmail)
9462: @kindex k (rmail)
9463: @findex rmail-add-label
9464: @findex rmail-kill-label
9465: The @kbd{a} (@code{rmail-add-label}) and @kbd{k} (@code{rmail-kill-label}) commands allow
9466: you to assign or remove any label on the current message. If the @var{label}
9467: argument is empty, it means to assign or remove the same label most
9468: recently assigned or removed.
9469:
9470: Once you have given messages labels to classify them as you wish, there
9471: are two ways to use the labels: in moving, and in summaries.
9472:
9473: @kindex C-M-n (Rmail)
9474: @kindex C-M-p (Rmail)
9475: @findex rmail-next-labeled-message
9476: @findex rmail-previous-labeled-message
9477: The command @kbd{C-M-n @var{label} @key{RET}}
9478: (@code{rmail-next-labeled-message}) moves to the next message that has one
9479: of the labels @var{labels}. @var{labels} is one or more label names,
9480: separated by commas. @kbd{C-M-p} (@code{rmail-previous-labeled-message})
9481: is similar, but moves backwards to previous messages. A preceding numeric
9482: argument to either one serves as a repeat count.@refill
9483:
9484: @kindex C-M-l (Rmail)
9485: @findex rmail-summary-by-labels
9486: The command @kbd{C-M-l @var{labels} @key{RET}}
9487: (@code{rmail-summary-by-labels}) displays a summary containing only the
9488: messages that have at least one of a specified set of messages. The
9489: argument @var{labels} is one or more label names, separated by commas.
9490: @xref{Rmail Summary}, for information on how summaries are used.@refill
9491:
9492: If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or @kbd{C-M-l} is empty, it means
9493: to use the last set of labels specified for any of these commands.
9494:
9495: Some labels such as @samp{deleted} and @samp{filed} have built-in meanings and
9496: are assigned to or removed from messages automatically at appropriate
9497: times; these labels are called @dfn{attributes}. Here is a list of Rmail
9498: attributes:
9499:
9500: @table @samp
9501: @item unseen
9502: Means the message has never been current. Assigned to messages when
9503: they come from an inbox file, and removed when a message is made
9504: current.
9505: @item deleted
9506: Means the message is deleted. Assigned by deletion commands and
9507: removed by undeletion commands (@pxref{Rmail Deletion}).
9508: @item filed
9509: Means the message has been copied to some other file. Assigned by the
9510: file output commands (@pxref{Rmail Files}).
9511: @item answered
9512: Means you have mailed an answer to the message. Assigned by the @kbd{r}
9513: command (@code{rmail-reply}). @xref{Rmail Reply}.
9514: @item forwarded
9515: Means you have forwarded the message to other users. Assigned by the
9516: @kbd{f} command (@code{rmail-forward}). @xref{Rmail Reply}.
9517: @end table
9518:
9519: All other labels are assigned or removed only by the user, and it is up
9520: to the user to decide what they mean.
9521:
9522: @node Rmail Summary, Rmail Reply, Rmail Labels, Rmail
9523: @section Summaries
9524: @cindex summary (Rmail)
9525:
9526: A @dfn{summary} is a buffer containing one line per message that Rmail
9527: can make and display to give you an overview of the mail in an Rmail file.
9528: Each line shows the message number, the sender, the labels, and the
9529: subject. When the summary buffer is selected, various commands can be used
9530: to select messages by moving in the summary buffer, or delete or undelete
9531: messages.
9532:
9533: A summary buffer applies to a single Rmail file only; if you are
9534: editing multiple Rmail files, they have separate summary buffers. The
9535: summary buffer name is made by appending @samp{-summary} to the Rmail buffer's
9536: name. Only one summary buffer will be displayed at a time unless you make
9537: several windows and select the summary buffers by hand.
9538:
9539: @subsection Making Summaries
9540:
9541: @table @kbd
9542: @item h
9543: @itemx C-M-h
9544: Summarize all messages (@code{rmail-summary}).
9545: @item l @var{labels} @key{RET}
9546: @itemx C-M-l @var{labels} @key{RET}
9547: Summarize message that have one or more of the specified labels
9548: (@code{rmail-summary-by-labels}).
9549: @item C-M-r @var{rcpts} @key{RET}
9550: Summarize messages that have one or more of the specified recipients
9551: (@code{rmail-summary-by-recipients})
9552: @end table
9553:
9554: @kindex h
9555: @findex rmail-summary
9556: The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
9557: for the current Rmail file with a summary of all the messages in the file.
9558: It then displays and selects the summary buffer in another window.
9559:
9560: @kindex l
9561: @kindex C-M-l
9562: @findex rmail-summary-by-labels
9563: @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
9564: a partial summary mentioning only the messages that have one or more of the
9565: labels @var{labels}. @var{labels} should contain label names separated by
9566: commas.@refill
9567:
9568: @kindex C-M-r
9569: @findex rmail-summary-by-recipients
9570: @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
9571: makes a partial summary mentioning only the messages that have one or more
9572: of the recipients @var{rcpts}. @var{rcpts} should contain mailing
9573: addresses separated by commas.@refill
9574:
9575: Note that there is only one summary buffer for any Rmail file; making one
9576: kind of summary discards any previously made summary. Also, summary
9577: buffers are not updated automatically when the Rmail buffer is changed.
9578:
9579: @subsection Editing in Summaries
9580:
9581: Summary buffers are given the major mode Rmail Summary mode, which
9582: provides the following special commands:
9583:
9584: @table @kbd
9585: @item j
9586: Select the message described by the line that point is on
9587: (@code{rmail-summary-goto-msg}).
9588: @item C-n
9589: Move to next line and select its message in Rmail
9590: (@code{rmail-summary-next-all}).
9591: @item C-p
9592: Move to previous line and select its message
9593: (@code{rmail-summary-previous-all}).
9594: @item n
9595: Move to next line, skipping lines saying `deleted', and select its
9596: message (@code{rmail-summary-next-msg}).
9597: @item p
9598: Move to previous line, skipping lines saying `deleted', and select
9599: its message (@code{rmail-summary-previous-msg}).
9600: @item d
9601: Delete the current line's message, then do like @kbd{n}
9602: (@code{rmail-summary-delete-forward}).
9603: @item u
9604: Undelete and select this message or the previous deleted message in
9605: the summary (@code{rmail-summary-undelete}).
9606: @item @key{SPC}
9607: Scroll the other window (presumably Rmail) forward
9608: (@code{rmail-summary-scroll-msg-up}).
9609: @item @key{DEL}
9610: Scroll the other window backward (@code{rmail-summary-scroll-msg-down}).
9611: @item x
9612: Kill the summary window (@code{rmail-summary-exit}).
9613: @item q
9614: Exit Rmail (@code{rmail-summary-quit}).
9615: @end table
9616:
9617: @kindex C-n (Rmail summary)
9618: @kindex C-p (Rmail summary)
9619: @findex rmail-summary-next-all
9620: @findex rmail-summary-previous-all
9621: The keys @kbd{C-n} and @kbd{C-p} are modified in Rmail Summary mode so that in
9622: addition to moving point in the summary buffer they also cause the line's
9623: message to become current in the associated Rmail buffer. That buffer is
9624: also made visible in another window if it is not already so.
9625:
9626: @kindex n (Rmail summary)
9627: @kindex p (Rmail summary)
9628: @findex rmail-summary-next-msg
9629: @findex rmail-summary-previous-msg
9630: @kbd{n} and @kbd{p} are similar to @kbd{C-n} and @kbd{C-p}, but skip
9631: lines that say `message deleted'. They are like the @kbd{n} and @kbd{p}
9632: keys of Rmail itself. Note, however, that in a partial summary these
9633: commands move only among the message listed in the summary.@refill
9634:
9635: @kindex j (Rmail summary)
9636: @findex rmail-summary-goto-msg
9637: The other Emacs cursor motion commands are not changed in Rmail Summary
9638: mode, so it is easy to get the point on a line whose message is not
9639: selected in Rmail. This can also happen if you switch to the Rmail window
9640: and switch messages there. To get the Rmail buffer back in sync with the
9641: summary, use the @kbd{j} (@code{rmail-summary-goto-msg}) command, which selects
9642: in Rmail the message of the current summary line.
9643:
9644: @kindex d (Rmail summary)
9645: @kindex u (Rmail summary)
9646: @findex rmail-summary-delete-forward
9647: @findex rmail-summary-undelete
9648: Deletion and undeletion can also be done from the summary buffer. They
9649: always work based on where point is located in the summary buffer, ignoring
9650: which message is selected in Rmail. @kbd{d} (@code{rmail-summary-delete-forward})
9651: deletes the current line's message, then moves to the next line whose
9652: message is not deleted and selects that message. The inverse of this is
9653: @kbd{u} (@code{rmail-summary-undelete}), which moves back (if necessary) to a line
9654: whose message is deleted, undeletes that message, and selects it in Rmail.
9655:
9656: @kindex SPC (Rmail summary)
9657: @kindex DEL (Rmail summary)
9658: @findex rmail-summary-scroll-down
9659: @findex rmail-summary-scroll-up
9660: When moving through messages with the summary buffer, it is convenient to
9661: be able to scroll the message while remaining in the summary window.
9662: The commands @key{SPC} (@code{rmail-summary-scroll-up}) and @key{DEL}
9663: (@code{rmail-summary-scroll-down}) do this. They scroll the message just
9664: as those same keys do when the Rmail buffer is selected.@refill
9665:
9666: @kindex x (Rmail summary)
9667: @findex rmail-summary-exit
9668: When you are finished using the summary, type @kbd{x} (@code{rmail-summary-exit})
9669: to kill the summary buffer's window.
9670:
9671: @kindex q (Rmail summary)
9672: @findex rmail-summary-quit
9673: You can also exit Rmail while in the summary. @kbd{q} (@code{rmail-summary-quit})
9674: kills the summary window, then saves the Rmail file and switches to another
9675: buffer.
9676:
9677: @node Rmail Reply, Rmail Editing, Rmail Summary, Rmail
9678: @section Sending Replies
9679:
9680: Rmail has several commands that use Mail mode to send outgoing mail.
9681: @xref{Sending Mail}, for information on using Mail mode. What are
9682: documented here are the special commands of Rmail for entering Mail mode.
9683: Note that the usual keys for sending mail, @kbd{C-x m} and @kbd{C-x 4 m},
9684: are available in Rmail mode and work just as they usually do.@refill
9685:
9686: @table @kbd
9687: @item m
9688: Send a message (@code{rmail-mail}).
9689: @item c
9690: Continue editing already started outgoing message @*(@code{rmail-continue}).
9691: @item r
9692: Send a reply to the current Rmail message (@code{rmail-reply}).
9693: @item f
9694: Forward current message to other users (@code{rmail-forward}).
9695: @end table
9696:
9697: @kindex r (Rmail)
9698: @findex rmail-reply
9699: @vindex rmail-dont-reply-to
9700: @cindex reply to a message
9701: The most common reason to send a message while in Rmail is to reply to
9702: the message you are reading. To do this, type @kbd{r}
9703: (@code{rmail-reply}). This displays the @samp{*mail*} buffer in another
9704: window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject},
9705: @samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the
9706: message being replied to. The @samp{To} field is given the sender of that
9707: message, and the @samp{CC} gets all the recipients of that message (but
9708: recipients that match elements of the list @code{rmail-dont-reply-to} are
9709: omitted; by default, this list contains your own mailing address).@refill
9710:
9711: Once you have initialized the @samp{*mail*} buffer this way, sending the
9712: mail goes as usual (@pxref{Sending Mail}). You can edit the presupplied
9713: header fields if they are not right for you.
9714:
9715: @kindex C-c y
9716: @findex mail-yank-original
9717: One additional Mail mode command is available when mailing is invoked
9718: from Rmail: @kbd{C-c y} (@code{mail-yank-original}) inserts into the outgoing
9719: message a copy of the current Rmail message; normally this is the message
9720: you are replying to, but you can also switch to the Rmail buffer, select a
9721: different message, switch back, and yank new current message. Normally the
9722: yanked message is indented four spaces and has most header fields deleted
9723: from it; an argument to @kbd{C-c y} specifies the amount to indent, and
9724: @kbd{C-u C-c y} does not indent at all and does not delete any header
9725: fields.@refill
9726:
9727: @kindex f (Rmail)
9728: @findex rmail-forward
9729: @cindex forward a message
9730: Another frequent reason to send mail in Rmail is to forward the current
9731: message to other users. @kbd{f} (@code{rmail-forward}) makes this easy by
9732: preinitializing the @samp{*mail*} buffer with the current message as the
9733: text, and a subject designating a forwarded message. All you have to do is
9734: fill in the recipients and send.@refill
9735:
9736: @kindex m (Rmail)
9737: @findex rmail-mail
9738: The @kbd{m} (@code{rmail-mail}) command is used to start editing an
9739: outgoing message that is not a reply. It leaves the header fields empty.
9740: Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
9741: accessible for @kbd{C-c y}, just as @kbd{r} does. Thus, @kbd{m} can be
9742: used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
9743: can do.@refill
9744:
9745: @kindex c (Rmail)
9746: @findex rmail-continue
9747: The @kbd{c} (@code{rmail-continue}) command resumes editing the
9748: @samp{*mail*} buffer, to finish editing an outgoing message you were
9749: already composing, or to alter a message you have sent.@refill
9750:
9751: @node Rmail Editing, Rmail Digest, Rmail Reply, Rmail
9752: @section Editing Within a Message
9753:
9754: Rmail mode provides a few special commands for moving within and editing
9755: the current message. In addition, the usual Emacs commands are available
9756: (except for a few, such as @kbd{C-r} and @kbd{C-M-h}, that are redefined by Rmail for
9757: other purposes). However, the Rmail buffer is normally read-only, and to
9758: alter it you must use the Rmail command @kbd{C-r} described below.
9759:
9760: @table @kbd
9761: @item t
9762: Toggle display of original headers (@code{rmail-toggle-headers}).
9763: @item C-r
9764: Edit current message (@code{rmail-edit-current-message}).
9765: @end table
9766:
9767: @kindex t (Rmail)
9768: @findex rmail-toggle-header
9769: @vindex rmail-ignored-headers
9770: Rmail reformats the header of each message before displaying it.
9771: Normally this involves deleting most header fields, on the grounds that
9772: they are not interesting. The variable @code{rmail-ignored-headers} should
9773: contain a regexp that matches the header fields to discard in this way.
9774: The original headers are saved permanently, and to see what they look like,
9775: use the @kbd{t} (@code{rmail-toggle-headers}) command. This discards the reformatted
9776: headers of the current message and displays it with the original headers.
9777: Repeating @kbd{t} reformats the message again. Selecting the message again
9778: also reformats.
9779:
9780: @kindex C-r (Rmail)
9781: @findex rmail-edit-current-message
9782: The Rmail buffer is normally read only, and most of the characters you
9783: would type to modify it (including most letters) are redefined as Rmail
9784: commands. This is usually not a problem since it is rare to want to change
9785: the text of a message. When you do want to do this, the way is to type
9786: @kbd{C-r} (@code{rmail-edit-current-message}), which changes from Rmail mode into
9787: Rmail Edit mode, another major mode which is nearly the same as Text mode.
9788: The mode line illustrates this change.
9789:
9790: In Rmail Edit mode, letters insert themselves as usual and the Rmail
9791: commands are not available. When you are finished editing the message and
9792: are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to
9793: Rmail mode. Alternatively, you can return to Rmail mode but cancel all the
9794: editing that you have done by typing @kbd{C-c C-]}.
9795:
9796: @vindex rmail-edit-mode-hook
9797: Entering Rmail Edit mode calls with no arguments the value of the variable
9798: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
9799: does the same with the variable @code{rmail-edit-mode-hook}.
9800:
9801: @node Rmail Digest,, Rmail Editing, Rmail
9802: @section Digest Messages
9803: @cindex digest message
9804: @cindex undigestify
9805:
9806: A @dfn{digest message} is a message which exists to contain and carry
9807: several other messages. Digests are used on moderated mailing lists; all
9808: the messages that arrive for the list during a period of time such as one
9809: day are put inside a single digest which is then sent to the subscribers.
9810: Transmitting the single digest uses much less computer time than
9811: transmitting the individual messages even though the total size is the
9812: same, because the per-message overhead in network mail transmission is
9813: considerable.
9814:
9815: @findex undigestify-rmail-message
9816: When you receive a digest message, the most convenient way to read it is
9817: to @dfn{undigestify} it: to turn it back into many individual messages.
9818: Then you can read and delete the individual messages as it suits you.
9819:
9820: To undigestify a message, select it and then type @kbd{M-x
9821: undigestify-rmail-message}. This copies each submessage as a separate
9822: Rmail message and inserts them all following the digest. The digest
9823: message itself is flagged as deleted.
9824:
9825: @iftex
9826: @chapter Miscellaneous Commands
9827:
9828: This chapter contains several brief topics that do not fit anywhere else.
9829:
9830: @end iftex
9831: @node Recursive Edit, Narrowing, Rmail, Top
9832: @section Recursive Editing Levels
9833: @cindex recursive edit
9834:
9835: A @dfn{recursive edit} is a situation in which you are using Emacs
9836: commands to perform arbitrary editing while in the middle of another Emacs
9837: command. For example, when you type @kbd{C-r} inside of a @code{query-replace},
9838: you enter a recursive edit in which you can change the current buffer. On
9839: exiting from the recursive edit, you go back to the @code{query-replace}.
9840:
9841: @kindex C-M-c
9842: @findex exit-recursive-edit
9843: @cindex exiting
9844: @dfn{Exiting} the recursive edit means returning to the unfinished
9845: command, which continues execution. For example, exiting the recursive
9846: edit requested by @kbd{C-r} in @code{query-replace} causes query replacing
9847: to resume. Exiting is done with @kbd{C-M-c} (@code{exit-recursive-edit}).
9848:
9849: @kindex C-]
9850: @findex abort-recursive-edit
9851: You can also @dfn{abort} the recursive edit. This is like exiting, but
9852: also quits the unfinished command immediately. Use the command @kbd{C-]}
9853: (@code{abort-recursive-edit}) for this. @xref{Quitting}.
9854:
9855: The mode line shows you when you are in a recursive edit, by displaying
9856: square brackets around the parentheses that always surround the major and
9857: minor mode names. Every window's mode line shows this, in the same way,
9858: since being in a recursive edit is true regardless of what buffer is
9859: selected.
9860:
9861: @findex top-level
9862: It is possible to be in recursive edits within recursive edits. For
9863: example, after typing @kbd{C-r} in a @code{query-replace}, you might type a
9864: command that entered the debugger. In such circumstances, two or more sets
9865: of square brackets appear in the mode line. Exiting the inner recursive
9866: edit (such as, with the debugger @kbd{c} command) would resume the command
9867: where it called the debugger. After the end of this command, you would be
9868: able to exit the first recursive edit. Aborting also gets out of only one
9869: level of recursive edit; it returns immediately to the command level of the
9870: previous recursive edit. So you could immediately abort that one too.
9871:
9872: Alternatively, the command @kbd{M-x top-level} aborts all levels of
9873: recursive edits, returning immediately to the top level command reader.
9874:
9875: The text being edited inside the recursive edit need not be the same text
9876: that you were editing at top level. It depends on what the recursive edit
9877: is for. If the command that invokes the recursive edit selects a different
9878: buffer first, that is the buffer you will edit recursively. In any case,
9879: you can switch buffers within the recursive edit in the normal manner (as
9880: long as the buffer-switching keys have not been rebound). You could
9881: probably do all the rest of your editing inside the recursive edit,
9882: visiting files and all. But this could have surprising effects (such as
9883: stack overflow) from time to time. So remember to exit or abort the
9884: recursive edit when you no longer need it.
9885:
9886: In general, GNU Emacs tries to avoid using recursive edits. It is
9887: usually preferable to allow the user to switch among the possible editing
9888: modes in any order he likes. With recursive edits, the only way to get to
9889: another state is to go ``back'' to the state that the recursive edit was
9890: invoked from.
9891:
9892: @node Narrowing, Shell, Recursive Edit, Top
9893: @section Narrowing
9894: @cindex widening
9895: @cindex restriction
9896: @cindex narrowing
9897:
9898: @dfn{Narrowing} means focusing in on some portion of the buffer, making
9899: the rest temporarily invisible and inaccessible. Cancelling the narrowing,
9900: and making the entire buffer once again visible, is called @dfn{widening}.
9901: The amount of narrowing in effect in a buffer at any time is called the
9902: buffer's @dfn{restriction}.
9903:
9904: @c WideCommands
9905: @table @kbd
9906: @item C-x n
9907: Narrow down to between point and mark (@code{narrow-to-region}).
9908: @item C-x w
9909: Widen to make the entire buffer visible again (@code{widen}).
9910: @end table
9911:
9912: When you have narrowed down to a part of the buffer, that part appears to
9913: be all there is. You can't see the rest, you can't move into it (motion
9914: commands won't go outside the visible part), you can't change it in any
9915: way. However, it is not gone, and if you save the file all the invisible
9916: text will be saved. In addition to sometimes making it easier to
9917: concentrate on a single subroutine or paragraph by eliminating clutter,
9918: narrowing can be used to restrict the range of operation of a replace
9919: command or repeating keyboard macro. The word @samp{Narrow} appears in the
9920: mode line whenever narrowing is in effect.
9921:
9922: @kindex C-x n
9923: @findex narrow-to-region
9924: The primary narrowing command is @kbd{C-x n} (@code{narrow-to-region}).
9925: It sets the current buffer's restrictions so that the text in the current
9926: region remains visible but all text before the region or after the region
9927: is invisible. Point and mark do not change.
9928:
9929: Because narrowing can easily confuse users who do not understand it,
9930: @code{narrow-to-region} is normally a disabled command. Attempting to use
9931: this command asks for confirmation and gives you the option of enabling it;
9932: once you enable the command, confirmation will no longer be required for
9933: it. @xref{Disabling}.
9934:
9935: @kindex C-x w
9936: @findex widen
9937: The way to undo narrowing is to widen with @kbd{C-x w} (@code{widen}).
9938: This makes all text in the buffer accessible again.
9939:
9940: You can get information on what part of the buffer you are narrowed down
9941: to using the @code{C-x =} command. @xref{Position Info}.
9942:
9943: @node Shell, Hardcopy, Narrowing, Top
9944: @section Running Shell Commands from Emacs
9945: @cindex subshell
9946: @cindex shell commands
9947:
9948: Emacs has commands for passing single command lines to inferior shell
9949: processes; it can also run a shell interactively with input and output to
9950: an Emacs buffer @samp{*shell*}.
9951:
9952: @table @kbd
9953: @item M-!
9954: Run a specified shell command line and display the output
9955: (@code{shell-command}).
9956: @item M-|
9957: Run a specified shell command line with region contents as input;
9958: optionally replace the region with the output
9959: (@code{shell-command-on-region}).
9960: @item M-x shell
9961: Run a subshell with input and output through an Emacs buffer.
9962: You can then give commands interactively.
9963: @end table
9964:
9965: @subsection Single Shell Commands
9966:
9967: @kindex M-!
9968: @findex shell-command
9969: @kbd{M-!} (@code{shell-command}) reads a line of text using the
9970: minibuffer and creates an inferior shell to execute the line as a command.
9971: Standard input from the command comes from the null device. If the shell
9972: command produces any output, the output goes into an Emacs buffer named
9973: @samp{*Shell Command Output*}, which is displayed in another window but not
9974: selected. A numeric argument, as in @kbd{M-1 M-!}, directs this command to
9975: insert any output into the current buffer. In that case, point is left
9976: before the output and the mark is set after the output.
9977:
9978: @kindex M-|
9979: @findex shell-command-on-region
9980: @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but passes
9981: the contents of the region as input to the shell command, instead of no
9982: input. If a numeric argument is used, meaning insert output in the current
9983: buffer, then the old region is deleted first and the output replaces it as
9984: the contents of the region.@refill
9985:
9986: @vindex shell-file-name
9987: @cindex environment
9988: Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
9989: shell to use. This variable is initialized based on your @code{SHELL}
9990: environment variable when Emacs is started. If the file name does not
9991: specify a directory, the directories in the list @code{exec-path} are
9992: searched; this list is initialized based on the environment variable
9993: @code{PATH} when Emacs is started. Your @file{.emacs} file can override
9994: either or both of these default initializations.@refill
9995:
9996: With @kbd{M-!} and @kbd{M-|}, Emacs has to wait until the shell command
9997: completes. You can quit with @kbd{C-g}; that terminates the shell command.
9998:
9999: @subsection Interactive Inferior Shell
10000:
10001: @findex M-x shell
10002: To run a subshell interactively, putting its typescript in an Emacs
10003: buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named
10004: @samp{*shell*} and runs a subshell with input coming from and output going
10005: to that buffer. That is to say, any ``terminal output'' from the subshell
10006: will go into the buffer, advancing point, and any ``terminal input'' for
10007: the subshell comes from text in the buffer. To give input to the subshell,
10008: go to the end of the buffer and type the input, terminated by @key{RET}.
10009:
10010: Emacs does not wait for the subshell to do anything. You can switch
10011: windows or buffers and edit them while the shell is waiting, or while it is
10012: running a command. Output from the subshell waits until Emacs has time to
10013: process it; this happens whenever Emacs is waiting for keyboard input or
10014: for time to elapse.
10015:
10016: @vindex explicit-shell-file-name
10017: The file name used to load the subshell is the value of the variable
10018: @code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise, the
10019: environment variable @code{ESHELL} is used, or the environment variable
10020: @code{SHELL} if there is no @code{ESHELL}. If no directory is specified,
10021: the directories in the list @code{exec-path} are searched; see
10022: above.@refill
10023:
10024: As soon as the subshell is started, it is sent as input the contents of
10025: the file @file{~/.emacs_@var{shellname}}, if that file exists, where
10026: @var{shellname} is the name of the file that the shell was loaded from.
10027: For example, if you use @code{csh}, the file sent to it is
10028: @file{~/.emacs_csh}.@refill
10029:
10030: @cindex Shell mode
10031: The shell buffer uses Shell mode, which defines several special keys
10032: attached to the @kbd{C-c} prefix. They are chosen to resemble the usual
10033: editing and job control characters present in shells that are not under
10034: Emacs, except that you must type @kbd{C-c} first. Here is a complete list
10035: of the special key bindings of Shell mode:
10036:
10037: @kindex RET
10038: @kindex C-c C-d
10039: @kindex C-c C-u
10040: @kindex C-c C-w
10041: @kindex C-c C-c
10042: @kindex C-c C-z
10043: @kindex C-c C-\
10044: @kindex C-c C-o
10045: @kindex C-c C-r
10046: @kindex C-c C-y
10047: @findex send-shell-input
10048: @findex shell-send-eof
10049: @findex interrupt-shell-subjob
10050: @findex stop-shell-subjob
10051: @findex quit-shell-subjob
10052: @findex kill-output-from-shell
10053: @findex show-output-from-shell
10054: @findex copy-last-shell-input
10055: @vindex shell-prompt-pattern
10056: @table @kbd
10057: @item @key{RET}
10058: At end of buffer send line as input; otherwise, copy current line to end of
10059: buffer and send it (@code{send-shell-input}). When a line is copied, any
10060: text at the beginning of the line that matches the variable
10061: @code{shell-prompt-pattern} is left out; this variable's value should be a
10062: regexp string that matches the prompts that you use in your subshell.
10063: @item C-c C-d
10064: Send end-of-file as input, probably causing the shell or its current
10065: subjob to finish (@code{shell-send-eof}).
10066: @item C-c C-u
10067: Kill all text that has yet to be sent as input (@code{kill-shell-input}).
10068: @item C-c C-w
10069: Kill a word before point (@code{backward-kill-word}).
10070: @item C-c C-c
10071: Interrupt the shell or its current subjob if any
10072: (@code{interrupt-shell-subjob}).
10073: @item C-c C-z
10074: Stop the shell or its current subjob if any (@code{stop-shell-subjob}).
10075: @item C-c C-\
10076: Send quit signal to the shell or its current subjob if any
10077: (@code{quit-shell-subjob}).
10078: @item C-c C-o
10079: Delete last batch of output from shell (@code{kill-output-from-shell}).
10080: @item C-c C-r
10081: Scroll top of last batch of output to top of window
10082: (@code{show-output-from-shell}).
10083: @item C-c C-y
10084: Copy the previous bunch of shell input, and insert it into the
10085: buffer before point (@code{copy-last-shell-input}). No final newline
10086: is inserted, and the input copied is not resubmitted until you type
10087: @key{RET}.
10088: @end table
10089:
10090: @vindex shell-pushd-regexp
10091: @vindex shell-popd-regexp
10092: @vindex shell-cd-regexp
10093: @code{cd}, @code{pushd} and @code{popd} commands given to the inferior
10094: shell are watched by Emacs so it can keep the @samp{*shell*} buffer's
10095: default directory the same as the shell's working directory. These
10096: commands are recognized syntactically by examining lines of input that are
10097: sent. If you use aliases for these commands, you can tell Emacs to
10098: recognize them also. For example, if the value of the variable
10099: @code{shell-pushd-regexp} matches the beginning of a shell command line,
10100: that line is regarded as a @code{pushd} command. Change this variable when
10101: you add aliases for @samp{pushd}. Likewise, @code{shell-popd-regexp} and
10102: @code{shell-cd-regexp} are used to recognize commands with the meaning of
10103: @samp{popd} and @samp{cd}. These commands are recognized only at the
10104: beginning of a shell command line.@refill
10105:
10106: @node Hardcopy, Dissociated Press, Shell, Top
10107: @section Hardcopy Output
10108: @cindex hardcopy
10109:
10110: @table @kbd
10111: @item M-x print-buffer
10112: Print hardcopy of current buffer using Unix command @code{lpr -p}.
10113: This makes page headings containing the file name and page number.
10114: @item M-x lpr-buffer
10115: Print hardcopy of current buffer using Unix command @code{lpr}.
10116: This makes no page headings.
10117: @item M-x print-region
10118: Like @code{print-buffer} but prints only the current region.
10119: @item M-x lpr-region
10120: Like @code{lpr-buffer} but prints only the current region.
10121: @end table
10122:
10123: @findex print-buffer
10124: @findex print-region
10125: @findex lpr-buffer
10126: @findex lpr-region
10127: @vindex lpr-switches
10128: All the hardcopy commands pass extra switches to the @code{lpr} program
10129: based on the value of the variable @code{lpr-switches}. Its value should
10130: be a list of strings, each string a switch starting with @samp{-}.
10131:
10132: @node Dissociated Press, Amusements, Hardcopy, Top
10133: @section Dissociated Press
10134:
10135: @findex dissociated-press
10136: @kbd{M-x dissociated-press} is a command for scrambling a file of text
10137: either word by word or character by character. Starting from a buffer of
10138: straight English, it produces extremely amusing output. The input comes
10139: from the current Emacs buffer. Dissociated Press writes its output in a
10140: buffer named @samp{*Dissociation*}, and redisplays that buffer after every
10141: couple of lines (approximately) to facilitate reading it.
10142:
10143: @code{dissociated-press} asks every so often whether to continue
10144: operating. Answer @kbd{n} to stop it. You can also stop at any time by
10145: typing @kbd{C-g}. The dissociation output remains in the @samp{*Dissociation*}
10146: buffer for you to copy elsewhere if you wish.
10147:
10148: @cindex presidentagon
10149: Dissociated Press operates by jumping at random from one point in the
10150: buffer to another. In order to produce plausible output rather than
10151: gibberish, it insists on a certain amount of overlap between the end of one
10152: run of consecutive words or characters and the start of the next. That is,
10153: if it has just printed out `president' and then decides to jump to a
10154: different point in the file, it might spot the `ent' in `pentagon' and
10155: continue from there, producing `presidentagon'. Long sample texts produce
10156: the best results.
10157:
10158: @cindex againformation
10159: A positive argument to @kbd{M-x Dissociated Press} tells it to operate
10160: character by character, and specifies the number of overlap characters. A
10161: negative argument tells it to operate word by word and specifies the number
10162: of overlap words. In this mode, whole words are treated as the elements to
10163: be permuted, rather than characters. No argument is equivalent to an
10164: argument of two. For your againformation, the output goes only into the
10165: buffer @samp{*Dissociation*}. The buffer you start with is not changed.
10166:
10167: @cindex Markov chain
10168: @cindex ignoriginal
10169: @cindex techniquitous
10170: Dissociated Press produces nearly the same results as a Markov chain
10171: based on a frequency table constructed from the sample text. It is,
10172: however, an independent, ignoriginal invention. Dissociated Press
10173: techniquitously copies several consecutive characters from the sample
10174: between random choices, whereas a Markov chain would choose randomly for
10175: each word or character. This makes for more plausible sounding results,
10176: and runs faster.
10177:
10178: @cindex outragedy
10179: @cindex buggestion
10180: @cindex properbose
10181: It is a mustatement that too much use of Dissociated Press can be a
10182: developediment to your real work. Sometimes to the point of outragedy.
10183: And keep dissociwords out of your documentation, if you want it to be well
10184: userenced and properbose. Have fun. Your buggestions are welcome.
10185:
10186: @node Amusements, Customization, Dissociated Press, Top
10187: @section Other Amusements
10188: @cindex boredom
10189: @findex hanoi
10190:
10191: If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are
10192: considerably bored, give it a numeric argument. If you are very very
10193: bored, try an argument of 9.
10194:
10195: When you are frustrated, try the famous Eliza program. Just do
10196: @kbd{M-x doctor}.
10197:
10198: @node Customization, Quitting, Amusements, Top
10199: @chapter Customization
10200: @cindex customization
10201:
10202: This chapter talks about various topics relevant to adapting the
10203: behavior of Emacs in minor ways.
10204:
10205: All kinds of customization affect only the particular Emacs job that you
10206: do them in. They are completely lost when you kill the Emacs job, and have
10207: no effect on other Emacs jobs you may run at the same time or later. The
10208: only way an Emacs job can affect anything outside of it is by writing a
10209: file; in particular, the only way to make a customization `permanent' is to
10210: put something in your @file{.emacs} file or other appropriate file to do the
10211: customization in each session. @xref{Init File}.
10212:
10213: @menu
10214: * Minor Modes:: Each minor mode is one feature you can turn on
10215: independently of any others.
10216: * Variables:: Many Emacs commands examine Emacs variables
10217: to decide what to do; by setting variables,
10218: you can control their functioning.
10219: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
10220: to be replayed with a single command.
10221: * Key Bindings:: The keymaps say what command each key runs.
10222: By changing them, you can "redefine keys".
10223: * Syntax:: The syntax table controls how words and expressions
10224: are parsed.
10225: * Init File:: How to write common customizations in the @file{.emacs} file.
10226: @end menu
10227:
10228: @node Minor Modes, Variables, Customization, Customization
10229: @section Minor Modes
10230: @cindex minor modes
10231:
10232: @cindex mode line
10233: Minor modes are options which you can use or not. For example, Auto Fill
10234: mode is a minor mode in which @key{SPC} breaks lines between words as you
10235: type. All the minor modes are independent of each other and of the
10236: selected major mode. Most minor modes say in the mode line when they are
10237: on; for example, @samp{Fill} in the mode line means that Auto Fill mode is
10238: on.
10239:
10240: Append @code{-mode} to the name of a minor mode to get the name of a
10241: command function that turns the mode on or off. Thus, the command to
10242: enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
10243: commands are usually invoked with @kbd{M-x}, but you can bind keys to them
10244: if you wish. With no argument, the function turns the mode on if it was
10245: off and off if it was on. This is known as @dfn{toggling}. A positive
10246: argument always turns the mode on, and an explicit zero argument or a
10247: negative argument always turns it off.
10248:
10249: @cindex Auto Fill mode
10250: Auto Fill mode allows you to enter filled text without breaking lines
10251: explicitly. Emacs inserts newlines as necessary to prevent lines from
10252: becoming too long. @xref{Filling}.
10253:
10254: @cindex Overwrite mode
10255: Overwrite mode causes ordinary printing characters to replace existing
10256: text instead of shoving it over. For example, if the point is in front of
10257: the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a @kbd{G}
10258: changes it to @samp{FOOGAR}, instead of making it @samp{FOOGBAR} as
10259: usual.@refill
10260:
10261: @cindex Abbrev mode
10262: Abbrev mode allows you to define abbreviations that automatically expand
10263: as you type them. For example, @samp{amd} might expand to @samp{abbrev
10264: mode}. @xref{Abbrevs}, for full information.
10265:
10266: @node Variables, Keyboard Macros, Minor Modes, Customization
10267: @section Variables
10268: @cindex variable
10269: @cindex option
10270:
10271: A @dfn{variable} is a Lisp symbol which has a value. The symbol's name
10272: is also called the name of the variable. Variable names can contain any
10273: characters, but conventionally they are chosen to be words separated by
10274: hyphens. A variable can have a documentation string which describes what
10275: kind of value it should have and how the value will be used.
10276:
10277: Lisp allows any variable to have any kind of value, but most variables
10278: that Emacs uses require a value of a certain type. Often the value should
10279: always be a string, or should always be a number. Sometimes we say that a
10280: certain feature is turned on if a variable is ``non-@code{nil},'' meaning
10281: that if the variable's value is @code{nil}, the feature is off, but the
10282: feature is on for @i{any} other value. The conventional value to use to
10283: turn on the feature---since you have to pick one particular value when you
10284: set the variable---is @code{t}.
10285:
10286: Emacs uses many Lisp variables for internal recordkeeping, as any Lisp
10287: program must, but the most interesting variables for you are the ones that
10288: exist for the sake of customization. Emacs does not (usually) change the
10289: values of these variables; instead, you set the values, and thereby alter
10290: and control the behavior of certain Emacs commands. These variables are
10291: called @dfn{options}. Most options are documented in this manual, and
10292: appear in the Variable Index (@pxref{Variable Index}).
10293:
10294: One example of a variable which is an option is @code{fill-column}, which
10295: specifies the position of the right margin (as a number of characters from
10296: the left margin) to be used by the fill commands (@pxref{Filling}).
10297:
10298: @menu
10299: * Examining:: Examining or setting one variable's value.
10300: * Edit Options:: Examining or editing list of all variables' values.
10301: * Locals:: Per-buffer values of variables.
10302: * File Variables:: How files can specify variable values.
10303: @end menu
10304:
10305: @node Examining, Edit Options, Variables, Variables
10306: @subsection Examining and Setting Variables
10307:
10308: @table @kbd
10309: @item C-h v
10310: @itemx M-x describe-variable
10311: Print the value and documentation of a variable.
10312: @item M-x set-variable
10313: Change the value of a variable.
10314: @end table
10315:
10316: @kindex C-h v
10317: @findex describe-variable
10318: To examine the value of a single variable, use @kbd{C-h v}
10319: (@code{describe-variable}), which reads a variable name using the
10320: minibuffer, with completion. It prints both the value and the
10321: documentation of the variable.
10322:
10323: @example
10324: C-h v fill-column @key{RET}
10325: @end example
10326: @noindent
10327: prints something like
10328: @smallexample
10329: fill-column's value is 75
10330:
10331: Documentation:
10332: *Column beyond which automatic line-wrapping should happen.
10333: Separate value in each buffer.
10334: @end smallexample
10335:
10336: @cindex option
10337: @noindent
10338: The star at the beginning of the documentation indicates that this variable
10339: is an option. @kbd{C-h v} is not restricted to options; they allow any
10340: variable name.
10341:
10342: @findex set-variable
10343: If you know which option you want to set, you can set it using @kbd{M-x
10344: set-variable}. This reads the variable name with the minibuffer (with
10345: completion), and then reads a Lisp expression for the new value using the
10346: minibuffer a second time. For example,
10347:
10348: @example
10349: M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
10350: @end example
10351:
10352: @noindent
10353: sets @code{fill-column} to 75.
10354:
10355: @node Edit Options, Locals, Examining, Variables
10356: @subsection Editing Variable Values
10357:
10358: @table @kbd
10359: @item M-x list-options
10360: Display a buffer listing names, values and documentation of all options.
10361: @item M-x edit-options
10362: Change option values by editing a list of options.
10363: @end table
10364:
10365: @findex list-options
10366: @kbd{M-x list-options} displays a list of all Emacs option variables, in
10367: an Emacs buffer named @samp{*List Options*}. Each option is shown with its
10368: documentation and its current value. Here is what a portion of it might
10369: look like:
10370:
10371: @smallexample
10372: ;; exec-path:
10373: ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
10374: *List of directories to search programs to run in subprocesses.
10375: Each element is a string (directory name) or nil (try default directory).
10376: ;;
10377: ;; fill-column:
10378: 75
10379: *Column beyond which automatic line-wrapping should happen.
10380: Separate value in each buffer.
10381: ;;
10382: ;; find-file-hook:
10383: nil
10384: *If non-nil specifies a function to be called after a buffer
10385: is found or reverted from a file.
10386: The buffer's local variables (if any) will have been processed
10387: before the function is called.
10388: ;;
10389: @end smallexample
10390:
10391: @findex edit-options
10392: @kbd{M-x edit-options} goes one step farther and selects the @samp{*List
10393: Options*} buffer; this buffer uses the major mode Options mode, which
10394: provides commands that allow you to point at an option and change its
10395: value:
10396:
10397: @table @kbd
10398: @item s
10399: Set the variable point is in or near to a new value read using the
10400: minibuffer.
10401: @item x
10402: Toggle the variable point is in or near: if the value was @code{nil},
10403: it becomes @code{t}; otherwise it becomes @code{nil}.
10404: @item 1
10405: Set the variable point is in or near to @code{t}.
10406: @item 0
10407: Set the variable point is in or near to @code{nil}.
10408: @item n
10409: @itemx p
10410: Move to the next or previous variable.
10411: @end table
10412:
10413: @node Locals, File Variables, Edit Options, Variables
10414: @subsection Local Variables
10415:
10416: @table @kbd
10417: @item M-x make-local-variable
10418: Make a variable have a local value in the current buffer.
10419: @item M-x kill-local-variable
10420: Make a variable use its global value in the current buffer.
10421: @end table
10422:
10423: @cindex local variables
10424: Any variable can be made @dfn{local} to a specific Emacs buffer. This
10425: means that its value in that buffer is independent of its value in other
10426: buffers. A few variables are always local in every buffer. Every other
10427: Emacs variable has a @dfn{global} value which is in effect in all buffers
10428: that have not made the variable local.
10429:
10430: Major modes always make the variables they set local to the buffer.
10431: This is why changing major modes in one buffer has no effect on other
10432: buffers.
10433:
10434: @findex make-local-variable
10435: @kbd{M-x make-local-variable} reads the name of a variable and makes it
10436: local to the current buffer. Further changes in this buffer will not
10437: affect others, and further changes in the global value will not affect this
10438: buffer.
10439:
10440: @findex kill-local-variable
10441: @kbd{M-x kill-local-variable} reads the name of a variable and makes it
10442: cease to be local to the current buffer. The global value of the variable
10443: henceforth is in effect in this buffer. Setting the major mode kills all
10444: the local variables of the buffer, except for those variables that are
10445: always local to every buffer.
10446:
10447: @node File Variables,, Locals, Variables
10448: @subsection Local Variables in Files
10449: @cindex local variables in files
10450:
10451: A file can contain a @dfn{local variables list}, which specifies the
10452: values to use for certain Emacs variables when that file is edited.
10453: Visiting the file checks for a local variables list and makes each variable
10454: in the list local to the buffer in which the file is visited, with the
10455: value specified in the file.
10456:
10457: A local variables list goes near the end of the file, in the last page.
10458: (It is often best to put it on a page by itself.) The local variables list
10459: starts with a line containing the string @samp{Local Variables:}, and ends
10460: with a line containing the string @samp{End:}. In between come the
10461: variable names and values, one set per line, as @samp{@var{variable}:@:
10462: @var{value}}. The @var{value}s are not evaluated; they are used literally.
10463:
10464: The line which starts the local variables list does not have to say just
10465: @samp{Local Variables:}. If there is other text before @samp{Local
10466: Variables:}, that text is called the @dfn{prefix}, and if there is other
10467: text after, that is called the @dfn{suffix}. If these are present, each
10468: entry in the local variables list should have the prefix before it and the
10469: suffix after it. This includes the @samp{End:} line. The prefix and
10470: suffix are included to disguise the local variables list as a comment so
10471: that the compiler or text formatter will not be perplexed by it. If you do
10472: not need to disguise the local variables list as a comment in this way, do
10473: not bother with a prefix or a suffix.@refill
10474:
10475: Two ``variable'' names are special in a local variables list: a value for
10476: the variable @code{mode} really sets the major mode, and a value for the
10477: variable @code{eval} is simply evaluated as an expression and the value is
10478: ignored. These are not real variables; setting such variables in any other
10479: context has no such effect. If @code{mode} is used in a local variables
10480: list, it should be the first entry in the list.
10481:
10482: Here is an example of a local variables list:
10483: @example
10484: ;;; Local Variables: ***
10485: ;;; mode:lisp ***
10486: ;;; comment-column:0 ***
10487: ;;; comment-start: ";;; " ***
10488: ;;; comment-end:"***" ***
10489: ;;; End: ***
10490: @end example
10491:
10492: Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}. Note also
10493: that comments in the file begin with and end with the same strings.
10494: Presumably the file contains code in a language which is like Lisp
10495: (like it enough for Lisp mode to be useful) but in which comments start
10496: and end in that way. The prefix and suffix are used in the local
10497: variables list to make the list appear as comments when the file is read
10498: by the compiler or interpreter for that language.
10499:
10500: The start of the local variables list must be no more than 3000
10501: characters from the end of the file, and must be in the last page if the
10502: file is divided into pages. Otherwise, Emacs will not notice it is there.
10503: The purpose of this is so that a stray @samp{Local Variables:}@: not in the
10504: last page does not confuse Emacs, and so that visiting a long file that is
10505: all one page and has no local variables list need not take the time to
10506: search the whole file.
10507:
10508: You may be tempted to try to turn on Auto Fill mode with a local variable
10509: list. That is a mistake. The choice of Auto Fill mode or not is a matter
10510: of individual taste, not a matter of the contents of particular files.
10511: If you want to use Auto Fill, set up major mode hooks with your @file{.emacs}
10512: file to turn it on (when appropriate) for you alone (@pxref{Init File}).
10513: Don't try to use a local variable list that would impose your taste on
10514: everyone.
10515:
10516: @node Keyboard Macros, Key Bindings, Variables, Customization
10517: @section Keyboard Macros
10518:
10519: @cindex keyboard macros
10520: A @dfn{keyboard macro} is a command defined by the user to abbreviate a
10521: sequence of keys. For example, if you discover that you are about to type
10522: @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
10523: macro to do @kbd{C-n C-d} and calling it with a repeat count of forty.
10524:
10525: @c widecommands
10526: @table @kbd
10527: @item C-x (
10528: Start defining a keyboard macro (@code{start-kbd-macro}).
10529: @item C-x )
10530: End the definition of a keyboard macro (@code{end-kbd-macro}).
10531: @item C-x e
10532: Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
10533: @item C-u C-x (
10534: Re-execute last keyboard macro, then add more keys to its definition.
10535: @item C-x q
10536: When this point is reached during macro execution, ask for confirmation
10537: (@code{kbd-macro-query}).
10538: @item M-x name-last-kbd-macro
10539: Give a command name (for the duration of the session) to the most
10540: recently defined keyboard macro.
10541: @item M-x write-kbd-macro
10542: Store the definition of a keyboard macro into a file.
10543: @item M-x append-kbd-macro
10544: Append the definition of a keyboard macro to the end of a file.
10545: @end table
10546:
10547: Keyboard macros differ from ordinary Emacs commands in that they are
10548: written in the Emacs command language rather than in Lisp. This makes it
10549: easier for the novice to write them, and makes them more convenient as
10550: temporary hacks. However, the Emacs command language is not powerful
10551: enough as a programming language to be useful for writing anything
10552: intelligent or general. For such things, Lisp must be used.
10553:
10554: You define a keyboard macro while executing the commands which are the
10555: definition. Put differently, as you are defining a keyboard macro, the
10556: definition is being executed for the first time. This way, you can see
10557: what the effects of your commands are, so that you don't have to figure
10558: them out in your head. When you are finished, the keyboard macro is
10559: defined and also has been, in effect, executed once. You can then do the
10560: whole thing over again by invoking the macro.
10561:
10562: @subsection Basic Use
10563:
10564: @kindex C-x (
10565: @kindex C-x )
10566: @kindex C-x e
10567: @findex start-kbd-macro
10568: @findex end-kbd-macro
10569: @findex call-last-kbd-macro
10570: To start defining a keyboard macro, type the @kbd{C-x (} command
10571: (@code{start-kbd-macro}). From then on, your keys continue to be
10572: executed, but also become part of the definition of the macro. @samp{Def}
10573: appears in the mode line to remind you of what is going on. When you are
10574: finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
10575: definition (without becoming part of it!). For example
10576:
10577: @example
10578: C-x ( M-F foo C-x )
10579: @end example
10580:
10581: @noindent
10582: defines a macro to move forward a word and then insert @samp{foo}.
10583:
10584: The macro thus defined can be invoked again with the @kbd{C-x e} command
10585: (@code{call-last-kbd-macro}), which may be given a repeat count as a
10586: numeric argument to execute the macro many times. @kbd{C-x )} can also be
10587: given a repeat count as an argument, in which case it repeats the macro
10588: that many times right after defining it, but defining the macro counts as
10589: the first repetition (since it is executed as you define it). So, giving
10590: @kbd{C-x )} an argument of 4 executes the macro immediately 3 additional
10591: times. An argument of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the
10592: macro indefinitely (until it gets an error, or you type @kbd{C-g}).
10593:
10594: If you wish to repeat an operation at regularly spaced places in the
10595: text, define a macro and include as part of the macro the commands to move
10596: to the next place you want to use it. For example, if you want to change
10597: each line, you should position point at the start of a line, and define a
10598: macro to change that line and leave point at the start of the next line.
10599: Then repeating the macro will operate on successive lines.
10600:
10601: After you have terminated the definition of a keyboard macro, you can add
10602: to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
10603: to plain @kbd{C-x (} followed by retyping the whole definition so far. As
10604: a consequence it re-executes the macro as previously defined.
10605:
10606: @subsection Naming and Saving Keyboard Macros
10607:
10608: @findex name-last-kbd-macro
10609: If you wish to save a keyboard macro for longer than until you define the
10610: next one, you must give it a name or install it on a command sequence. To
10611: give the macro a name, use @kbd{M-x name-last-kbd-macro}. This reads a
10612: name as an argument using the minibuffer and defines that name to execute
10613: the macro. The macro name is a Lisp symbol, and defining it in this way
10614: makes it a valid command name for calling with @kbd{M-x} or for binding a
10615: key to with @code{global-set-key} (@pxref{Keymaps}).
10616:
10617: @findex write-kbd-macro
10618: @findex append-kbd-macro
10619: Once a macro has a command name, you can save its definition in a file.
10620: Then it can be used in another editing session.
10621:
10622: @example
10623: M-x write-kbd-macro @key{RET} @var{macroname} @key{RET} @var{file} @key{RET}
10624: @end example
10625:
10626: @noindent
10627: writes a Lisp expression for the definition of the keyboard macro named
10628: @var{macroname} into the file @var{file}, replacing any previous contents.
10629: The file can be loaded with @code{load} (@pxref{Lisp Libraries}).
10630: The command @code{append-kbd-macro} is similar, but adds the definition
10631: to the end of the file, in addition to the previous contents. You might
10632: want to add a macro in this way to your init file @file{~/.emacs}; then
10633: it will automatically be defined when you run Emacs again.
10634:
10635: @subsection Executing Macros with Variations
10636:
10637: @kindex C-x q
10638: @findex kbd-macro-query
10639: Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect similar
10640: to that of @code{query-replace}, where the macro asks you each time around
10641: whether to make a change. When you are defining the macro, type @kbd{C-x
10642: q} at the point where you want the query to occur. During macro
10643: definition, the @kbd{C-x q} does nothing, but when the macro is invoked the
10644: @kbd{C-x q} reads a character from the terminal to decide whether to
10645: continue.
10646:
10647: The special answers are @key{SPC}, @key{DEL}, @kbd{C-d}, @kbd{C-l} and
10648: @kbd{C-r}. Any other character terminates execution of the keyboard macro
10649: and is then read as a command. @key{SPC} means to continue. @key{DEL}
10650: means to skip the remainder of this repetition of the macro, starting again
10651: from the beginning in the next repetition. @kbd{C-d} means to skip the
10652: remainder of this repetition and cancel further repetition. @kbd{C-l}
10653: clears the screen and asks you again for a character to say what to do.
10654: @kbd{C-r} enters a recursive editing level, in which you can perform
10655: editing which is not part of the macro. When you exit the recursive edit
10656: using @kbd{C-M-c}, you are asked again how to continue with the keyboard
10657: macro. If you type a @key{SPC} at this time, the rest of the macro
10658: definition is executed. It is up to you to leave point and the text in a
10659: state such that the rest of the macro will do what you want.@refill
10660:
10661: @kbd{C-u C-x q}, @kbd{C-x q} with a numeric argument, performs a different
10662: function. It enters a recursive edit reading input from the keyboard, both
10663: when you type it during the definition of the macro, and when it is
10664: executed from the macro. During definition, the editing you do inside the
10665: recursive edit does not become part of the macro. During macro execution,
10666: the recursive edit gives you a chance to do some particularized editing.
10667: @xref{Recursive Edit}.
10668:
10669: @node Key Bindings, Syntax, Keyboard Macros, Customization
10670: @section Customizing Key Bindings
10671:
10672: This section deals with the @dfn{keymaps} which define the bindings
10673: between keys and functions, and says how you can customize these bindings.
10674: @cindex command
10675: @cindex function
10676: @cindex command name
10677:
10678: A command is a Lisp function whose definition provides for interactive
10679: use. Like every Lisp function, a command has a function name, a Lisp
10680: symbol whose name usually consists of lower case letters and dashes.
10681:
10682: The bindings between characters and command functions are recorded in
10683: data structures called @dfn{keymaps}. Emacs has many of these. One, the
10684: @dfn{global} keymap, defines the meanings of the single keys that are
10685: defined regardless of major mode. Each major mode has another keymap, its
10686: @dfn{local keymap}, which contains overriding definitions for the single
10687: keys that are to be redefined in that mode. Finally, each prefix key has a
10688: keymap which defines the key sequences that start with that prefix.
10689:
10690: @menu
10691: * Keymaps:: Definition of the keymap data structure.
10692: * Rebinding:: How to redefine one key's meaning conveniently.
10693: * Disabling:: Disabling a command means confirmation is required
10694: before it can be executed. This is done to protect
10695: beginners from surprises.
10696: @end menu
10697:
10698: @node Keymaps, Rebinding, Key Bindings, Key Bindings
10699: @subsection Keymaps
10700: @cindex keymap
10701:
10702: @cindex global keymap
10703: @vindex global-map
10704: The bindings between characters and command functions are recorded in
10705: data structures called @dfn{keymaps}. Emacs has many of these. One, the
10706: @dfn{global} keymap, defines the meanings of the single keys that are
10707: defined regardless of major mode. It is the value of the variable
10708: @code{global-map}.
10709:
10710: @cindex local keymap
10711: @vindex c-mode-map
10712: @vindex lisp-mode-map
10713: Each major mode has another keymap, its @dfn{local keymap}, which
10714: contains overriding definitions for the single keys that are to be
10715: redefined in that mode. Each buffer records which local keymap is
10716: installed for it at any time, and the current buffer's local keymap is the
10717: only one that directly affects command execution. The local keymaps for
10718: Lisp mode, C mode, and many other major modes always exist even when not in
10719: use. They are the values of the variables @code{lisp-mode-map},
10720: @code{c-mode-map}, and so on. For major modes less often used, the local
10721: keymap is sometimes constructed only when the mode is used for the first
10722: time in a session. This is to save space.
10723:
10724: @vindex minibuffer-local-map
10725: @vindex minibuffer-local-ns-map
10726: @vindex minibuffer-local-completion-map
10727: @vindex minibuffer-local-must-match-map
10728: There are local keymaps for the minibuffer too; they contain various
10729: completion and exit commands.
10730:
10731: @itemize @bullet
10732: @item
10733: @code{minibuffer-local-map} is used for ordinary input (no completion).
10734: @item
10735: @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
10736: just like @key{RET}. This is used mainly for Mocklisp compatibility.
10737: @item
10738: @code{minibuffer-local-completion-map} is for permissive completion.
10739: @item
10740: @code{minibuffer-local-must-match-map} is for strict completion and
10741: for cautious completion.
10742: @end itemize
10743:
10744: @vindex ctl-x-map
10745: @vindex help-map
10746: @vindex esc-map
10747: Finally, each prefix key has a keymap which defines the key sequences
10748: that start with it. For example, @code{ctl-x-map} is the keymap used for
10749: characters following a @kbd{C-x}, and @code{help-map} is the keymap used
10750: for characters following a @kbd{C-h}. @code{esc-map} is the keymap used
10751: for characters following @key{ESC}, and therefore for all Meta characters
10752: (see below). In fact, the definition of a prefix key is just the keymap to
10753: use for looking up the following character. Actually, the definition is
10754: sometimes a Lisp symbol whose function definition is the following character
10755: keymap. The effect is the same, but it provides a command name for the
10756: prefix key that can be used as a description of what the prefix key is for.
10757: Thus, the binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose
10758: function definition is the keymap for @kbd{C-x} commands, the value of
10759: @code{ctl-x-map}.@refill
10760:
10761: Prefix key definitions of this sort can appear in either the global map
10762: or a local map. The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC}
10763: as prefix keys appear in the global map, so these prefix keys are always
10764: available. Major modes can locally redefine a key as a prefix by putting
10765: a prefix key definition for it in the local map.@refill
10766:
10767: A mode can also put a prefix definition of a global prefix character such
10768: as @kbd{C-x} into its local map. This is how major modes override the
10769: definitions of certain keys that start with @kbd{C-x}. This case is
10770: special, because the local definition does not entirely replace the global
10771: one. When both the global and local definitions of a key are other
10772: keymaps, the next character is looked up in both keymaps, with the local
10773: definition overriding the global one as usual. So, the character after the
10774: @kbd{C-x} is looked up in both the major mode's own keymap for redefined
10775: @kbd{C-x} commands and in @code{ctl-x-map}. If the major mode's own keymap
10776: for @kbd{C-x} commands contains @code{nil}, the definition from the global
10777: keymap for @kbd{C-x} commands is used.@refill
10778:
10779: @cindex sparse keymap
10780: A keymap is actually a Lisp object. The simplest form of keymap is a
10781: Lisp vector of length 128. The binding for a character in such a keymap is
10782: found by indexing into the vector with the character as an index. A keymap
10783: can also be a Lisp list whose car is the symbol @code{keymap} and whose
10784: remaining elements are pairs of the form @code{(@var{char} . @var{binding})}.
10785: Such lists are called @dfn{sparse keymaps} because they are used when most
10786: of the characters' entries will be @code{nil}. Sparse keymaps are used
10787: mainly for prefix characters.
10788:
10789: Keymaps are only of length 128, so what about Meta characters, whose
10790: codes are from 128 to 255? A key that contains a Meta character actually
10791: represents it as a sequence of two characters, the first of which is
10792: @key{ESC}. So the key @kbd{M-a} is really represented as @kbd{@key{ESC}
10793: a}, and its binding is found at the slot for @samp{a} in
10794: @code{esc-map}.@refill
10795:
10796: @node Rebinding, Disabling, Keymaps, Key Bindings
10797: @subsection Changing Key Bindings Interactively
10798:
10799: The way to redefine an Emacs key is to change its entry in a keymap.
10800: You can change the global keymap, in which case the change is effective in
10801: all major modes (except those that have their own overriding local
10802: definitions for the same key). Or you can change the current buffer's
10803: local map, which affects all buffers using the same major mode.
10804: @findex global-set-key
10805: @findex local-set-key
10806:
10807: @table @kbd
10808: @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
10809: Defines @var{key} globally to run @var{cmd}.
10810: @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
10811: Defines @var{key} locally (in the major mode now in effect) to run
10812: @var{cmd}.
10813: @end table
10814:
10815: For example,
10816:
10817: @example
10818: M-x global-set-key @key{RET} C-f next-line @key{RET}
10819: @end example
10820:
10821: @noindent
10822: would redefine @kbd{C-f} to move down a line. The fact that @var{cmd} is
10823: read second makes it serve as a kind of confirmation for @var{key}.
10824:
10825: These functions offer no way to specify a particular prefix keymap as the
10826: one to redefine in, but that is not necessary, as you can include prefixes
10827: in @var{key}. @var{key} is read by reading characters one by one until
10828: they amount to a complete key (that is, not a prefix key). Thus, if you
10829: type @kbd{C-f} for @var{key}, that's the end; the minibuffer is entered
10830: immediately to read @var{cmd}. But if you type @kbd{C-x}, another
10831: character is read; if that is @kbd{4}, another character is read, and so
10832: on. For example,@refill
10833:
10834: @example
10835: M-x global-set-key @key{RET} C-x 4 $ dictionary-other-window @key{RET}
10836: @end example
10837:
10838: @noindent
10839: would redefine @kbd{C-x 4 $} to run the (fictitious) command
10840: @code{dictionary-other-window}.
10841:
10842: @findex define-key
10843: The most general way to modify a keymap is the function @code{define-key},
10844: used in Lisp code (such in your @file{.emacs} file). @code{define-key}
10845: takes three arguments: the keymap, the key to modify in it, and the new
10846: definition. @xref{Init File}, for an example.
10847:
10848: @node Disabling,, Rebinding, Key Bindings
10849: @subsection Disabling Commands
10850: @cindex disabled command
10851:
10852: Disabling a command marks the command as requiring confirmation before it
10853: can be executed. The purpose of disabling a command is to prevent
10854: beginning users from executing it by accident and being confused.
10855:
10856: The direct mechanism for disabling a command is to have a non-@code{nil}
10857: @code{disabled} property on the Lisp symbol for the command. These
10858: properties are normally set up by the user's @file{.emacs} file with
10859: Lisp expressions such as
10860:
10861: @example
10862: (put 'delete-region 'disabled t)
10863: @end example
10864:
10865: @findex disable-command
10866: @findex enable-command
10867: You can make a command disabled either by editing the @file{.emacs} file
10868: directly or with the command @kbd{M-x disable-command}, which edits the
10869: @file{.emacs} file for you. @xref{Init File}.
10870:
10871: Attempting to invoke a disabled command interactively in Emacs causes the
10872: display of a window containing the command's name, its documentation, and
10873: some instructions on what to do immediately; then Emacs asks for input
10874: saying whether to execute the command as requested, enable it and execute,
10875: or cancel it. If you decide to enable the command, you are asked whether to
10876: do this permanently or just for the current session. Enabling permanently
10877: works by automatically editing your @file{.emacs} file. You can use
10878: @kbd{M-x enable-command} to enable a command permanently without
10879: executing it.
10880:
10881: Whether a command is disabled is independent of what key is used to
10882: invoke it; it also applies if the command is invoked using @kbd{M-x}.
10883: Disabling a command has no effect on calling it as a function from Lisp
10884: programs.
10885:
10886: @node Syntax, Init File, Key Bindings, Customization
10887: @section The Syntax Table
10888: @cindex syntax table
10889:
10890: All the Emacs commands which parse words or balance parentheses are
10891: controlled by the @dfn{syntax table}. The syntax table says which
10892: characters are opening delimiters, which are parts of words, which are
10893: string quotes, and so on. Actually, each major mode has its own syntax
10894: table (though sometimes related major modes use the same one) which it
10895: installs in each buffer that uses that major mode. The syntax table
10896: installed in the current buffer is the one that all commands use. So we
10897: will call it ``the syntax table''. A syntax table is a Lisp object, a
10898: vector of length 256 whose elements are numbers.
10899:
10900: The syntax table entry for a character holds six pieces of information:
10901:
10902: @itemize @bullet
10903: @item
10904: The syntactic class of the character, represented as a small integer.
10905: @item
10906: The matching delimiter, for delimiter characters only.
10907: The matching delimiter of @samp{(} is @samp{)}, and vice versa.
10908: @item
10909: A flag saying whether the character is the first character of a
10910: two-character comment starting sequence.
10911: @item
10912: A flag saying whether the character is the second character of a
10913: two-character comment starting sequence.
10914: @item
10915: A flag saying whether the character is the first character of a
10916: two-character comment ending sequence.
10917: @item
10918: A flag saying whether the character is the second character of a
10919: two-character comment ending sequence.
10920: @end itemize
10921:
10922: The syntactic classes are stored internally as small integers, but are
10923: usually described to or by the user with characters. For example, @samp{(}
10924: is used to specify the syntactic class of opening delimiters. Here is a
10925: table of syntactic classes, with the characters that specify them.
10926:
10927: @table @samp
10928: @item @w{ }
10929: The class of whitespace characters.
10930: @item w
10931: The class of word-constituent characters.
10932: @item _
10933: The class of characters that are part of symbol names but not words.
10934: This class is represented by @samp{_} because the character @samp{_}
10935: has this class in both C and Lisp.
10936: @item .
10937: The class of punctuation characters that do not fit into any other
10938: special class.
10939: @item (
10940: The class of opening delimiters.
10941: @item )
10942: The class of closing delimiters.
10943: @item '
10944: The class of expression-adhering characters. These characters are
10945: part of a symbol if found within or adjacent to one, and are part
10946: of a following expression if immediately preceding one, but are like
10947: whitespace if surrounded by whitespace.
10948: @item "
10949: The class of string-quote characters. They match each other in pairs,
10950: and the characters within the pair all lose their syntactic
10951: significance except for the @samp{\} and @samp{/} classes of escape
10952: characters, which can be used to include a string-quote inside the
10953: string.
10954: @item $
10955: The class of self-matching delimiters. This is intended for @TeX{}'s
10956: @samp{$}, which is used both to enter and leave math mode. Thus,
10957: a pair of matching @samp{$} characters surround each piece of math mode
10958: @TeX{} input. A pair of adjacent @samp{$} characters act like a single
10959: one for purposes of matching
10960:
10961: @item /
10962: The class of escape characters that always just deny the following
10963: character its special syntactic significance. The character after one
10964: of these escapes is always treated as alphabetic.
10965: @item \
10966: The class of C-style escape characters. In practice, these are
10967: treated just like @samp{/}-class characters, because the extra
10968: possibilities for C escapes (such as being followed by digits) have no
10969: effect on where the containing expression ends.
10970: @item <
10971: The class of comment-starting characters. Only single-character
10972: comment starters (such as @samp{;} in Lisp mode) are represented this
10973: way.
10974: @item >
10975: The class of comment-ending characters. Newline has this syntax in
10976: Lisp mode.
10977: @end table
10978:
10979: @vindex parse-sexp-ignore-comments
10980: The characters flagged as part of two-character comment delimiters can
10981: have other syntactic functions most of the time. For example, @samp{/} and
10982: @samp{*} in C code, when found separately, have nothing to do with
10983: comments. The comment-delimiter significance overrides when the pair of
10984: characters occur together in the proper order. Only the list and sexp
10985: commands use the syntax table to find comments; the commands specifically
10986: for comments have other variables that tell them where to find comments.
10987: And the list and sexp commands notice comments only if
10988: @code{parse-sexp-ignore-comments} is non-@code{nil}. This variable is set
10989: to @code{nil} in modes where comment-terminator sequences are liable to
10990: appear where there is no comment; for example, in Lisp mode where the
10991: comment terminator is a newline but not every newline ends a comment.
10992:
10993: @findex modify-syntax-entry
10994: @kbd{M-x modify-syntax-entry} is the command to change a character's
10995: syntax. It can be used interactively, and is also the means used by major
10996: modes to initialize their own syntax tables. Its first argument is the
10997: character to change. The second argument is a string that specifies the
10998: new syntax. When called from Lisp code, there is a third, optional
10999: argument, which specifies the syntax table in which to make the change. If
11000: not supplied, or if this command is called interactively, the third
11001: argument defaults to the current buffer's syntax table.
11002:
11003: @enumerate
11004: @item
11005: The first character in the string specifies the syntactic class. It
11006: is one of the characters in the previous table.
11007:
11008: @item
11009: The second character is the matching delimiter. For a character that
11010: is not an opening or closing delimiter, this should be a space, or may
11011: be omitted if no following characters are needed.
11012:
11013: @item
11014: The remaining characters are flags. The flag characters allowed are
11015:
11016: @table @samp
11017: @item 1
11018: Flag this character as the first of a two-character comment starting sequence.
11019: @item 2
11020: Flag this character as the second of a two-character comment starting sequence.
11021: @item 3
11022: Flag this character as the first of a two-character comment ending sequence.
11023: @item 4
11024: Flag this character as the second of a two-character comment ending sequence.
11025: @end table
11026: @end enumerate
11027:
11028: @kindex C-h s
11029: @findex describe-syntax
11030: A description of the contents of the current syntax table can be
11031: displayed with @kbd{C-h s} (@code{describe-syntax}). The description of
11032: each character includes both the string you would have to give to
11033: @code{modify-syntax-entry} to set up that character's current syntax, and
11034: some English to explain that string if necessary.
11035:
11036: @node Init File,, Syntax, Customization
11037: @section The Init File, .emacs
11038: @cindex init file
11039:
11040: When Emacs is started, it normally loads the file @file{.emacs} in your
11041: home directory. This file, if it exists, should contain Lisp code.
11042: Here we describe how to do certain common things in the @file{.emacs} file.
11043:
11044: The @file{.emacs} file contains one or more Lisp function call
11045: expressions. Each of these consists of a function name followed by
11046: arguments, all surrounded by parentheses. For example, @code{(setq
11047: default-fill-column 60)} represents a call to the function @code{setq}
11048: which is used to set the variable @code{default-fill-column}
11049: (@pxref{Filling}) to 60.
11050:
11051: The second argument to @code{setq} is an expression for the new value of
11052: the variable. This can be a constant, a variable, or a function call
11053: expression. In @file{.emacs}, constants are used most of the time. They can be:
11054:
11055: @table @asis
11056: @item Numbers:
11057: Numbers are written in decimal, with an optional initial minus sign.
11058: @item Strings:
11059: Lisp string syntax is the same as C string syntax with a few extra
11060: features. First, newlines and any other characters may be present
11061: literally in strings. Second, @samp{\e} may be used to stand for the
11062: character @key{ESC}. Third, @samp{\C-} can be used as a prefix for a
11063: control character, as in @samp{\C-s} for ASCII Control-S, and
11064: @samp{\M-} can be used as a prefix for a meta character, as in
11065: @samp{\M-a} for Meta-A or @samp{\M-\C-a} for Control-Meta-A.@refill
11066: @item Characters:
11067: Lisp character constant syntax consists of a @samp{?} followed by
11068: either a character or an escape sequence starting with @samp{\}.
11069: Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
11070: strings and characters are not interchangeable in Lisp; some contexts
11071: require one and some contexts require the other.
11072: @item True:
11073: @code{t} stands for `true'.
11074: @item False:
11075: @code{nil} stands for `false'.
11076: @item Other Lisp objects:
11077: Write a single-quote (') followed by the Lisp object you want.
11078: @end table
11079:
11080: Here are some examples of doing certain commonly desired things with
11081: Lisp expressions:
11082:
11083: @itemize @bullet
11084: @item
11085: Make searches case sensitive:
11086:
11087: @example
11088: (setq default-case-fold-search nil)
11089: @end example
11090:
11091: Here we have a variable whose value is normally @code{t} for `true'
11092: and the alternative is @code{nil} for `false'.
11093:
11094: @item
11095: Make Text mode the default mode for new buffers:
11096:
11097: @example
11098: (setq default-major-mode 'text-mode)
11099: @end example
11100:
11101: Note that @code{text-mode} is used because it is the command for entering
11102: the mode we want. A single-quote is written before it to make a symbol
11103: constant; otherwise, @code{text-mode} would be treated as a variable name.
11104:
11105: @item
11106: Turn on Auto Fill mode automatically in Text mode and related modes:
11107:
11108: @example
11109: (setq text-mode-hook
11110: '(lambda () (auto-fill-mode 1)))
11111: @end example
11112:
11113: Here we have a variable whose value should be a Lisp function. The
11114: function we supply is a list starting with @code{lambda}, and a single
11115: quote is written in front of it to make it (for the purpose of this
11116: @code{setq}) a list constant rather than an expression. Lisp functions
11117: are not explained here, but for mode hooks it is enough to know that
11118: @code{(auto-fill-mode 1)} is an expression that will be executed when
11119: Text mode is entered, and you could replace it with any other expression
11120: that you like, or with several expressions in a row.
11121:
11122: @example
11123: (setq text-mode-hook 'turn-on-auto-fill)
11124: @end example
11125:
11126: This is another way to accomplish the same result.
11127: @code{turn-on-auto-fill} is a symbol whose function definition is
11128: @code{(lambda () (auto-fill-mode 1))}.
11129:
11130: @item
11131: Load the compiled Lisp file @file{foo.elc}.
11132:
11133: @example
11134: (load "foo")
11135: @end example
11136:
11137: @item
11138: Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
11139:
11140: @example
11141: (global-set-key "\C-xl" 'make-symbolic-link)
11142: @end example
11143:
11144: Note once again the single-quote used to refer to the symbol
11145: @code{make-symbolic-link} instead of its value as a variable.
11146:
11147: @item
11148: Do the same thing for C mode only.
11149:
11150: @example
11151: (define-key c-mode-map "\C-xl" 'make-symbolic-link)
11152: @end example
11153:
11154: @item
11155: Make @kbd{C-x p} undefined.
11156:
11157: @example
11158: (global-unset-key "\C-xp")
11159: @end example
11160:
11161: One reason to undefine a key is so that you can make it a prefix.
11162: Simply defining @kbd{C-x p @var{anything}} would make @kbd{C-x p}
11163: a prefix, provided it is not otherwise defined.
11164:
11165: @item
11166: Make @samp{$} have the syntax of punctuation in Text mode.
11167: Note the use of a character constant for @samp{$}.
11168:
11169: @example
11170: (modify-syntax-entry ?\$ "." text-mode-syntax-table)
11171: @end example
11172:
11173: @item
11174: Enable the use of the command @code{eval-expression} without confirmation.
11175:
11176: @example
11177: (put 'eval-expression 'disabled nil)
11178: @end example
11179: @end itemize
11180:
11181: @iftex
11182: @chapter Correcting Mistakes (Yours or Emacs's)
11183:
11184: If you type an Emacs command you did not intend, the results are often
11185: mysterious. This chapter tells what you can do to cancel your mistake or
11186: recover from a mysterious situation. Emacs bugs and system crashes are
11187: also considered.
11188: @end iftex
11189:
11190: @node Quitting, Lossage, Customization, Top
11191: @section Quitting and Aborting
11192: @cindex quitting
11193:
11194: @table @kbd
11195: @item C-g
11196: Quit. Cancel running or partially typed command.
11197: @item C-]
11198: Abort recursive editing level and cancel the command which invoked it
11199: (@code{abort-recursive-edit}).
11200: @item M-x top-level
11201: Abort all recursive editing levels that are currently executing.
11202: @item C-x u
11203: Cancel an already-executed command, usually (@code{undo}).
11204: @end table
11205:
11206: There are two ways of cancelling commands which are not finished
11207: executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]}
11208: or @kbd{M-x top-level}. Quitting is cancelling a partially typed command
11209: or one which is already running. Aborting is getting out of a recursive
11210: editing level and cancelling the command that invoked the recursive edit.
11211:
11212: @cindex quitting
11213: @cindex C-g
11214: Quitting with @kbd{C-g} is used for getting rid of a partially typed
11215: command, or a numeric argument that you don't want. It also stops a
11216: running command in the middle in a relatively safe way, so you can use it
11217: if you accidentally give a command which takes a long time. In particular,
11218: it is safe to quit out of killing; either your text will @var{all} still be
11219: there, or it will @var{all} be in the kill ring (or maybe both). Quitting
11220: an incremental search does special things documented under searching; in
11221: general, it may take two successive @kbd{C-g} characters to get out of a
11222: search. @kbd{C-g} works by setting the variable @code{quit-flag} to
11223: @code{t} the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
11224: frequently and quits if it is non-@code{nil}. @kbd{C-g} is only actually
11225: executed as a command if it is typed while Emacs is waiting for input.
11226:
11227: If you quit twice in a row before the first @kbd{C-g} is recognized, you
11228: activate the ``emergency escape'' feature and return to the shell.
11229: @xref{Emergency Escape}.
11230:
11231: @cindex recursive editing level
11232: @cindex aborting
11233: @findex abort-recursive-edit
11234: @kindex C-]
11235: Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get out
11236: of a recursive editing level and cancel the command which invoked it.
11237: Quitting with @kbd{C-g} does not do this, and could not do this, because it
11238: is used to cancel a partially typed command @i{within} the recursive
11239: editing level. Both operations are useful. For example, if you are in the
11240: Emacs debugger (@pxref{Lisp Debug}) and have typed @kbd{C-u 8} to enter a
11241: numeric argument, you can cancel that argument with @kbd{C-g} and remain in
11242: the debugger.
11243:
11244: @findex top-level
11245: The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
11246: commands to get you out of all the levels of subsystems and recursive edits
11247: that you are in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x
11248: top-level} goes out all levels at once. Both @kbd{C-]} and @kbd{M-x
11249: top-level} are like all other commands, and unlike @kbd{C-g}, in that they
11250: are effective only when Emacs is ready for a command. @kbd{C-]} is an
11251: ordinary key and has its meaning only because of its binding in the keymap.
11252:
11253: @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelling
11254: a command, but you can think of it as cancelling a command already finished
11255: executing. @xref{Undo}.
11256:
11257: @node Lossage, Bugs, Quitting, Top
11258: @section Dealing with Emacs Trouble
11259:
11260: This section describes various conditions in which Emacs fails to work,
11261: and how to recognize them and correct them.
11262:
11263: @menu
11264: * Stuck Recursive:: `[...]' in mode line around the parentheses
11265: * Screen Garbled:: Garbage on the screen
11266: * Text Garbled:: Garbage in the text
11267: * Unasked-for Search:: Spontaneous entry to incremental search
11268: * Emergency Escape:: Emergency escape---
11269: What to do if Emacs stops responding
11270: * Total Frustration:: When you are at your wits' end.
11271: @end menu
11272:
11273: @node Stuck Recursive, Screen Garbled, Lossage, Lossage
11274: @subsection Recursive Editing Levels
11275:
11276: Recursive editing levels are important and useful features of Emacs, but
11277: they can seem like malfunctions to the user who does not understand them.
11278:
11279: If the mode line has square brackets @samp{[@dots{}]} around the parentheses
11280: that contain the names of the major and minor modes, you have entered a
11281: recursive editing level. If you did not do this on purpose, or if you
11282: don't understand what that means, you should just get out of the recursive
11283: editing level. To do so, type @kbd{M-x top-level}. This is called getting
11284: back to top level. @xref{Recursive Edit}.
11285:
11286: @node Screen Garbled, Text Garbled, Stuck Recursive, Lossage
11287: @subsection Garbage on the Screen
11288:
11289: If the data on the screen looks wrong, the first thing to do is see
11290: whether the text is really wrong. Type @kbd{C-l}, to redisplay the entire
11291: screen. If it appears correct after this, the problem was entirely in the
11292: previous screen update.
11293:
11294: Display updating problems often result from an incorrect termcap entry
11295: for the terminal you are using. The file @file{etc/TERMS} gives the fixes
11296: for known problems of this sort. @file{INSTALL} contains general advice
11297: for these problems in one of its sections. Very likely there is simply
11298: insufficient padding for certain display operations. To investigate the
11299: possibility that you have this sort of problem, try Emacs on another
11300: terminal made by a different manufacturer. If problems happen frequently
11301: on one kind of terminal but not another kind, it is likely to be a bad
11302: termcap entry, though it could also be due to a bug in Emacs that appears
11303: for terminals that have or that lack specific features.
11304:
11305: @node Text Garbled, Unasked-for Search, Screen Garbled, Lossage
11306: @subsection Garbage in the Text
11307:
11308: If @kbd{C-l} shows that the text is wrong, try undoing the changes to it
11309: using @kbd{C-x u} until it gets back to a state you consider correct. Also
11310: try @kbd{C-h l} to find out what command you typed to produce the observed
11311: results.
11312:
11313: If a large portion of text appears to be missing at the beginning or
11314: end of the buffer, check for the word @samp{Narrow} in the mode line.
11315: If it appears, the text is still present, but marked off-limits.
11316: To make it visible again, type @kbd{C-x w}. @xref{Narrowing}.
11317:
11318: @node Unasked-for Search, Emergency Escape, Text Garbled, Lossage
11319: @subsection Spontaneous Entry to Incremental Search
11320:
11321: If Emacs spontaneously displays @samp{I-search:} at the bottom of the
11322: screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q}
11323: according to the badly designed xon/xoff ``flow control'' protocol. You
11324: should try to prevent this by putting the terminal in a mode where it will
11325: not use flow control or giving it enough padding that it will never send a
11326: @kbd{C-s}. If that cannot be done, you must tell Emacs to expect flow
11327: control to be used, until you can get a properly designed terminal.
11328:
11329: Information on how to do these things can be found in the file
11330: @file{INSTALL} in the Emacs distribution.
11331:
11332: @node Emergency Escape, Total Frustration, Unasked-for Search, Lossage
11333: @subsection Emergency Escape
11334:
11335: Because at times there have been bugs causing Emacs to loop without
11336: checking @code{quit-flag}, a special feature causes Emacs to be suspended
11337: immediately if you type a second @kbd{C-g} while the flag is already set.
11338: So you can always get out of GNU Emacs. Normally Emacs recognizes and
11339: clears @code{quit-flag} (and quits!) quickly enough to prevent this from
11340: happening.
11341:
11342: When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it
11343: asks two questions before going back to what it had been doing:
11344:
11345: @example
11346: Checkpoint?
11347: Abort (and dump core)?
11348: @end example
11349:
11350: @noindent
11351: Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.
11352:
11353: Saying @kbd{y} to @samp{Checkpoint?} causes immediate auto-saving of all
11354: modified buffers in which auto-saving is enabled.
11355:
11356: Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be
11357: executed, dumping core. This is to enable a wizard to figure out why Emacs
11358: was failing to quit in the first place. Execution does not continue
11359: after a core dump. If you answer @kbd{n}, execution does continue. With
11360: luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally.
11361: If not, and you type another @kbd{C-g}, it is suspended again.
11362:
11363: If Emacs is not really hung, just slow, you may invoke the double
11364: @kbd{C-g} feature without really meaning to. Then just resume and answer
11365: @kbd{n} to both questions, and you will arrive at your former state.
11366: Presumably the quit you requested will happen soon.
11367:
11368: @node Total Frustration,, Emergency Escape, Lossage
11369: @subsection Help for Total Frustration
11370: @cindex Eliza
11371: @cindex doctor
11372:
11373: If using Emacs (or something else) becomes terribly frustrating and none
11374: of the techniques described above solve the problem, Emacs can still help
11375: you.
11376:
11377: First, if the Emacs you are using is not responding to commands, type
11378: @kbd{C-g C-g} to get out of it and then start a new one.
11379:
11380: @findex doctor
11381: Second, type @kbd{M-x doctor @key{RET}}.
11382:
11383: The doctor will make you feel better. Each time you say something to
11384: the doctor, you must end it by typing @key{RET} @key{RET}. This lets the
11385: doctor know you are finished.
11386:
11387: @node Bugs, Manifesto, Lossage, Top
11388: @section Reporting Bugs
11389:
11390: @cindex bugs
11391: Sometimes you will encounter a bug in Emacs. Although we cannot promise
11392: we can or will fix the bug, and we might not even agree that it is a bug,
11393: we want to hear about bugs you encounter in case we do want to fix them.
11394:
11395: To make it possible for us to fix a bug, you must report it. In order
11396: to do so effectively, you must know when and how to do it.
11397:
11398: @subsection When Is There a Bug
11399:
11400: If Emacs executes an illegal instruction, or dies with an operating
11401: system error message that indicates a problem in the program (as opposed to
11402: something like ``disk full''), then it is certainly a bug.
11403:
11404: If Emacs updates the display in a way that does not correspond to what is
11405: in the buffer, then it is certainly a bug. If a command seems to do the
11406: wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
11407: case of incorrect display updating.
11408:
11409: Taking forever to complete a command can be a bug, but you must make
11410: certain that it was really Emacs's fault. Some commands simply take a long
11411: time. Type @kbd{C-g} and then @kbd{C-h l} to see whether the input Emacs
11412: received was what you intended to type; if the input was such that you
11413: @var{know} it should have been processed quickly, report a bug. If you
11414: don't know whether the command should take a long time, find out by looking
11415: in the manual or by asking for assistance.
11416:
11417: If a command you are familiar with causes an Emacs error message in a
11418: case where its usual definition ought to be reasonable, it is probably a
11419: bug.
11420:
11421: If a command does the wrong thing, that is a bug. But be sure you know
11422: for certain what it ought to have done. If you aren't familiar with the
11423: command, or don't know for certain how the command is supposed to work,
11424: then it might actually be working right. Rather than jumping to
11425: conclusions, show the problem to someone who knows for certain.
11426:
11427: Finally, a command's intended definition may not be best for editing
11428: with. This is a very important sort of problem, but it is also a matter of
11429: judgment. Also, it is easy to come to such a conclusion out of ignorance
11430: of some of the existing features. It is probably best not to complain
11431: about such a problem until you have checked the documentation in the usual
11432: ways, feel confident that you understand it, and know for certain that what
11433: you want is not available. If you are not sure what the command is
11434: supposed to do after a careful reading of the manual, check the index and
11435: glossary for any terms that may be unclear. If you still do not
11436: understand, this indicates a bug in the manual. The manual's job is to
11437: make everything clear. It is just as important to report documentation
11438: bugs as program bugs.
11439:
11440: If the on-line documentation string of a function or variable disagrees
11441: with the manual, one of them must be wrong, so report the bug.
11442:
11443: @subsection How to Report a Bug
11444:
11445: @findex emacs-version
11446: When you decide that there is a bug, it is important to report it and to
11447: report it in a way which is useful. What is most useful is an exact
11448: description of what commands you type, starting with the shell command to
11449: run Emacs, until the problem happens. Always include the version number
11450: of Emacs that you are using; type @kbd{M-x emacs-version} to print this.
11451:
11452: The most important principle in reporting a bug is to report @var{facts},
11453: not hypotheses or categorizations. It is always easier to report the facts,
11454: but people seem to prefer to strain to posit explanations and report
11455: them instead. If the explanations are based on guesses about how Emacs is
11456: implemented, they will be useless; we will have to try to figure out what
11457: the facts must have been to lead to such speculations. Sometimes this is
11458: impossible. But in any case, it is unnecessary work for us.
11459:
11460: For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
11461: @key{RET}}, visiting a file which (you know) happens to be rather large,
11462: and Emacs prints out @samp{I feel pretty today}. The best way to report
11463: the bug is with a sentence like the preceding one, because it gives all the
11464: facts and nothing but the facts.
11465:
11466: Do not assume that the problem is due to the size of the file and say,
11467: ``When I visit a large file, Emacs prints out @samp{I feel pretty today}.''
11468: This is what we mean by ``guessing explanations''. The problem is just as
11469: likely to be due to the fact that there is a @code{z} in the file name. If
11470: this is so, then when we got your report, we would try out the problem with
11471: some ``large file'', probably with no @code{z} in its name, and not find
11472: anything wrong. There is no way in the world that we could guess that we
11473: should try visiting a file with a @code{z} in its name.
11474:
11475: Alternatively, the problem might be due to the fact that the file starts
11476: with exactly 25 spaces. For this reason, you should make sure that you
11477: inform us of the exact contents of any file that is needed to reproduce the
11478: bug. What if the problem only occurs when you have typed the @kbd{C-x C-a}
11479: command previously? This is why we ask you to give the exact sequence of
11480: characters you typed since starting to use Emacs.
11481:
11482: You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
11483: you @i{know} that it makes no difference which visiting command is used.
11484: Similarly, rather than saying ``if I have three characters on the line,''
11485: say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is
11486: the way you entered the text.@refill
11487:
11488: If you are not in Fundamental mode when the problem occurs, you should
11489: say what mode you are in.
11490:
11491: If the manifestation of the bug is an Emacs error message, it is
11492: important to report not just the text of the error message but a backtrace
11493: showing how the Lisp program in Emacs arrived at the error. To make the
11494: backtrace, you must execute the Lisp expression @code{(setq debug-on-error@ t)}
11495: before the error happens (that is to say, you must execute that expression
11496: and then make the bug happen). This causes the Lisp debugger to run
11497: (@pxref{Lisp Debug}). The debugger's backtrace can be copied as text into
11498: the bug report. This use of the debugger is possible only if you know how
11499: to make the bug happen again. Do note the error message the first time the
11500: bug happens, so if you can't make it happen again, you can report at least
11501: that.
11502:
11503: Check whether any programs you have loaded into the Lisp world, including
11504: your @file{.emacs} file, set any variables that may affect the functioning
11505: of Emacs. Also, see whether the problem happens in a freshly started Emacs
11506: without loading your @file{.emacs} file (start Emacs with the @code{-q} switch
11507: to prevent loading the init file.) If the problem does @var{not} occur
11508: then, it is essential that we know the contents of any programs that you
11509: must load into the Lisp world in order to cause the problem to occur.
11510:
11511: If the problem does depend on an init file or other Lisp programs that
11512: are not part of the standard Emacs system, then you should make sure it is
11513: not a bug in those programs by complaining to their maintainers, first.
11514: After they verify that they are using Emacs in a way that is supposed to
11515: work, they should report the bug.
11516:
11517: If you can tell us a way to cause the problem without visiting any files,
11518: please do so. This makes it much easier to debug. If you do need files,
11519: make sure you arrange for us to see their exact contents. For example, it
11520: can often matter whether there are spaces at the ends of lines, or a
11521: newline after the last line in the buffer (nothing ought to care whether
11522: the last line is terminated, but tell that to the bugs).
11523:
11524: @findex open-dribble-file
11525: @cindex dribble file
11526: The easy way to record the input to Emacs precisely is to to write a
11527: dribble file; execute the Lisp expression
11528:
11529: @example
11530: (open-dribble-file "~/dribble")
11531: @end example
11532:
11533: @noindent
11534: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting
11535: Emacs. From then on, all Emacs input will be written in the specified
11536: dribble file until the Emacs process is killed.
11537:
11538: @findex open-termscript
11539: @cindex termcript file
11540: For possible display bugs, it is important to report the terminal type
11541: (the value of environment variable @code{TERM}), the termcap entry for the
11542: terminal (since @file{/etc/termcap} is not identical on all machines), and
11543: the output that Emacs actually sent to the terminal. The way to collect
11544: this output is to execute the Lisp expression
11545:
11546: @example
11547: (open-termscript "~/termscript")
11548: @end example
11549:
11550: @noindent
11551: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just
11552: after starting Emacs. From then on, all output from Emacs to the terminal
11553: will be written in the specified termscript file as well, until the Emacs
11554: process is killed. If the problem happens when Emacs starts up, put this
11555: expression into your @file{~/.emacs} file so that the termscript file will
11556: be open when Emacs displays the screen for the first time. Be warned:
11557: it is often difficult, and sometimes impossible, to fix a terminal-dependent
11558: bug without access to a terminal of the type that stimulates the bug.@refill
11559:
11560: The address for reporting bugs is
11561:
11562: @format
11563: GNU Emacs Bugs
11564: 545 Tech Sq, rm 703
11565: Cambridge, MA 02139
11566: @end format
11567:
11568: @noindent
11569: or, on Usenet, mail to @samp{mit-eddie!bug-gnu-emacs}.
11570:
11571: Once again, we do not promise to fix the bug; but if the bug is serious,
11572: or ugly, or easy to fix, chances are we will want to.
11573:
11574: @node Manifesto,, Bugs, Top
11575: @unnumbered The GNU Manifesto
11576:
11577: @unnumberedsec What's GNU? Gnu's Not Unix!
11578:
11579: GNU, which stands for Gnu's Not Unix, is the name for the complete
11580: Unix-compatible software system which I am writing so that I can give it
11581: away free to everyone who can use it. Several other volunteers are helping
11582: me. Contributions of time, money, programs and equipment are greatly
11583: needed.
11584:
11585: So far we have a portable C and Pascal compiler which compiles for Vax and
11586: 68000 (though needing much rewriting), an Emacs-like text editor with Lisp
11587: for writing editor commands, a yacc-compatible parser generator, a linker,
11588: and around 35 utilities. A shell (command interpreter) is nearly
11589: completed. When the kernel and a debugger are written, it will be possible
11590: to distribute a GNU system suitable for program development. After this we
11591: will add a text formatter, an Empire game, a spreadsheet, and hundreds of
11592: other things, plus on-line documentation. We hope to supply, eventually,
11593: everything useful that normally comes with a Unix system, and more.
11594:
11595: GNU will be able to run Unix programs, but will not be identical to Unix.
11596: We will make all improvements that are convenient, based on our experience
11597: with other operating systems. In particular, we plan to have longer
11598: filenames, file version numbers, a crashproof file system, filename
11599: completion perhaps, terminal-independent display support, and eventually a
11600: Lisp-based window system through which several Lisp programs and ordinary
11601: Unix programs can share a screen. Both C and Lisp will be available as
11602: system programming languages. We will try to support UUCP, MIT Chaosnet,
11603: and Internet protocols for communication.
11604:
11605: GNU is aimed initially at machines in the 68000/16000 class, with virtual
11606: memory, because they are the easiest machines to make it run on. The extra
11607: effort to make it run on smaller machines will be left to someone who wants
11608: to use it on them.
11609:
11610: To avoid horrible confusion, please pronounce the `G' in the word `GNU'
11611: when it is the name of this project.
11612:
11613: @unnumberedsec Why I Must Write GNU
11614:
11615: I consider that the golden rule requires that if I like a program I must
11616: share it with other people who like it. Software sellers want to divide
11617: the users and conquer them, making each user agree not to share with
11618: others. I refuse to break solidarity with other users in this way. I
11619: cannot in good conscience sign a nondisclosure agreement or a software
11620: license agreement. For years I worked within the Artificial Intelligence
11621: Lab to resist such tendencies and other inhospitalities, but eventually
11622: they had gone too far: I could not remain in an institution where such
11623: things are done for me against my will.
11624:
11625: So that I can continue to use computers without dishonor, I have decided to
11626: put together a sufficient body of free software so that I will be able to
11627: get along without any software that is not free. I have resigned from the
11628: AI lab to deny MIT any legal excuse to prevent me from giving GNU away.
11629:
11630: @unnumberedsec Why GNU Will Be Compatible with Unix
11631:
11632: Unix is not my ideal system, but it is not too bad. The essential features
11633: of Unix seem to be good ones, and I think I can fill in what Unix lacks
11634: without spoiling them. And a system compatible with Unix would be
11635: convenient for many other people to adopt.
11636:
11637: @unnumberedsec How GNU Will Be Available
11638:
11639: GNU is not in the public domain. Everyone will be permitted to modify and
11640: redistribute GNU, but no distributor will be allowed to restrict its
11641: further redistribution. That is to say, proprietary modifications will not
11642: be allowed. I want to make sure that all versions of GNU remain free.
11643:
11644: @unnumberedsec Why Many Other Programmers Want to Help
11645:
11646: I have found many other programmers who are excited about GNU and want to
11647: help.
11648:
11649: Many programmers are unhappy about the commercialization of system
11650: software. It may enable them to make more money, but it requires them to
11651: feel in conflict with other programmers in general rather than feel as
11652: comrades. The fundamental act of friendship among programmers is the
11653: sharing of programs; marketing arrangements now typically used essentially
11654: forbid programmers to treat others as friends. The purchaser of software
11655: must choose between friendship and obeying the law. Naturally, many decide
11656: that friendship is more important. But those who believe in law often do
11657: not feel at ease with either choice. They become cynical and think that
11658: programming is just a way of making money.
11659:
11660: By working on and using GNU rather than proprietary programs, we can be
11661: hospitable to everyone and obey the law. In addition, GNU serves as an
11662: example to inspire and a banner to rally others to join us in sharing.
11663: This can give us a feeling of harmony which is impossible if we use
11664: software that is not free. For about half the programmers I talk to, this
11665: is an important happiness that money cannot replace.
11666:
11667: @unnumberedsec How You Can Contribute
11668:
11669: I am asking computer manufacturers for donations of machines and money.
11670: I'm asking individuals for donations of programs and work.
11671:
11672: One consequence you can expect if you donate machines is that GNU will run
11673: on them at an early date. The machines should be complete, ready to use
11674: systems, approved for use in a residential area, and not in need of
11675: sophisticated cooling or power.
11676:
11677: I have found very many programmers eager to contribute part-time work for
11678: GNU. For most projects, such part-time distributed work would be very hard
11679: to coordinate; the independently-written parts would not work together.
11680: But for the particular task of replacing Unix, this problem is absent. A
11681: complete Unix system contains hundreds of utility programs, each of which
11682: is documented separately. Most interface specifications are fixed by Unix
11683: compatibility. If each contributor can write a compatible replacement for
11684: a single Unix utility, and make it work properly in place of the original
11685: on a Unix system, then these utilities will work right when put together.
11686: Even allowing for Murphy to create a few unexpected problems, assembling
11687: these components will be a feasible task. (The kernel will require closer
11688: communication and will be worked on by a small, tight group.)
11689:
11690: If I get donations of money, I may be able to hire a few people full or
11691: part time. The salary won't be high by programmers' standards, but I'm
11692: looking for people for whom building community spirit is as important as
11693: making money. I view this as a way of enabling dedicated people to devote
11694: their full energies to working on GNU by sparing them the need to make a
11695: living in another way.
11696:
11697: @unnumberedsec Why All Computer Users Will Benefit
11698:
11699: Once GNU is written, everyone will be able to obtain good system software
11700: free, just like air.
11701:
11702: This means much more than just saving everyone the price of a Unix license.
11703: It means that much wasteful duplication of system programming effort will
11704: be avoided. This effort can go instead into advancing the state of the
11705: art.
11706:
11707: Complete system sources will be available to everyone. As a result, a user
11708: who needs changes in the system will always be free to make them himself,
11709: or hire any available programmer or company to make them for him. Users
11710: will no longer be at the mercy of one programmer or company which owns the
11711: sources and is in sole position to make changes.
11712:
11713: Schools will be able to provide a much more educational environment by
11714: encouraging all students to study and improve the system code. Harvard's
11715: computer lab used to have the policy that no program could be installed on
11716: the system if its sources were not on public display, and upheld it by
11717: actually refusing to install certain programs. I was very much inspired by
11718: this.
11719:
11720: Finally, the overhead of considering who owns the system software and what
11721: one is or is not entitled to do with it will be lifted.
11722:
11723: Arrangements to make people pay for using a program, including licensing of
11724: copies, always incur a tremendous cost to society through the cumbersome
11725: mechanisms necessary to figure out how much (that is, which programs) a
11726: person must pay for. And only a police state can force everyone to obey
11727: them. Consider a space station where air must be manufactured at great
11728: cost: charging each breather per liter of air may be fair, but wearing the
11729: metered gas mask all day and all night is intolerable even if everyone can
11730: afford to pay the air bill. And the TV cameras everywhere to see if you
11731: ever take the mask off are outrageous. It's better to support the air
11732: plant with a head tax and chuck the masks.
11733:
11734: Copying all or parts of a program is as natural to a programmer as
11735: breathing, and as productive. It ought to be as free.
11736:
11737: @unnumberedsec Some Easily Rebutted Objections to GNU's Goals
11738:
11739: @quotation
11740: ``Nobody will use it if it is free, because that means they can't rely
11741: on any support.''
11742:
11743: ``You have to charge for the program to pay for providing the
11744: support.''
11745: @end quotation
11746:
11747: If people would rather pay for GNU plus service than get GNU free without
11748: service, a company to provide just service to people who have obtained GNU
11749: free ought to be profitable.
11750:
11751: We must distinguish between support in the form of real programming work
11752: and mere handholding. The former is something one cannot rely on from a
11753: software vendor. If your problem is not shared by enough people, the
11754: vendor will tell you to get lost.
11755:
11756: If your business needs to be able to rely on support, the only way is to
11757: have all the necessary sources and tools. Then you can hire any available
11758: person to fix your problem; you are not at the mercy of any individual.
11759: With Unix, the price of sources puts this out of consideration for most
11760: businesses. With GNU this will be easy. It is still possible for there to
11761: be no available competent person, but this problem cannot be blamed on
11762: distibution arrangements. GNU does not eliminate all the world's problems,
11763: only some of them.
11764:
11765: Meanwhile, the users who know nothing about computers need handholding:
11766: doing things for them which they could easily do themselves but don't know
11767: how.
11768:
11769: Such services could be provided by companies that sell just hand-holding
11770: and repair service. If it is true that users would rather spend money and
11771: get a product with service, they will also be willing to buy the service
11772: having got the product free. The service companies will compete in quality
11773: and price; users will not be tied to any particular one. Meanwhile, those
11774: of us who don't need the service should be able to use the program without
11775: paying for the service.
11776:
11777: @quotation
11778: ``You cannot reach many people without advertising,
11779: and you must charge for the program to support that.''
11780:
11781: ``It's no use advertising a program people can get free.''
11782: @end quotation
11783:
11784: There are various forms of free or very cheap publicity that can be used to
11785: inform numbers of computer users about something like GNU. But it may be
11786: true that one can reach more microcomputer users with advertising. If this
11787: is really so, a business which advertises the service of copying and
11788: mailing GNU for a fee ought to be successful enough to pay for its
11789: advertising and more. This way, only the users who benefit from the
11790: advertising pay for it.
11791:
11792: On the other hand, if many people get GNU from their friends, and such
11793: companies don't succeed, this will show that advertising was not really
11794: necessary to spread GNU. Why is it that free market advocates don't want
11795: to let the free market decide this?
11796:
11797: @quotation
11798: ``My company needs a proprietary operating system
11799: to get a competitive edge.''
11800: @end quotation
11801:
11802: GNU will remove operating system software from the realm of competition.
11803: You will not be able to get an edge in this area, but neither will your
11804: competitors be able to get an edge over you. You and they will compete in
11805: other areas, while benefitting mutually in this one. If your business is
11806: selling an operating system, you will not like GNU, but that's tough on
11807: you. If your business is something else, GNU can save you from being
11808: pushed into the expensive business of selling operating systems.
11809:
11810: I would like to see GNU development supported by gifts from many
11811: manufacturers and users, reducing the cost to each.
11812:
11813: @quotation
11814: ``Don't programmers deserve a reward for their creativity?''
11815: @end quotation
11816:
11817: If anything deserves a reward, it is social contribution. Creativity can
11818: be a social contribution, but only in so far as society is free to use the
11819: results. If programmers deserve to be rewarded for creating innovative
11820: programs, by the same token they deserve to be punished if they restrict
11821: the use of these programs.
11822:
11823: @quotation
11824: ``Shouldn't a programmer be able to ask for a reward for his creativity?''
11825: @end quotation
11826:
11827: There is nothing wrong with wanting pay for work, or seeking to maximize
11828: one's income, as long as one does not use means that are destructive. But
11829: the means customary in the field of software today are based on
11830: destruction.
11831:
11832: Extracting money from users of a program by restricting their use of it is
11833: destructive because the restrictions reduce the amount and the ways that
11834: the program can be used. This reduces the amount of wealth that humanity
11835: derives from the program. When there is a deliberate choice to restrict,
11836: the harmful consequences are deliberate destruction.
11837:
11838: The reason a good citizen does not use such destructive means to become
11839: wealthier is that, if everyone did so, we would all become poorer from the
11840: mutual destructiveness. This is Kantian ethics; or, the Golden Rule.
11841: Since I do not like the consequences that result if everyone hoards
11842: information, I am required to consider it wrong for one to do so.
11843: Specifically, the desire to be rewarded for one's creativity does not
11844: justify depriving the world in general of all or part of that creativity.
11845:
11846: @quotation
11847: ``Won't programmers starve?''
11848: @end quotation
11849:
11850: I could answer that nobody is forced to be a programmer. Most of us cannot
11851: manage to get any money for standing on the street and making faces. But
11852: we are not, as a result, condemned to spend our lives standing on the
11853: street making faces, and starving. We do something else.
11854:
11855: But that is the wrong answer because it accepts the questioner's implicit
11856: assumption: that without ownership of software, programmers cannot possibly
11857: be paid a cent. Supposedly it is all or nothing.
11858:
11859: The real reason programmers will not starve is that it will still be
11860: possible for them to get paid for programming; just not paid as much as
11861: now.
11862:
11863: Restricting copying is not the only basis for business in software. It is
11864: the most common basis because it brings in the most money. If it were
11865: prohibited, or rejected by the customer, software business would move to
11866: other bases of organization which are now used less often. There are
11867: always numerous ways to organize any kind of business.
11868:
11869: Probably programming will not be as lucrative on the new basis as it is
11870: now. But that is not an argument against the change. It is not considered
11871: an injustice that sales clerks make the salaries that they now do. If
11872: programmers made the same, that would not be an injustice either. (In
11873: practice they would still make considerably more than that.)
11874:
11875: @quotation
11876: ``Don't people have a right to control how their creativity is used?''
11877: @end quotation
11878:
11879: ``Control over the use of one's ideas'' really constitutes control over
11880: other people's lives; and it is usually used to make their lives more
11881: difficult.
11882:
11883: People who have studied the issue of intellectual property rights carefully
11884: (such as lawyers) say that there is no intrinsic right to intellectual
11885: property. The kinds of supposed intellectual property rights that the
11886: government recognizes were created by specific acts of legislation for
11887: specific purposes.
11888:
11889: For example, the patent system was established to encourage inventors to
11890: disclose the details of their inventions. Its purpose was to help society
11891: rather than to help inventors. At the time, the life span of 17 years for
11892: a patent was short compared with the rate of advance of the state of the
11893: art. Since patents are an issue only among manufacturers, for whom the
11894: cost and effort of a license agreement are small compared with setting up
11895: production, the patents often do not do much harm. They do not obstruct
11896: most individuals who use patented products.
11897:
11898: The idea of copyright did not exist in ancient times, when authors
11899: frequently copied other authors at length in works of non-fiction. This
11900: practice was useful, and is the only way many authors' works have survived
11901: even in part. The copyright system was created expressly for the purpose
11902: of encouraging authorship. In the domain for which it was
11903: invented---books, which could be copied economically only on a printing
11904: press---it did little harm, and did not obstruct most of the individuals
11905: who read the books.
11906:
11907: All intellectual property rights are just licenses granted by society
11908: because it was thought, rightly or wrongly, that society as a whole would
11909: benefit by granting them. But in any particular situation, we have to ask:
11910: are we really better off granting such license? What kind of act are we
11911: licensing a person to do?
11912:
11913: The case of programs today is very different from that of books a hundred
11914: years ago. The fact that the easiest way to copy a program is from one
11915: neighbor to another, the fact that a program has both source code and
11916: object code which are distinct, and the fact that a program is used rather
11917: than read and enjoyed, combine to create a situation in which a person who
11918: enforces a copyright is harming society as a whole both materially and
11919: spiritually; in which a person should not do so regardless of whether the
11920: law enables him to.
11921:
11922: @quotation
11923: ``Competition makes things get done better.''
11924: @end quotation
11925:
11926: The paradigm of competition is a race: by rewarding the winner, we
11927: encourage everyone to run faster. When capitalism really works this way,
11928: it does a good job; but its defenders are wrong in assuming it always works
11929: this way. If the runners forget why the reward is offered and become
11930: intent on winning, no matter how, they may find other strategies---such as,
11931: attacking other runners. If the runners get into a fist fight, they will
11932: all finish late.
11933:
11934: Proprietary and secret software is the moral equivalent of runners in a
11935: fist fight. Sad to say, the only referee we've got does not seem to
11936: object to fights; he just regulates them (``For every ten yards you run,
11937: you can fire one shot''). He really ought to break them up, and penalize
11938: runners for even trying to fight.
11939:
11940: @quotation
11941: ``Won't everyone stop programming without a monetary incentive?''
11942: @end quotation
11943:
11944: Actually, many people will program with absolutely no monetary incentive.
11945: Programming has an irresistible fascination for some people, usually the
11946: people who are best at it. There is no shortage of professional musicians
11947: who keep at it even though they have no hope of making a living that way.
11948:
11949: But really this question, though commonly asked, is not appropriate to the
11950: situation. Pay for programmers will not disappear, only become less. So
11951: the right question is, will anyone program with a reduced monetary
11952: incentive? My experience shows that they will.
11953:
11954: For more than ten years, many of the world's best programmers worked at the
11955: Artificial Intelligence Lab for far less money than they could have had
11956: anywhere else. They got many kinds of non-monetary rewards: fame and
11957: appreciation, for example. And creativity is also fun, a reward in itself.
11958:
11959: Then most of them left when offered a chance to do the same interesting
11960: work for a lot of money.
11961:
11962: What the facts show is that people will program for reasons other than
11963: riches; but if given a chance to make a lot of money as well, they will
11964: come to expect and demand it. Low-paying organizations do poorly in
11965: competition with high-paying ones, but they do not have to do badly if the
11966: high-paying ones are banned.
11967:
11968: @quotation
11969: ``We need the programmers desperately. If they demand that we
11970: stop helping our neighbors, we have to obey.''
11971: @end quotation
11972:
11973: You're never so desperate that you have to obey this sort of demand.
11974: Remember: millions for defense, but not a cent for tribute!
11975:
11976: @quotation
11977: ``Programmers need to make a living somehow.''
11978: @end quotation
11979:
11980: In the short run, this is true. However, there are plenty of ways that
11981: programmers could make a living without selling the right to use a program.
11982: This way is customary now because it brings programmers and businessmen the
11983: most money, not because it is the only way to make a living. It is easy to
11984: find other ways if you want to find them. Here are a number of examples.
11985:
11986: A manufacturer introducing a new computer will pay for the porting of
11987: operating systems onto the new hardware.
11988:
11989: The sale of teaching, hand-holding and maintenance services could also
11990: employ programmers.
11991:
11992: People with new ideas could distribute programs as freeware, asking for
11993: donations from satisfied users, or selling hand-holding services. I have
11994: met people who are already working this way successfully.
11995:
11996: Users with related needs can form users' groups, and pay dues. A group
11997: would contract with programming companies to write programs that the
11998: group's members would like to use.
11999:
12000: All sorts of development can be funded with a Software Tax:
12001:
12002: @quotation
12003: Suppose everyone who buys a computer has to pay x percent of
12004: the price as a software tax. The government gives this to
12005: an agency like the NSF to spend on software development.
12006:
12007: But if the computer buyer makes a donation to software development
12008: himself, he can take a credit against the tax. He can donate to
12009: the project of his own choosing---often, chosen because he hopes to
12010: use the results when it is done. He can take a credit for any amount
12011: of donation up to the total tax he had to pay.
12012:
12013: The total tax rate could be decided by a vote of the payers of
12014: the tax, weighted according to the amount they will be taxed on.
12015:
12016: The consequences:
12017:
12018: @itemize @bullet
12019: @item
12020: The computer-using community supports software development.
12021: @item
12022: This community decides what level of support is needed.
12023: @item
12024: Users who care which projects their share is spent on
12025: can choose this for themselves.
12026: @end itemize
12027: @end quotation
12028:
12029: In the long run, making programs free is a step toward the post-scarcity
12030: world, where nobody will have to work very hard just to make a living.
12031: People will be free to devote themselves to activities that are fun, such
12032: as programming, after spending the necessary ten hours a week on required
12033: tasks such as legislation, family counseling, robot repair and asteroid
12034: prospecting. There will be no need to be able to make a living from
12035: programming.
12036:
12037: We have already greatly reduced the amount of work that the whole society
12038: must do for its actual productivity, but only a little of this has
12039: translated itself into leisure for workers because much nonproductive
12040: activity is required to accompany productive activity. The main causes of
12041: this are bureaucracy and isometric struggles against competition. Free
12042: software will greatly reduce these drains in the area of software
12043: production. We must do this, in order for technical gains in productivity
12044: to translate into less work for us.
12045:
12046: @node Glossary, Key Index, Intro, Top
12047: @unnumbered Glossary
12048:
12049: @table @asis
12050: @item Abbrev
12051: An abbrev is a text string which expands into a different text string
12052: when present in the buffer. For example, you might define a short
12053: word as an abbrev for a long phrase that you want to insert
12054: frequently. @xref{Abbrevs}.
12055:
12056: @item Aborting
12057: Aborting means getting out of a recursive edit (q.v.@:). The
12058: commands @kbd{C-]} and @kbd{M-x top-level} are used for this.
12059: @xref{Quitting}.
12060:
12061: @item Auto Fill mode
12062: Auto Fill mode is a minor mode in which text that you insert is
12063: automatically broken into lines of fixed width. @xref{Filling}.
12064:
12065: @item Balance Parentheses
12066: Emacs can balance parentheses manually or automatically. Manual
12067: balancing is done by the commands to move over balanced expressions
12068: (@pxref{Lists}). Automatic balancing is done by blinking the
12069: parenthesis that matches one just inserted (@pxref{Matching,,Matching
12070: Parens}).
12071:
12072: @item Bind
12073: To bind a key is to change its binding (q.v.@:). @xref{Rebinding}.
12074:
12075: @item Binding
12076: A key gets its meaning in Emacs by having a binding which is a
12077: command (q.v.@:), a Lisp function that is run when the key is typed.
12078: @xref{Commands,Binding}. Customization often involves rebinding a
12079: character to a different command function. The bindings of all keys
12080: are recorded in the keymaps (q.v.@:). @xref{Keymaps}.
12081:
12082: @item Blank Lines
12083: Blank lines are lines that contain only whitespace. Emacs has several
12084: commands for operating on the blank lines in the buffer.
12085:
12086: @item Buffer
12087: The buffer is the basic editing unit; one buffer corresponds to one
12088: piece of text being edited. You can have several buffers, but at any
12089: time you are editing only one, the `selected' buffer, though several
12090: can be visible when you are using multiple windows. @xref{Buffers}.
12091:
12092: @item Buffer Selection History
12093: Emacs keeps a buffer selection history which records how recently each
12094: Emacs buffer has been selected. This is used for choosing a buffer to
12095: select. @xref{Buffers}.
12096:
12097: @item C-
12098: @samp{C} in the name of a character is an abbreviation for Control.
12099: @xref{Characters,C-}.
12100:
12101: @item C-M-
12102: @samp{C-M-} in the name of a character is an abbreviation for
12103: Control-Meta. @xref{Characters,C-M-}.
12104:
12105: @item Case Conversion
12106: Case conversion means changing text from upper case to lower case or
12107: vice versa. @xref{Case}, for the commands for case conversion.
12108:
12109: @item Characters
12110: Characters form the contents of an Emacs buffer; also, Emacs commands
12111: are invoked by keys (q.v.@:), which are sequences of one or more
12112: characters. @xref{Characters}.
12113:
12114: @item Command
12115: A command is a Lisp function specially defined to be able to serve as
12116: a key binding in Emacs. When you type a key (q.v.@:), its binding
12117: (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find the
12118: command to run. @xref{Commands}.
12119:
12120: @item Command Name
12121: A command name is the name of a Lisp symbol which is a command
12122: (@pxref{Commands}). You can invoke any command by its name using
12123: @kbd{M-x} (@pxref{M-x}).
12124:
12125: @item Comments
12126: A comment is text in a program which is intended only for humans
12127: reading the program, and is marked specially so that it will be
12128: ignored when the program is loaded or compiled. Emacs offers special
12129: commands for creating, aligning and killing comments.
12130: @xref{Comments}.
12131:
12132: @item Compilation
12133: Compilation is the process of creating an executable program from
12134: source code. Emacs has commands for compiling files of Emacs Lisp
12135: code (@pxref{Lisp Libraries}) and programs in C and other languages
12136: (@pxref{Compilation}).
12137:
12138: @item Completion
12139: Completion is what Emacs does when it automatically fills out an
12140: abbreviation for a name into the entire name. Completion is done for
12141: minibuffer (q.v.@:) arguments, when the set of possible valid inputs
12142: is known; for example, on command names, buffer names, and
12143: file names. Completion occurs when @key{TAB}, @key{SPC} or @key{RET}
12144: is typed. @xref{Completion}.@refill
12145:
12146: @item Continuation Line
12147: When a line of text is longer than the width of the screen, it
12148: takes up more than one screen line when displayed. We say that the
12149: text line is continued, and all screen lines used for it after the
12150: first are called continuation lines. @xref{Basic,Continuation,Basic
12151: Editing}.
12152:
12153: @item Control-Character
12154: ASCII characters with octal codes 0 through 040, and also code 0177,
12155: do not have graphic images assigned to them. These are the control
12156: characters. Any control character can be typed by holding down the
12157: @key{CTRL} key and typing some other character; some have special keys
12158: on the keyboard. @key{RET}, @key{TAB}, @key{ESC}, @key{LFD} and
12159: @key{DEL} are all control characters. @xref{Characters}.@refill
12160:
12161: @item Current Buffer
12162: The current buffer in Emacs is the Emacs buffer on which most editing
12163: commands operate. You can select any Emacs buffer as the current one.
12164: @xref{Buffers}.
12165:
12166: @item Current Line
12167: The line point is on (@pxref{Point}).
12168:
12169: @item Current Paragraph
12170: The paragraph that point is in. If point is between paragraphs, the
12171: current paragraph is the one that follows point. @xref{Paragraphs}.
12172:
12173: @item Current Defun
12174: The defun (q.v.@:) that point is in. If point is between defuns, the
12175: current defun is the one that follows point. @xref{Defuns}.
12176:
12177: @item Cursor
12178: The cursor is the rectangle on the screen which indicates the position
12179: called point (q.v.@:) at which insertion and deletion takes place.
12180: Often people speak of `the cursor' when, strictly speaking, they mean
12181: `point'. @xref{Basic,Cursor,Basic Editing}.
12182:
12183: @item Customization
12184: Customization is making minor changes in the way Emacs works. It is
12185: often done by setting variables (@pxref{Variables}) or by rebinding
12186: keys (@pxref{Keymaps}).
12187:
12188: @item Default Argument
12189: The default for an argument is the value that will be assumed if you
12190: do not specify one. When the minibuffer is used to read an argument,
12191: the default argument is used if you just type @key{RET}.
12192: @xref{Minibuffer}.
12193:
12194: @item Default Directory
12195: When you specify a file name that does not start with @samp{/} or @samp{~},
12196: it is interpreted relative to the current buffer's default directory.
12197: @xref{Minibuffer File,Default Directory}.
12198:
12199: @item Defun
12200: A defun is a list at the top level of parenthesis or bracket structure
12201: in a program. It is so named because most such lists in Lisp programs
12202: are calls to the Lisp function @code{defun}. @xref{Defuns}.
12203:
12204: @item @key{DEL}
12205: @key{DEL} is a character that runs the command to delete one character of
12206: text. @xref{Basic,DEL,Basic Editing}.
12207:
12208: @item Deletion
12209: Deletion means erasing text without saving it. Emacs deletes text
12210: only when it is expected not to be worth saving (all whitespace, or
12211: only one character). The alternative is killing (q.v.@:).
12212: @xref{Killing,Deletion}.
12213:
12214: @item Deletion of Files
12215: Deleting a file means erasing it from the file system. @xref{Misc
12216: File Ops}.
12217:
12218: @item Deletion of Messages
12219: Deleting a message means flagging it to be eliminated from your mail
12220: file. This can be undone by undeletion until the mail file is expunged.
12221: @xref{Rmail Deletion}.
12222:
12223: @item Deletion of Windows
12224: Deleting a window means eliminating it from the screen. Other windows
12225: expand to use up the space. The deleted window can never come back,
12226: but no actual text is thereby lost. @xref{Windows}.
12227:
12228: @item Directory
12229: Files in the Unix file system are grouped into file directories.
12230: @xref{ListDir,,Directories}.
12231:
12232: @item Dired
12233: Dired is the Emacs facility that displays the contents of a file
12234: directory and allows you to ``edit the directory'', performing
12235: operations on the files in the directory. @xref{Dired}.
12236:
12237: @item Disabled Command
12238: A disabled command is one that you may not run without special
12239: confirmation. The usual reason for disabling a command is that it is
12240: confusing for beginning users. @xref{Disabling}.
12241:
12242: @item Dribble File
12243: A file into which Emacs writes all the characters that the user types
12244: on the keyboard. Dribble files are used to make a record for
12245: debugging Emacs bugs. Emacs does not make a dribble file unless you
12246: tell it to. @xref{Bugs}.
12247:
12248: @item Echo Area
12249: The echo area is the bottom line of the screen, used for echoing the
12250: arguments to commands, for asking questions, and printing brief
12251: messages (including error messages). @xref{Echo Area}.
12252:
12253: @item Echoing
12254: Echoing is acknowledging the receipt of commands by displaying them
12255: (in the echo area). Emacs never echoes single-character keys; longer
12256: keys echo only if you pause while typing them.
12257:
12258: @item Error Messages
12259: Error messages are single lines of output printed by Emacs when the
12260: user asks for something impossible to do (such as, killing text
12261: forward when point is at the end of the buffer). They appear in the
12262: echo area, accompanied by a beep.
12263:
12264: @item @key{ESC}
12265: @key{ESC} is a character, used to end incremental searches and as a
12266: prefix for typing Meta characters on keyboards lacking a @key{META}
12267: key.
12268:
12269: @item Fill Prefix
12270: The fill prefix is a string that should be expected at the beginning
12271: of each line when filling is done. It is not regarded as part of the
12272: text to be filled. @xref{Filling}.
12273:
12274: @item Filling
12275: Filling text means moving text from line to line so that all the lines
12276: are approximately the same length. @xref{Filling}.
12277:
12278: @item Global
12279: Global means `independent of the current environment; in effect
12280: throughout Emacs'. It is the opposite of local (q.v.@:). Particular
12281: examples of the use of `global' appear below.
12282:
12283: @item Global Abbrev
12284: A global definition of an abbrev (q.v.@:) is effective in all major
12285: modes that do not have local (q.v.@:) definitions for the same abbrev.
12286: @xref{Abbrevs}.
12287:
12288: @item Global Keymap
12289: The global keymap (q.v.@:) contains key bindings that are in effect
12290: except when overridden by local key bindings in a major mode's local
12291: keymap (q.v.@:). @xref{Keymaps}.
12292:
12293: @item Global Substitution
12294: Global substitution means replacing each occurrence of one string by
12295: another string through a large amount of text. @xref{Replace}.
12296:
12297: @item Global Variable
12298: The global value of a variable (q.v.@:) takes effect in all buffers
12299: that do not have their own local (q.v.@:) values for the variable.
12300: @xref{Variables}.
12301:
12302: @item Graphic Character
12303: Graphic characters are those assigned pictorial images rather than
12304: just names. All the non-Meta (q.v.@:) characters except for the
12305: Control (q.v.@:) characters are graphic characters. These include
12306: letters, digits, punctuation, and spaces; they do not include
12307: @key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts
12308: that character (in ordinary editing modes). @xref{Basic,,Basic Editing}.
12309:
12310: @item Grinding
12311: Grinding means adjusting the indentation in a program to fit the
12312: nesting structure. @xref{Indentation,Grinding}.
12313:
12314: @item Hardcopy
12315: Hardcopy means printed output. Emacs has commands for making printed
12316: listings of text in Emacs buffers. @xref{Hardcopy}.
12317:
12318: @item @key{HELP}
12319: You can type @key{HELP} at any time to ask what options you have, or
12320: to ask what any command does. @key{HELP} is really @kbd{Control-h}.
12321: @xref{Help}.
12322:
12323: @item Indentation
12324: Indentation means blank space at the beginning of a line. Most
12325: programming languages have conventions for using indentation to
12326: illuminate the structure of the program, and Emacs has special
12327: features to help you set up the correct indentation.
12328: @xref{Indentation}.
12329:
12330: @item Insertion
12331: Insertion means copying text into the buffer, either from the keyboard
12332: or from some other place in Emacs.
12333:
12334: @item Justification
12335: Justification means adding extra spaces to lines of text to make them
12336: come exactly to a specified width. @xref{Filling,Justification}.
12337:
12338: @item Keyboard Macros
12339: Keyboard macros are a way of defining new Emacs commands from
12340: sequences of existing ones, with no need to write a Lisp program.
12341: @xref{Keyboard Macros}.
12342:
12343: @item Key
12344: A key is a character or sequence of characters which, when typed by
12345: the user, fully specifies one action to be performed by Emacs. For
12346: example, @kbd{X} and @kbd{Control-f} and @kbd{Control-x m} are keys.
12347: Keys derive their meanings from being bound (q.v.@:) to commands
12348: (q.v.@:). @xref{Keys}.
12349:
12350: @item Keymap
12351: The keymap is the data structure that records the bindings (q.v.@:) of
12352: keys to the commands that they run. For example, the keymap binds the
12353: character @kbd{C-n} to the command function @code{next-line}.
12354: @xref{Keymaps}.
12355:
12356: @item Kill Ring
12357: The kill ring is where all text you have killed recently is saved.
12358: You can reinsert any of the killed text still in the ring; this is
12359: called yanking (q.v.@:). @xref{Yanking}.
12360:
12361: @item Killing
12362: Killing means erasing text and saving it on the kill ring so it can be
12363: yanked (q.v.@:) later. Most Emacs commands to erase text do killing,
12364: as opposed to deletion (q.v.@:). @xref{Killing}.
12365:
12366: @item Killing Jobs
12367: Killing a job (such as, an invocation of Emacs) means making it cease
12368: to exist. Any data within it, if not saved in a file, is lost.
12369: @xref{Exiting}.
12370:
12371: @item List
12372: A list is, approximately, a text string beginning with an open
12373: parenthesis and ending with the matching close parenthesis. In C mode
12374: and other non-Lisp mode groupings surrounded by other kinds of matched
12375: delimiters appropriate to the language, such as braces, are also
12376: considered lists. Emacs has special commands for many operations on
12377: lists. @xref{Lists}.
12378:
12379: @item Local
12380: Local means `in effect only in a particular context'; the relevant
12381: kind of context is a particular function execution, a particular
12382: buffer, or a particular major mode. It is the opposite of `global'
12383: (q.v.@:). Specific uses of `local' in Emacs terminology appear below.
12384:
12385: @item Local Abbrev
12386: A local abbrev definition is effective only if a particular major mode
12387: is selected. In that major mode, it overrides any global definition
12388: for the same abbrev. @xref{Abbrevs}.
12389:
12390: @item Local Keymap
12391: A local keymap is used in a particular major mode; the key bindings
12392: (q.v.@:) in the current local keymap override global bindings of the
12393: same keys. @xref{Keymaps}.
12394:
12395: @item Local Variable
12396: A local value of a variable (q.v.@:) applies to only one buffer.
12397: @xref{Locals}.
12398:
12399: @item M-
12400: @kbd{M-} in the name of a character is an abbreviation for @key{META},
12401: one of the modifier keys that can accompany any character.
12402: @xref{Characters}.
12403:
12404: @item M-C-
12405: @samp{M-C-} in the name of a character is an abbreviation for
12406: Control-Meta; it means the same thing as @samp{C-M-}.
12407: @xref{Characters,C-M-}.
12408:
12409: @item M-x
12410: @kbd{M-x} is the key which is used to call an Emacs command by name.
12411: This is how commands that are not bound to keys are called.
12412: @xref{M-x}.
12413:
12414: @item Mail
12415: Mail means messages sent from one user to another through the computer
12416: system, to be read at the recipient's convenience. Emacs has commands for
12417: composing and sending mail, and for reading and editing the mail you have
12418: received. @xref{Sending Mail}.
12419:
12420: @item Major Mode
12421: The major modes are a mutually exclusive set of options each of which
12422: configures Emacs for editing a certain sort of text. Ideally, each
12423: programming language has its own major mode. @xref{Major Modes}.
12424:
12425: @item Mark
12426: The mark points to a position in the text. It specifies one end of
12427: the region (q.v.@:), point being the other end. Many commands operate
12428: on all the text from point to the mark. @xref{Mark}.
12429:
12430: @item Mark Ring
12431: The mark ring is used to hold several recent previous locations of the
12432: mark, just in case you want to move back to them. @xref{Mark Ring}.
12433:
12434: @item Message
12435: See `mail'.
12436:
12437: @item Meta
12438: Meta is the name of a modifier bit which a command character may have.
12439: It is present in a character if the character is typed with the
12440: @key{META} key held down. Such characters are given names that start
12441: with @kbd{Meta-}. For example, @kbd{Meta-<} is typed by holding down
12442: @key{META} and typing @kbd{<} (which itself is done, on most terminals,
12443: by holding down @key{SHIFT} and typing @kbd{,}). @xref{Characters,Meta}.
12444:
12445: @item Meta Character
12446: A Meta character is one whose character code includes the Meta bit.
12447:
12448: @item Minibuffer
12449: The minibuffer is the window that appears when necessary inside the
12450: echo area (q.v.@:), used for reading arguments to commands.
12451: @xref{Minibuffer}.
12452:
12453: @item Minor Mode
12454: A minor mode is an optional feature of Emacs which can be switched on
12455: or off independently of all other features. Each minor mode has a
12456: command to turn it on or off. @xref{Minor Modes}.
12457:
12458: @item Mode Line
12459: The mode line is the line at the bottom of each text window (q.v.@:),
12460: which gives status information on the buffer displayed in that window.
12461: @xref{Mode Line}.
12462:
12463: @item Modified Buffer
12464: A buffer (q.v.@:) is modified if its text has been changed since the
12465: last time the buffer was saved (or since when it was created, if it
12466: has never been saved). @xref{Saving}.
12467:
12468: @item Moving Text
12469: Moving text means erasing it from one place and inserting it in
12470: another. This is done by killing (q.v.@:) and then yanking (q.v.@:).
12471: @xref{Killing}.
12472:
12473: @item Named Mark
12474: A named mark is a register (q.v.@:) in its role of recording a
12475: location in text so that you can move point to that location.
12476: @xref{Registers}.
12477:
12478: @item Narrowing
12479: Narrowing means creating a restriction (q.v.@:) that limits editing in
12480: the current buffer to only a part of the text in the buffer. Text
12481: outside that part is inaccessible to the user until the boundaries are
12482: widened again, but it is still there, and saving the file saves it
12483: all. @xref{Narrowing}.
12484:
12485: @item Newline
12486: @key{LFD} characters in the buffer terminate lines of text and are
12487: called newlines. @xref{Characters,Newline}.
12488:
12489: @item Numeric Argument
12490: A numeric argument is a number, specified before a command, to change
12491: the effect of the command. Often the numeric argument serves as a
12492: repeat count. @xref{Arguments}.
12493:
12494: @item Option
12495: An option is a variable (q.v.@:) that exists so that you can customize
12496: Emacs by giving it a new value. @xref{Variables}.
12497:
12498: @item Overwrite Mode
12499: Overwrite mode is a minor mode. When it is enabled, ordinary text
12500: characters replace the existing text after point rather than pushing
12501: it to the right. @xref{Minor Modes}.
12502:
12503: @item Page
12504: A page is a unit of text, delimited by formfeed characters (ASCII
12505: Control-L, code 014) coming at the beginning of a line. Some Emacs
12506: commands are provided for moving over and operating on pages.
12507: @xref{Pages}.
12508:
12509: @item Paragraphs
12510: Paragraphs are the medium-size unit of English text. There are
12511: special Emacs commands for moving over and operating on paragraphs.
12512: @xref{Paragraphs}.
12513:
12514: @item Parsing
12515: We say that Emacs parses words or expressions in the text being
12516: edited. Really, all it knows how to do is find the other end of a
12517: word or expression. @xref{Syntax}.
12518:
12519: @item Point
12520: Point is the place in the buffer at which insertion and deletion
12521: occur. Point is considered to be between two characters, not at one
12522: character. The terminal's cursor (q.v.@:) indicates the location of
12523: point. @xref{Basic,Point}.
12524:
12525: @item Prefix Key
12526: A prefix key is a key (q.v.@:) whose sole function is to introduce a
12527: set of multi-character keys. @kbd{Control-x} is an example of prefix
12528: key; thus, any two-character sequence starting with @kbd{C-x} is also
12529: a legitimate key. @xref{Keys}.
12530:
12531: @item Prompt
12532: A prompt is text printed to ask the user for input. Printing a prompt
12533: is called prompting. Emacs prompts always appear in the echo area
12534: (q.v.@:). One kind of prompting happens when the minibuffer is used
12535: to read an argument (@pxref{Minibuffer}); the echoing which happens
12536: when you pause in the middle of typing a multicharacter key is also a
12537: kind of prompting (@pxref{Echo Area}).
12538:
12539: @item Quitting
12540: Quitting means cancelling a partially typed command or a running
12541: command, using @kbd{C-g}. @xref{Quitting}.
12542:
12543: @item Quoting
12544: Quoting means depriving a character of its usual special significance.
12545: In Emacs this is usually done with @kbd{Control-q}. What constitutes special
12546: significance depends on the context and on convention. For example,
12547: an ``ordinary'' character as an Emacs command inserts itself; so in
12548: this context, a special character is any character that does not
12549: normally insert itself (such as @key{DEL}, for example), and quoting
12550: it makes it insert itself as if it were not special. Not all contexts
12551: allow quoting. @xref{Basic,Quoting,Basic Editing}.
12552:
12553: @item Read-only Buffer
12554: A read-only buffer is one whose text you are not allowed to change.
12555: Normally Emacs makes buffers read-only when they contain text which
12556: has a special significance to Emacs; for example, Dired buffers.
12557: Visiting a file that is write protected also makes a read-only buffer.
12558: @xref{Buffers}.
12559:
12560: @item Recursive Editing Level
12561: A recursive editing level is a state in which part of the execution of
12562: a command involves asking the user to edit some text. This text may
12563: or may not be the same as the text to which the command was applied.
12564: The mode line indicates recursive editing levels with square brackets
12565: (@samp{[} and @samp{]}). @xref{Recursive Edit}.
12566:
12567: @item Redisplay
12568: Redisplay is the process of correcting the image on the screen to
12569: correspond to changes that have been made in the text being edited.
12570: @xref{Screen,Redisplay}.
12571:
12572: @item Region
12573: The region is the text between point (q.v.@:) and the mark (q.v.@:).
12574: Many commands operate on the text of the region. @xref{Mark,Region}.
12575:
12576: @item Registers
12577: Registers are named slots in which text or buffer positions or
12578: rectangles can be saved for later use. @xref{Registers}.
12579:
12580: @item Replacement
12581: See `global substitution'.
12582:
12583: @item Restriction
12584: A buffer's restriction is the amount of text, at the beginning or the
12585: end of the buffer, that is temporarily invisible and inaccessible.
12586: Giving a buffer a nonzero amount of restriction is called narrowing
12587: (q.v.). @xref{Narrowing}.
12588:
12589: @item @key{RET}
12590: @key{RET} is a character than in Emacs runs the command to insert a
12591: newline into the text. It is also used to terminate most arguments
12592: read in the minibuffer (q.v.@:). @xref{Characters,Return}.
12593:
12594: @item Saving
12595: Saving a buffer means copying its text into the file that was visited
12596: (q.v.@:) in that buffer. This is the way text in files actually gets
12597: changed by your Emacs editing. @xref{Saving}.
12598:
12599: @item Scrolling
12600: Scrolling means shifting the text in the Emacs window so as to see a
12601: different part of the buffer. @xref{Display,Scrolling}.
12602:
12603: @item Searching
12604: Searching means moving point to the next occurrence of a specified
12605: string. @xref{Search}.
12606:
12607: @item Selecting
12608: Selecting a buffer means making it the current (q.v.@:) buffer.
12609: @xref{Buffers,Selecting}.
12610:
12611: @item Self-documentation
12612: Self-documentation is the feature of Emacs which can tell you what any
12613: command does, or give you a list of all commands related to a topic
12614: you specify. You ask for self-documentation with the @key{HELP}
12615: character. @xref{Help}.
12616:
12617: @item Sentences
12618: Emacs has commands for moving by or killing by sentences.
12619: @xref{Sentences}.
12620:
12621: @item Sexp
12622: A sexp (short for `s-expression') is the basic syntactic unit of Lisp
12623: in its textual form: either a list, or Lisp atom. Many Emacs commands
12624: operate on sexps. The term `sexp' is generalized to languages other
12625: than Lisp, to mean a syntactically recognizable expression.
12626: @xref{Lists,Sexps}.
12627:
12628: @item Simultaneous Editing
12629: Simultaneous editing means two users modifying the same file at once.
12630: Simultaneous editing if not detected can cause one user to lose his
12631: work. Emacs detects all cases of simultaneous editing and warns the
12632: user to investigate them. @xref{Interlocking,,Simultaneous Editing}.
12633:
12634: @item String
12635: A string is a kind of Lisp data object which contains a sequence of
12636: characters. Many Emacs variables are intended to have strings as
12637: values. The Lisp syntax for a string consists of the characters in
12638: the string with a @samp{"} before and another @samp{"} after. A
12639: @samp{"} that is part of the string must be written as @samp{\"} and a
12640: @samp{\} that is part of the string must be written as @samp{\\}. All
12641: other characters, including newline, can be included just by writing
12642: them inside the string; however, escape sequences as in C, such as
12643: @samp{\n} for newline or @samp{\241} using an octal character code,
12644: are allowed as well.
12645:
12646: @item String Substitution
12647: See `global substitution'.
12648:
12649: @item Syntax Table
12650: The syntax table tells Emacs which characters are part of a word,
12651: which characters balance each other like parentheses, etc.
12652: @xref{Syntax}.
12653:
12654: @item Tag Table
12655: A tag table is a file that serves as an index to the function
12656: definitions in one or more other files. @xref{Tags}.
12657:
12658: @item Termscript File
12659: A termscript file contains a record of all characters sent by Emacs to
12660: the terminal. It is used for tracking down bugs in Emacs redisplay.
12661: Emacs does not make a termscript file unless you tell it to.
12662: @xref{Bugs}.
12663:
12664: @item Text
12665: Two meanings (@pxref{Text}):
12666:
12667: @itemize @bullet
12668: @item
12669: Data consisting of a sequence of characters. The contents of an
12670: Emacs buffer are always text in this sense.
12671: @item
12672: Data consisting of written human language, as opposed to programs,
12673: or following the stylistic conventions of human language.
12674: @end itemize
12675:
12676: @item Top Level
12677: Top level is the normal state of Emacs, in which you are editing the
12678: text of the file you have visited. You are at top level whenever you
12679: are not in a recursive editing level (q.v.@:) or the minibuffer
12680: (q.v.@:), and not in the middle of a command. You can get back to top
12681: level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}.
12682:
12683: @item Transposition
12684: Transposing two units of text means putting each one into the place
12685: formerly occupied by the other. There are Emacs commands to transpose
12686: two adjacent characters, words, sexps (q.v.@:) or lines
12687: (@pxref{Transpose}).
12688:
12689: @item Truncation
12690: Truncating text lines in the display means leaving out any text on a
12691: line that does not fit within the right margin of the window
12692: displaying it. See also `continuation line'.
12693: @xref{Basic,Truncation,Basic Editing}.
12694:
12695: @item Undoing
12696: Undoing means making your previous editing go in reverse, bringing
12697: back the text that existed earlier in the editing session.
12698: @xref{Undo}.
12699:
12700: @item Variable
12701: A variable is an object in Lisp that can store an arbitrary value.
12702: Emacs uses some variables for internal purposes, and has others (known
12703: as `options' (q.v.@:)) just so that you can set their values to
12704: control the behavior of Emacs. The variables used in Emacs that you
12705: are likely to be interested in are listed in the Variables Index in
12706: this manual. @xref{Variables}, for information on variables.
12707:
12708: @item Visiting
12709: Visiting a file means loading its contents into a buffer (q.v.@:)
12710: where they can be edited. @xref{Visiting}.
12711:
12712: @item Whitespace
12713: Whitespace is any run of consecutive formatting characters (space,
12714: tab, newline, and backspace).
12715:
12716: @item Widening
12717: Widening is removing any restriction (q.v.@:) on the current buffer;
12718: it is the opposite of narrowing (q.v.@:). @xref{Narrowing}.
12719:
12720: @item Window
12721: Emacs divides the screen into one or more windows, each of which can
12722: display the contents of one buffer (q.v.@:) at any time.
12723: @xref{Screen}, for basic information on how Emacs uses the screen.
12724: @xref{Windows}, for commands to control the use of windows.
12725:
12726: @item Word Abbrev
12727: Synonymous with `abbrev'.
12728:
12729: @item Word Search
12730: Word search is searching for a sequence of words, considering the
12731: punctuation between them as insignificant. @xref{Word Search}.
12732:
12733: @item Yanking
12734: Yanking means reinserting text previously killed. It can be used to
12735: undo a mistaken kill, or for copying or moving text. @xref{Yanking}.
12736: @end table
12737:
12738: @node Key Index, Command Index, Glossary, Top
12739: @unnumbered Key (Character) Index
12740: @printindex ky
12741:
12742: @node Command Index, Variable Index, Key Index, Top
12743: @unnumbered Command and Function Index
12744: @printindex fn
12745:
12746: @node Variable Index, Concept Index, Command Index, Top
12747: @unnumbered Variable Index
12748: @printindex vr
12749:
12750: @node Concept Index, Screen, Variable Index, Top
12751: @unnumbered Concept Index
12752: @printindex cp
12753:
12754: @summarycontents
12755: @contents
12756: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.