43BSDReno/contrib/emacs-18.55/man/emacs.tex - annotate

Return to emacs.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / man

Annotation of 43BSDReno/contrib/emacs-18.55/man/emacs.tex, revision 1.1.1.1

1.1 root 1: \input texinfo @c -*-texinfo-*-
2: @setfilename ../info/emacs
3: @c @smallbook
4: @tex
5: \overfullrule=0pt
6: @end tex
7: @ifinfo
8: This file documents the GNU Emacs editor.
9:
10: Copyright (C) 1985, 1986 Richard M. Stallman.
11:
12: Permission is granted to make and distribute verbatim copies of
13: this manual provided the copyright notice and this permission notice
14: are preserved on all copies.
15:
16: @ignore
17: Permission is granted to process this file through Tex and print the
18: results, provided the printed document carries copying permission
19: notice identical to this one except for the removal of this paragraph
20: (this paragraph not being relevant to the printed manual).
21:
22: @end ignore
23: Permission is granted to copy and distribute modified versions of this
24: manual under the conditions for verbatim copying, provided also that the
25: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU Emacs
26: General Public License'' are included exactly as in the original, and
27: provided that the entire resulting derived work is distributed under the
28: terms of a permission notice identical to this one.
29:
30: Permission is granted to copy and distribute translations of this manual
31: into another language, under the above conditions for modified versions,
32: except that the sections entitled ``The GNU Manifesto'', ``Distribution''
33: and ``GNU Emacs General Public License'' may be included in a translation
34: approved by the author instead of in the original English.
35: @end ifinfo
36: @c
37: @setchapternewpage odd
38: @settitle GNU Emacs Manual
39: @c
40: @titlepage
41: @sp 6
42: @center @titlefont{GNU Emacs Manual}
43: @sp 4
44: @center Fifth Edition, Emacs Version 18
45: @sp 1
46: @center for Unix Users
47: @sp 1
48: @center October 1986
49: @sp 5
50: @center Richard Stallman
51: @page
52: @vskip 0pt plus 1filll
53: Copyright @copyright{} 1985, 1986 Richard M. Stallman.
54:
55: Permission is granted to make and distribute verbatim copies of
56: this manual provided the copyright notice and this permission notice
57: are preserved on all copies.
58:
59: Permission is granted to copy and distribute modified versions of this
60: manual under the conditions for verbatim copying, provided also that the
61: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU Emacs
62: General Public License'' are included exactly as in the original, and
63: provided that the entire resulting derived work is distributed under the
64: terms of a permission notice identical to this one.
65:
66: Permission is granted to copy and distribute translations of this manual
67: into another language, under the above conditions for modified versions,
68: except that the sections entitled ``The GNU Manifesto'', ``Distribution''
69: and ``GNU Emacs General Public License'' may be included in a translation
70: approved by the author instead of in the original English.
71: @end titlepage
72: @page
73: @ifinfo
74: @node Top, Distrib,, (DIR)
75:
76: The Emacs Editor
77: ****************
78:
79: Emacs is the extensible, customizable, self-documenting real-time
80: display editor. This Info file describes how to edit with Emacs
81: and some of how to customize it, but not how to extend it.
82:
83: @end ifinfo
84: @menu
85: * Distrib:: How to get the latest Emacs distribution.
86: * License:: The GNU Emacs General Public License gives you permission
87: to redistribute GNU Emacs on certain terms; and also
88: explains that there is no warranty.
89: * Intro:: An introduction to Emacs concepts.
90: * Glossary:: The glossary.
91: * Manifesto:: What's GNU? Gnu's Not Unix!
92:
93: Indexes, nodes containing large menus
94: * Key Index:: An item for each standard Emacs key sequence.
95: * Command Index:: An item for each command name.
96: * Variable Index:: An item for each documented variable.
97: * Concept Index:: An item for each concept.
98:
99: Important General Concepts
100: * Screen:: How to interpret what you see on the screen.
101: * Characters:: Emacs's character sets for file contents and for keyboard.
102: * Keys:: Key sequences: what you type to request one editing action.
103: * Commands:: Commands: named functions run by key sequences to do editing.
104: * Entering Emacs:: Starting Emacs from the shell.
105: * Command Switches:: Hairy startup options.
106: * Exiting:: Stopping or killing Emacs.
107: * Basic:: The most basic editing commands.
108: * Undo:: Undoing recently made changes in the text.
109: * Minibuffer:: Entering arguments that are prompted for.
110: * M-x:: Invoking commands by their names.
111: * Help:: Commands for asking Emacs about its commands.
112:
113: Important Text-Changing Commands
114: * Mark:: The mark: how to delimit a ``region'' of text.
115: * Killing:: Killing text.
116: * Yanking:: Recovering killed text. Moving text.
117: * Accumulating Text::
118: Other ways of copying text.
119: * Rectangles:: Operating on the text inside a rectangle on the screen.
120: * Registers:: Saving a text string or a location in the buffer.
121: * Display:: Controlling what text is displayed.
122: * Search:: Finding or replacing occurrences of a string.
123: * Fixit:: Commands especially useful for fixing typos.
124:
125: Larger Units of Text
126: * Files:: All about handling files.
127: * Buffers:: Multiple buffers; editing several files at once.
128: * Windows:: Viewing two pieces of text at once.
129:
130: Advanced Features
131: * Major Modes:: Text mode vs. Lisp mode vs. C mode ...
132: * Indentation:: Editing the white space at the beginnings of lines.
133: * Text:: Commands and modes for editing English.
134: * Programs:: Commands and modes for editing programs.
135: * Running:: Compiling, running and debugging programs.
136: * Abbrevs:: How to define text abbreviations to reduce
137: the number of characters you must type.
138: * Picture:: Editing pictures made up of characters
139: using the quarter-plane screen model.
140: * Sending Mail::Sending mail in Emacs.
141: * Rmail:: Reading mail in Emacs.
142: * Recursive Edit::
143: A command can allow you to do editing
144: "within the command". This is called a
145: `recursive editing level'.
146: * Narrowing:: Restricting display and editing to a portion
147: of the buffer.
148: * Sorting:: Sorting lines, paragraphs or pages within Emacs.
149: * Shell:: Executing shell commands from Emacs.
150: * Hardcopy:: Printing buffers or regions.
151: * Dissociated Press:: Dissociating text for fun.
152: * Amusements:: Various games and hacks.
153: * Emulation:: Emulating some other editors with Emacs.
154: * Customization:: Modifying the behavior of Emacs.
155:
156: Recovery from Problems.
157: * Quitting:: Quitting and aborting.
158: * Lossage:: What to do if Emacs is hung or malfunctioning.
159: * Bugs:: How and when to report a bug.
160:
161: Here are some other nodes which are really inferiors of the ones
162: already listed, mentioned here so you can get to them in one step:
163:
164: Subnodes of Screen
165: * Point:: The place in the text where editing commands operate.
166: * Echo Area:: Short messages appear at the bottom of the screen.
167: * Mode Line:: Interpreting the mode line.
168:
169: Subnodes of Basic
170: * Blank Lines:: Commands to make or delete blank lines.
171: * Continuation Lines:: Lines too wide for the screen.
172: * Position Info:: What page, line, row, or column is point on?
173: * Arguments:: Giving numeric arguments to commands.
174:
175: Subnodes of Minibuffer
176: * Minibuffer File:: Entering file names with the minibuffer.
177: * Minibuffer Edit:: How to edit in the minibuffer.
178: * Completion:: An abbreviation facility for minibuffer input.
179: * Repetition:: Re-executing previous commands that used the minibuffer.
180:
181: Subnodes of Mark
182: * Setting Mark:: Commands to set the mark.
183: * Using Region:: Summary of ways to operate on contents of the region.
184: * Marking Objects:: Commands to put region around textual units.
185: * Mark Ring:: Previous mark positions saved so you can go back there.
186:
187: Subnodes of Yanking
188: * Kill Ring:: Where killed text is stored. Basic yanking.
189: * Appending Kills:: Several kills in a row all yank together.
190: * Earlier Kills:: Yanking something killed some time ago.
191:
192: Subnodes of Registers
193: * RegPos:: Saving positions in registers.
194: * RegText:: Saving text in registers.
195: * RegRect:: Saving rectangles in registers.
196:
197: Subnodes of Display
198: * Scrolling:: Moving text up and down in a window.
199: * Horizontal Scrolling:: Moving text left and right in a window.
200: * Selective Display:: Hiding lines with lots of indentation.
201: * Display Vars:: Information on variables for customizing display.
202:
203: Subnodes of Search
204: * Incremental Search:: Search happens as you type the string.
205: * Nonincremental Search:: Specify entire string and then search.
206: * Word Search:: Search for sequence of words.
207: * Regexp Search:: Search for match for a regexp.
208: * Regexps:: Syntax of regular expressions.
209: * Search Case:: To ignore case while searching, or not.
210: * Replace:: Search, and replace some or all matches.
211: * Unconditional Replace:: Everything about replacement except for querying.
212: * Query Replace:: How to use querying.
213: * Other Repeating Search:: Operating on all matches for some regexp.
214:
215: Subnodes of Fixit
216: * Kill Errors:: Commands to kill a batch of recently entered text.
217: * Transpose:: Exchanging two characters, words, lines, lists...
218: * Fixing Case:: Correcting case of last word entered.
219: * Spelling:: Apply spelling checker to a word, or a whole file.
220:
221: Subnodes of Files
222: * File Names:: How to type and edit file name arguments.
223: * Visiting:: Visiting a file prepares Emacs to edit the file.
224: * Saving:: Saving makes your changes permanent.
225: * Backup:: How Emacs saves the old version of your file.
226: * Interlocking::How Emacs protects against simultaneous editing
227: of one file by two users.
228: * Reverting:: Reverting cancels all the changes not saved.
229: * Auto Save:: Auto Save periodically protects against loss of data.
230: * ListDir:: Listing the contents of a file directory.
231: * Dired:: ``Editing'' a directory to delete, rename, etc.
232: the files in it.
233: * Misc File Ops:: Other things you can do on files.
234:
235: Subnodes of Buffers
236: * Select Buffer:: Creating a new buffer or reselecting an old one.
237: * List Buffers:: Getting a list of buffers that exist.
238: * Misc Buffer:: Renaming; changing read-only status.
239: * Kill Buffer:: Killing buffers you no longer need.
240: * Several Buffers:: How to go through the list of all buffers
241: and operate variously on several of them.
242:
243: Subnodes of Windows
244: * Basic Window:: Introduction to Emacs windows.
245: * Split Window:: New windows are made by splitting existing windows.
246: * Other Window:: Moving to another window or doing something to it.
247: * Pop Up Window:: Finding a file or buffer in another window.
248: * Change Window:: Deleting windows and changing their sizes.
249:
250: Subnodes of Indentation
251: * Indentation Commands:: Various commands and techniques for indentation.
252: * Tab Stops:: You can set arbitrary "tab stops" and then
253: indent to the next tab stop when you want to.
254: * Just Spaces:: You can request indentation using just spaces.
255:
256: Subnodes of Text
257: * Text Mode:: The major mode for editing text files.
258: * Nroff Mode:: The major mode for editing input to the formatter nroff.
259: * TeX Mode:: The major mode for editing input to the formatter TeX.
260: * Outline Mode::The major mode for editing outlines.
261: * Words:: Moving over and killing words.
262: * Sentences:: Moving over and killing sentences.
263: * Paragraphs:: Moving over paragraphs.
264: * Pages:: Moving over pages.
265: * Filling:: Filling or justifying text
266: * Case:: Changing the case of text
267:
268: Subnodes of Programs
269: * Program Modes:: Major modes for editing programs.
270: * Lists:: Expressions with balanced parentheses.
271: There are editing commands to operate on them.
272: * Defuns:: Each program is made up of separate functions.
273: There are editing commands to operate on them.
274: * Grinding:: Adjusting indentation to show the nesting.
275: * Matching:: Insertion of a close-delimiter flashes matching open.
276: * Comments:: Inserting, illing and aligning comments.
277: * Balanced Editing:: Inserting two matching parentheses at once, etc.
278: * Lisp Completion:: Completion on symbol names in Lisp code.
279: * Documentation:: Getting documentation of functions you plan to call.
280: * Change Log:: Maintaining a change history for your program.
281: * Tags:: Go direct to any function in your program in one
282: command. Tags remembers which file it is in.
283: * Fortran:: Fortran mode and its special features.
284:
285: Subnodes of Running
286: * Compilation:: Compiling programs in languages other than Lisp
287: (C, Pascal, etc.)
288: * Lisp Modes:: Various modes for editing Lisp programs, with
289: different facilities for running the Lisp programs.
290: * Lisp Libraries:: Creating Lisp programs to run in Emacs.
291: * Lisp Interaction:: Executing Lisp in an Emacs buffer.
292: * Lisp Eval:: Executing a single Lisp expression in Emacs.
293: * Lisp Debug:: Debugging Lisp programs running in Emacs.
294: * External Lisp:: Communicating through Emacs with a separate Lisp.
295:
296: Subnodes of Abbrevs
297: * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
298: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
299: * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
300: * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
301: * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
302:
303: Subnodes of Picture
304: * Basic Picture:: Basic concepts and simple commands of Picture Mode.
305: * Insert in Picture:: Controlling direction of cursor motion
306: after "self-inserting" characters.
307: * Tabs in Picture:: Various features for tab stops and indentation.
308: * Rectangles in Picture:: Clearing and superimposing rectangles.
309:
310: Subnodes of Sending Mail
311: * Mail Format:: Format of the mail being composed.
312: * Mail Headers:: Details of allowed mail header fields.
313: * Mail Mode:: Special commands for editing mail being composed.
314:
315: Subnodes of Rmail
316: * Rmail Scrolling:: Scrolling through a message.
317: * Rmail Motion:: Moving to another message.
318: * Rmail Deletion:: Deleting and expunging messages.
319: * Rmail Inbox:: How mail gets into the Rmail file.
320: * Rmail Files:: Using multiple Rmail files.
321: * Rmail Output:: Copying message out to files.
322: * Rmail Labels:: Classifying messages by labeling them.
323: * Rmail Summary:: Summaries show brief info on many messages.
324: * Rmail Reply:: Sending replies to messages you are viewing.
325: * Rmail Editing:: Editing message text and headers in Rmail.
326: * Rmail Digest:: Extracting the messages from a digest message.
327:
328: Subnodes of Shell
329: * Single Shell:: Commands to run one shell command and return.
330: * Interactive Shell:: Permanent shell taking input via Emacs.
331: * Shell Mode:: Special Emacs commands used with permanent shell.
332:
333: Subnodes of Customization
334: * Minor Modes:: Each minor mode is one feature you can turn on
335: independently of any others.
336: * Variables:: Many Emacs commands examine Emacs variables
337: to decide what to do; by setting variables,
338: you can control their functioning.
339: * Examining:: Examining or setting one variable's value.
340: * Edit Options:: Examining or editing list of all variables' values.
341: * Locals:: Per-buffer values of variables.
342: * File Variables:: How files can specify variable values.
343: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
344: to be replayed with a single command.
345: * Key Bindings:: The keymaps say what command each key runs.
346: By changing them, you can "redefine keys".
347: * Keymaps:: Definition of the keymap data structure.
348: * Rebinding:: How to redefine one key's meaning conveniently.
349: * Disabling:: Disabling a command means confirmation is required
350: before it can be executed. This is done to protect
351: beginners from surprises.
352: * Syntax:: The syntax table controls how words and expressions
353: are parsed.
354: * Init File:: How to write common customizations in the `.emacs' file.
355:
356: Subnodes of Lossage (and recovery)
357: * Stuck Recursive:: `[...]' in mode line around the parentheses.
358: * Screen Garbled:: Garbage on the screen.
359: * Text Garbled:: Garbage in the text.
360: * Unasked-for Search::Spontaneous entry to incremental search.
361: * Emergency Escape:: Emergency escape---
362: What to do if Emacs stops responding.
363: * Total Frustration:: When you are at your wits' end.
364: @end menu
365:
366: @iftex
367: @unnumbered Preface
368:
369: This manual documents the use and simple customization of the
370: Emacs editor. The reader is not expected to be a programmer. Even simple
371: customizations do not require programming skill, but the user who is not
372: interested in customizing can ignore the scattered customization hints.
373:
374: This is primarily a reference manual, but can also be used as a
375: primer. However, I recommend that the newcomer first use the on-line,
376: learn-by-doing tutorial, which you get by running Emacs and typing
377: @kbd{C-h t}. With it, you learn Emacs by using Emacs on a specially
378: designed file which describes commands, tells you when to try them,
379: and then explains the results you see. This gives a more vivid
380: introduction than a printed manual.
381:
382: On first reading, just skim chapters one and two, which describe the
383: notational conventions of the manual and the general appearance of the
384: Emacs display screen. Note which questions are answered in these chapters,
385: so you can refer back later. After reading chapter four you should
386: practice the commands there. The next few chapters describe fundamental
387: techniques and concepts that are used constantly. You need to understand
388: them thoroughly, experimenting with them if necessary.
389:
390: To find the documentation on a particular command, look in the index.
391: Keys (character commands) and command names have separate indexes. There
392: is also a glossary, with a cross reference for each term.
393:
394: @ignore
395: If you know vaguely what the command
396: does, look in the command summary. The command summary contains a line or
397: two about each command, and a cross reference to the section of the
398: manual that describes the command in more detail; related commands
399: are grouped together.
400: @end ignore
401:
402: This manual comes in two forms: the published form and the Info form.
403: The Info form is for on-line perusal with the INFO program; it is
404: distributed along with GNU Emacs. Both forms contain substantially the
405: same text and are generated from a common source file, which is also
406: distributed along with GNU Emacs.
407:
408: GNU Emacs is a member of the Emacs editor family. There are many Emacs
409: editors, all sharing common principles of organization. For information on
410: the underlying philosophy of Emacs and the lessons learned from its
411: development, write for a copy of AI memo 519a, ``Emacs, the Extensible,
412: Customizable Self-Documenting Display Editor'', to Publications Department,
413: Artificial Intelligence Lab, 545 Tech Square, Cambridge, MA 02139, USA. At
414: last report they charge $2.25 per copy. Another useful publication is LCS
415: TM-165, ``A Cookbook for an Emacs'', by Craig Finseth, available from
416: Publications Department, Laboratory for Computer Science, 545 Tech Square,
417: Cambridge, MA 02139, USA. The price today is $3.
418:
419: This edition of the manual is intended for use with GNU Emacs installed on
420: Unix systems. GNU Emacs can also be used on VMS systems, which have
421: different file name syntax and do not support all GNU Emacs features. A
422: VMS edition of this manual may appear in the future.
423: @end iftex
424:
425: @node Distrib, License, Top, Top
426: @unnumbered Distribution
427:
428: GNU Emacs is @dfn{free}; this means that everyone is free to use it and
429: free to redistribute it on a free basis. GNU Emacs is not in the public
430: domain; it is copyrighted and there are restrictions on its distribution,
431: but these restrictions are designed to permit everything that a good
432: cooperating citizen would want to do. What is not allowed is to try to
433: prevent others from further sharing any version of GNU Emacs that they
434: might get from you. The precise conditions are found in the GNU Emacs
435: General Public License that comes with Emacs and also appears following
436: this section.
437:
438: The easiest way to get a copy of GNU Emacs is from someone else who has it.
439: You need not ask for permission to do so, or tell any one else; just copy
440: it.
441:
442: If you have access to the Internet, you can get the latest distribution
443: version of GNU Emacs from host @file{prep.ai.mit.edu} using anonymous
444: login. See the file @file{/u2/emacs/GETTING.GNU.SOFTWARE} on that host
445: to find out about your options for copying and which files to use.
446:
447: You may also receive GNU Emacs when you buy a computer. Computer
448: manufacturers are free to distribute copies on the same terms that apply to
449: everyone else. These terms require them to give you the full sources,
450: including whatever changes they may have made, and to permit you to
451: redistribute the GNU Emacs received from them under the usual terms of the
452: General Public License. In other words, the program must be free for you
453: when you get it, not just free for the manufacturer.
454:
455: If you cannot get a copy in any of those ways, you can order one from the
456: Free Software Foundation. Though Emacs itself is free, our distribution
457: service is not. An order form is included at the end of manuals printed by
458: the Foundation. It is also included in the file @file{etc/DISTRIB} in the
459: Emacs distribution. For further information, write to
460:
461: @display
462: Free Software Foundation
463: 675 Mass Ave
464: Cambridge, MA 02139
465: USA
466: @end display
467:
468: The income from distribution fees goes to support the foundation's
469: purpose: the development of more free software to distribute just like
470: GNU Emacs.
471:
472: If you find GNU Emacs useful, please @b{send a donation} to the Free
473: Software Foundation. This will help support development of the rest of the
474: GNU system, and other useful software beyond that. Your donation is tax
475: deductible.
476:
477: @node License, Intro, Distrib, Top
478: @unnumbered GNU Emacs General Public License
479: @center (Clarified 11 Feb 1988)
480:
481: The license agreements of most software companies keep you at the
482: mercy of those companies. By contrast, our general public license is
483: intended to give everyone the right to share GNU Emacs. To make
484: sure that you get the rights we want you to have, we need to make
485: restrictions that forbid anyone to deny you these rights or to ask you
486: to surrender the rights. Hence this license agreement.
487:
488: Specifically, we want to make sure that you have the right to give
489: away copies of Emacs, that you receive source code or else can get it
490: if you want it, that you can change Emacs or use pieces of it in new
491: free programs, and that you know you can do these things.
492:
493: To make sure that everyone has such rights, we have to forbid you to
494: deprive anyone else of these rights. For example, if you distribute
495: copies of Emacs, you must give the recipients all the rights that you
496: have. You must make sure that they, too, receive or can get the
497: source code. And you must tell them their rights.
498:
499: Also, for our own protection, we must make certain that everyone
500: finds out that there is no warranty for GNU Emacs. If Emacs is
501: modified by someone else and passed on, we want its recipients to know
502: that what they have is not what we distributed, so that any problems
503: introduced by others will not reflect on our reputation.
504:
505: Therefore we (Richard Stallman and the Free Software Foundation, Inc.)@:
506: make the following terms which say what you must do to be allowed to
507: distribute or change GNU Emacs.
508:
509: @unnumberedsec Copying Policies
510:
511: @enumerate
512: @item
513: You may copy and distribute verbatim copies of GNU Emacs source code as you
514: receive it, in any medium, provided that you conspicuously and
515: appropriately publish on each file a valid copyright notice ``Copyright
516: @copyright{} 1988 Free Software Foundation, Inc.'' (or with whatever year
517: is appropriate); keep intact the notices on all files that
518: refer to this License Agreement and to the absence of any warranty; and
519: give any other recipients of the GNU Emacs program a copy of this License
520: Agreement along with the program. You may charge a distribution fee
521: for the physical act of transferring a copy.
522:
523: @item
524: You may modify your copy or copies of GNU Emacs source code or
525: any portion of it, and copy and distribute such modifications under
526: the terms of Paragraph 1 above, provided that you also do the following:
527:
528: @itemize @bullet
529: @item
530: cause the modified files to carry prominent notices stating
531: who last changed such files and the date of any change; and
532:
533: @item
534: cause the whole of any work that you distribute or publish, that
535: in whole or in part contains or is a derivative of GNU Emacs or any
536: part thereof, to be licensed at no charge to all third parties on
537: terms identical to those contained in this License Agreement
538: (except that you may choose to grant more extensive warranty
539: protection to some or all third parties, at your option).
540:
541: @item
542: if the modified program serves as a text editor, cause it, when
543: started running in the simplest and usual way, to print an
544: announcement including a valid copyright notice ``Copyright
545: @copyright{} 1988 Free Software Foundation, Inc.'' (or with the
546: year that is appropriate), saying that there is no warranty (or
547: else, saying that you provide a warranty) and that users may
548: redistribute the program under these conditions, and telling the
549: user how to view a copy of this License Agreement.
550:
551: @item
552: You may charge a distribution fee for the physical act of
553: transferring a copy, and you may at your option offer warranty
554: protection in exchange for a fee.
555: @end itemize
556:
557: Mere aggregation of another unrelated program with this program (or its
558: derivative) on a volume of a storage or distribution medium does not bring
559: the other program under the scope of these terms.
560:
561: @item
562: You may copy and distribute GNU Emacs (or a portion or derivative of it,
563: under Paragraph 2) in object code or executable form under the terms
564: of Paragraphs 1 and 2 above provided that you also do one of the
565: following:
566:
567: @itemize @bullet
568: @item
569: accompany it with the complete corresponding machine-readable
570: source code, which must be distributed under the terms of
571: Paragraphs 1 and 2 above; or,
572:
573: @item
574: accompany it with a written offer, valid for at least three
575: years, to give any third party free (except for a nominal
576: shipping charge) a complete machine-readable copy of the
577: corresponding source code, to be distributed under the terms of
578: Paragraphs 1 and 2 above; or,
579:
580: @item
581: accompany it with the information you received as to where the
582: corresponding source code may be obtained. (This alternative is
583: allowed only for noncommercial distribution and only if you
584: received the program in object code or executable form alone.)
585: @end itemize
586:
587: For an executable file, complete source code means all the source code
588: for all modules it contains; but, as a special exception, it need not
589: include source code for modules which are standard libraries that
590: accompany the operating system on which the executable file runs.
591:
592: @item
593: You may not copy, sublicense, distribute or transfer GNU Emacs except
594: as expressly provided under this License Agreement. Any attempt
595: otherwise to copy, sublicense, distribute or transfer GNU Emacs is
596: void and your rights to use GNU Emacs under this License agreement
597: shall be automatically terminated. However, parties who have received
598: computer software programs from you with this License Agreement will
599: not have their licenses terminated so long as such parties remain in
600: full compliance.
601:
602: @item
603: If you wish to incorporate parts of GNU Emacs into other free programs
604: whose distribution conditions are different, write to the Free Software
605: Foundation. We have not yet worked out a simple rule that can be stated
606: here, but we will often permit this. We will be guided by the two goals of
607: preserving the free status of all derivatives of our free software and of
608: promoting the sharing and reuse of software.
609: @end enumerate
610:
611: Your comments and suggestions about our licensing policies and our
612: software are welcome! Please contact the Free Software Foundation, Inc.,
613: 675 Mass Ave, Cambridge, MA 02139.
614:
615: @iftex
616: @vfil
617: @eject
618: @end iftex
619: @unnumberedsec NO WARRANTY
620:
621: BECAUSE GNU EMACS IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
622: NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT
623: WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC,
624: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU EMACS ``AS IS''
625: WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
626: BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
627: FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY
628: AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE GNU EMACS
629: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
630: SERVICING, REPAIR OR CORRECTION.
631:
632: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
633: FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
634: MODIFY AND REDISTRIBUTE GNU EMACS AS PERMITTED ABOVE, BE LIABLE TO YOU
635: FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
636: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
637: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
638: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
639: FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
640: FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
641: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
642: OTHER PARTY.
643:
644: @node Intro, Glossary, License, Top
645: @unnumbered Introduction
646:
647: You are reading about GNU Emacs, the GNU incarnation of the advanced,
648: self-documenting, customizable, extensible real-time display editor Emacs.
649: (The `G' in `GNU' is not silent.)
650:
651: We say that Emacs is a @dfn{display} editor because normally the text
652: being edited is visible on the screen and is updated automatically as you
653: type your commands. @xref{Screen,Display}.
654:
655: We call it a @dfn{real-time} editor because the display is updated very
656: frequently, usually after each character or pair of characters you
657: type. This minimizes the amount of information you must keep in your
658: head as you edit. @xref{Basic,Real-time,Basic Editing}.
659:
660: We call Emacs advanced because it provides facilities that go beyond
661: simple insertion and deletion: filling of text; automatic indentation of
662: programs; viewing two or more files at once; and dealing in terms of
663: characters, words, lines, sentences, paragraphs, and pages, as well as
664: expressions and comments in several different programming languages. It is
665: much easier to type one command meaning ``go to the end of the paragraph''
666: than to find that spot with simple cursor keys.
667:
668: @dfn{Self-documenting} means that at any time you can type a special
669: character, @kbd{Control-h}, to find out what your options are. You can
670: also use it to find out what any command does, or to find all the commands
671: that pertain to a topic. @xref{Help}.
672:
673: @dfn{Customizable} means that you can change the definitions of Emacs
674: commands in little ways. For example, if you use a programming language in
675: which comments start with @samp{<**} and end with @samp{**>}, you can tell
676: the Emacs comment manipulation commands to use those strings
677: (@pxref{Comments}). Another sort of customization is rearrangement of the
678: command set. For example, if you prefer the four basic cursor motion
679: commands (up, down, left and right) on keys in a diamond pattern on the
680: keyboard, you can have it. @xref{Customization}.
681:
682: @dfn{Extensible} means that you can go beyond simple customization and
683: write entirely new commands, programs in the Lisp language to be run by
684: Emacs's own Lisp interpreter. Emacs is an ``on-line extensible'' system,
685: which means that it is divided into many functions that call each other,
686: any of which can be redefined in the middle of an editing session. Any
687: part of Emacs can be replaced without making a separate copy of all of
688: Emacs. Most of the editing commands of Emacs are written in Lisp already;
689: the few exceptions could have been written in Lisp but are written in C for
690: efficiency. Although only a programmer can write an extension, anybody can
691: use it afterward.
692:
693: @node Screen, Characters, Concept Index, Top
694:
695: @chapter The Organization of the Screen
696: @cindex screen
697:
698: Emacs divides the screen into several areas, each of which contains
699: its own sorts of information. The biggest area, of course, is the one
700: in which you usually see the text you are editing.
701:
702: When you are using Emacs, the screen is divided into a number of
703: @dfn{windows}. Initially there is one text window occupying all but the
704: last line, plus the special @dfn{echo area} or @dfn{minibuffer window} in
705: the last line. The text window can be subdivided horizontally or
706: vertically into multiple text windows, each of which can be used for a
707: different file (@pxref{Windows}). The window that the cursor is in is the
708: @dfn{selected window}, in which editing takes place. The other windows are
709: just for reference unless you select one of them.
710:
711: Each text window's last line is a @dfn{mode line} which describes what is
712: going on in that window. It is in inverse video if the terminal supports
713: that, and contains text that starts like @samp{-----Emacs:@: @var{something}}. Its
714: purpose is to indicate what buffer is being displayed above it in the
715: window; what major and minor modes are in use; and whether the buffer's
716: text has been changed.
717:
718: @menu
719: * Point:: The place in the text where editing commands operate.
720: * Echo Area:: Short messages appear at the bottom of the screen.
721: * Mode Line:: Interpreting the mode line.
722: @end menu
723:
724: @node Point, Echo Area, Screen, Screen
725: @section Point
726: @cindex point
727: @cindex cursor
728:
729: When Emacs is running, the terminal's cursor shows the location at
730: which editing commands will take effect. This location is called
731: @dfn{point}. Other commands move point through the text, so that you
732: can edit at different places in it.
733:
734: While the cursor appears to point @var{at} a character, point should be
735: thought of as @var{between} two characters; it points @var{before} the character
736: that the cursor appears on top of. Sometimes people speak of ``the
737: cursor'' when they mean ``point'', or speak of commands that move point as
738: ``cursor motion'' commands.
739:
740: Terminals have only one cursor, and when output is in progress it must
741: appear where the typing is being done. This does not mean that point is
742: moving. It is only that Emacs has no way to show you the location of point
743: except when the terminal is idle.
744:
745: If you are editing several files in Emacs, each file has its own point
746: location. A file that is not being displayed remembers where point is so
747: that it can be seen when you look at that file again.
748:
749: When there are multiple text windows, each window has its own point
750: location. The cursor shows the location of point in the selected window.
751: This also is how you can tell which window is selected. If the same buffer
752: appears in more than one window, point can be moved in each window
753: independently.
754:
755: The term `point' comes from the character @samp{.}, which was the
756: command in TECO (the language in which the original Emacs was written)
757: for accessing the value now called `point'.
758:
759: @node Echo Area, Mode Line, Point, Screen
760: @section The Echo Area
761: @cindex echo area
762:
763: The line at the bottom of the screen (below the mode line) is the
764: @dfn{echo area}. It is used to display small amounts of text for several
765: purposes.
766:
767: @dfn{Echoing} means printing out the characters that you type. Emacs
768: never echoes single-character commands, and multi-character commands are
769: echoed only if you pause while typing them. As soon as you pause for more
770: than a second in the middle of a command, all the characters of the command
771: so far are echoed. This is intended to @dfn{prompt} you for the rest of
772: the command. Once echoing has started, the rest of the command is echoed
773: immediately when you type it. This behavior is designed to give confident
774: users fast response, while giving hesitant users maximum feedback. You
775: can change this behavior by setting a variable (@pxref{Display Vars}).
776:
777: If a command cannot be executed, it may print an @dfn{error message} in
778: the echo area. Error messages are accompanied by a beep or by flashing the
779: screen. Also, any input you have typed ahead is thrown away when an error
780: happens.
781:
782: Some commands print informative messages in the echo area. These
783: messages look much like error messages, but they are not announced with a
784: beep and do not throw away input. Sometimes the message tells you what the
785: command has done, when this is not obvious from looking at the text being
786: edited. Sometimes the sole purpose of a command is to print a message
787: giving you specific information. For example, the command @kbd{C-x =} is
788: used to print a message describing the character position of point in the
789: text and its current column in the window. Commands that take a long time
790: often display messages ending in @samp{...} while they are working, and
791: add @samp{done} at the end when they are finished.
792:
793: The echo area is also used to display the @dfn{minibuffer}, a window that
794: is used for reading arguments to commands, such as the name of a file to be
795: edited. When the minibuffer is in use, the echo area begins with a prompt
796: string that usually ends with a colon; also, the cursor appears in that line
797: because it is the selected window. You can always get out of the
798: minibuffer by typing @kbd{C-g}. @xref{Minibuffer}.
799:
800: @node Mode Line,, Echo Area, Screen
801: @section The Mode Line
802: @cindex mode line
803: @cindex top level
804:
805: Each text window's last line is a @dfn{mode line} which describes what is
806: going on in that window. When there is only one text window, the mode line
807: appears right above the echo area. The mode line is in inverse video if
808: the terminal supports that, starts and ends with dashes, and contains text
809: like @samp{Emacs:@: @var{something}}.
810:
811: If a mode line has something else in place of @samp{Emacs:@: @var{something}},
812: then the window above it is in a special subsystem such as Dired. The mode
813: line then indicates the status of the subsystem.
814:
815: Normally, the mode line has the following appearance:
816:
817: @example
818: --@var{ch}-Emacs: @var{buf} (@var{major} @var{minor})----@var{pos}------
819: @end example
820:
821: @noindent
822: This gives information about the buffer being displayed in the window: the
823: buffer's name, what major and minor modes are in use, whether the buffer's
824: text has been changed, and how far down the buffer you are currently
825: looking.
826:
827: @var{ch} contains two stars @samp{**} if the text in the buffer has been
828: edited (the buffer is ``modified''), or @samp{--} if the buffer has not been
829: edited. Exception: for a read-only buffer, it is @samp{%%}.
830:
831: @var{buf} is the name of the window's chosen @dfn{buffer}. The chosen buffer
832: in the selected window (the window that the cursor is in) is also Emacs's
833: selected buffer, the one that editing takes place in. When we speak of
834: what some command does to ``the buffer'', we are talking about the
835: currently selected buffer. @xref{Buffers}.
836:
837: @var{pos} tells you whether there is additional text above the top of the
838: screen, or below the bottom. If your file is small and it is all on the
839: screen, @var{pos} is @samp{All}. Otherwise, it is @samp{Top} if you are
840: looking at the beginning of the file, @samp{Bot} if you are looking at the
841: end of the file, or @samp{@var{nn}%}, where @var{nn} is the percentage of
842: the file above the top of the screen.@refill
843:
844: @var{major} is the name of the @dfn{major mode} in effect in the buffer. At
845: any time, each buffer is in one and only one of the possible major modes.
846: The major modes available include Fundamental mode (the least specialized),
847: Text mode, Lisp mode, and C mode. @xref{Major Modes}, for details
848: of how the modes differ and how to select one.@refill
849:
850: @var{minor} is a list of some of the @dfn{minor modes} that are turned on
851: at the moment in the window's chosen buffer. @samp{Fill} means that Auto
852: Fill mode is on. @samp{Abbrev} means that Word Abbrev mode is on.
853: @samp{Ovwrt} means that Overwrite mode is on. @xref{Minor Modes}, for more
854: information. @samp{Narrow} means that the buffer being displayed has
855: editing restricted to only a portion of its text. This is not really a
856: minor mode, but is like one. @xref{Narrowing}. @samp{Def} means that a
857: keyboard macro is being defined. @xref{Keyboard Macros}.
858:
859: Some buffers display additional information after the minor modes. For
860: example, Rmail buffers display the current message number and the total
861: number of messages. Compilation buffers and Shell mode display the status
862: of the subprocess.
863:
864: In addition, if Emacs is currently inside a recursive editing level,
865: square brackets (@samp{[@dots{}]}) appear around the parentheses that
866: surround the modes. If Emacs is in one recursive editing level within
867: another, double square brackets appear, and so on. Since this information
868: pertains to Emacs in general and not to any one buffer, the square brackets
869: appear in every mode line on the screen or not in any of them.
870: @xref{Recursive Edit}.@refill
871:
872: @findex display-time
873: Emacs can optionally display the time and system load in all mode lines.
874: To enable this feature, type @kbd{M-x display-time}. The information added
875: to the mode line usually appears after the file name, before the mode names
876: and their parentheses. It looks like this:
877:
878: @example
879: @var{hh}:@var{mm}pm @var{l.ll} [@var{d}]
880: @end example
881:
882: @noindent
883: (Some fields may be missing if your operating system cannot support them.)
884: @var{hh} and @var{mm} are the hour and minute, followed always by @samp{am}
885: or @samp{pm}. @var{l.ll} is the average number of running processes in the
886: whole system recently. @var{d} is an approximate index of the ratio of
887: disk activity to cpu activity for all users.
888:
889: The word @samp{Mail} appears after the load level if there is mail for
890: you that you have not read yet.
891:
892: @vindex mode-line-inverse-video
893: Customization note: the variable @code{mode-line-inverse-video} controls
894: whether the mode line is displayed in inverse video (assuming the terminal
895: supports it); @code{nil} means no inverse video. The default is @code{t}.
896:
897: @iftex
898: @chapter Characters, Keys and Commands
899:
900: This chapter explains the character set used by Emacs for input commands
901: and for the contents of files, and also explains the concepts of
902: @dfn{keys} and @dfn{commands} which are necessary for understanding how
903: your keyboard input is understood by Emacs.
904: @end iftex
905:
906: @node Characters, Keys, Screen, Top
907: @section The Emacs Character Set
908: @cindex character set
909: @cindex ASCII
910:
911: GNU Emacs uses the ASCII character set, which defines 128 different
912: character codes. Some of these codes are assigned graphic symbols such
913: as @samp{a} and @samp{=}; the rest are control characters, such as
914: @kbd{Control-a} (also called @kbd{C-a} for short). @kbd{C-a} gets its name
915: from the fact that you type it by holding down the @key{CTRL} key and
916: then pressing @kbd{a}. There is no distinction between @kbd{C-a} and
917: @kbd{C-A}; they are the same character.@refill
918:
919: Some control characters have special names, and special keys you can
920: type them with: @key{RET}, @key{TAB}, @key{LFD}, @key{DEL} and @key{ESC}.
921: The space character is usually referred to below as @key{SPC}, even though
922: strictly speaking it is a graphic character whose graphic happens to be
923: blank.@refill
924:
925: Emacs extends the 7-bit ASCII code to an 8-bit code by adding an extra
926: bit to each character. This makes 256 possible command characters. The
927: additional bit is called Meta. Any ASCII character can be made Meta;
928: examples of Meta characters include @kbd{Meta-a} (@kbd{M-a}, for short),
929: @kbd{M-A} (not the same character as @kbd{M-a}, but those two characters
930: normally have the same meaning in Emacs), @kbd{M-@key{RET}}, and
931: @kbd{M-C-a}. For traditional reasons, @kbd{M-C-a} is usually called
932: @kbd{C-M-a}; logically speaking, the order in which the modifier keys
933: @key{CTRL} and @key{META} are mentioned does not matter.@refill
934:
935: @cindex Control
936: @cindex Meta
937: @cindex C-
938: @cindex M-
939: @cindex ESC replacing META key
940: Some terminals have a @key{META} key, and allow you to type Meta
941: characters by holding this key down. Thus, @kbd{Meta-a} is typed by
942: holding down @key{META} and pressing @kbd{a}. The @key{META} key works
943: much like the @key{SHIFT} key. Such a key is not always labeled
944: @key{META}, however, as this function is often a special option for a key
945: with some other primary purpose.@refill
946:
947: If there is no @key{META} key, you
948: can still type Meta characters using two-character sequences starting with
949: @key{ESC}. Thus, to enter @kbd{M-a}, you could type @kbd{@key{ESC} a}. To
950: enter @kbd{C-M-a}, you would type @kbd{@key{ESC} C-a}. @key{ESC} is
951: allowed on terminals with Meta keys, too, in case you have formed a habit
952: of using it.@refill
953:
954: @vindex meta-flag
955: Emacs believes the terminal has a @key{META} key if the variable
956: @code{meta-flag} is non-@code{nil}. Normally this is set automatically
957: according to the termcap entry for your terminal type. However, sometimes
958: the termcap entry is wrong, and then it is useful to set this variable
959: yourself. @xref{Variables}, for how to do this.
960:
961: Emacs buffers also use an 8-bit character set, because bytes have 8 bits,
962: but only the ASCII characters are considered meaningful. ASCII graphic
963: characters in Emacs buffers are displayed with their graphics. @key{LFD}
964: is the same as a newline character; it is displayed by starting a new line.
965: @key{TAB} is displayed by moving to the next tab stop column (usually every
966: 8 columns). Other control characters are displayed as a caret (@samp{^})
967: followed by the non-control version of the character; thus, @kbd{C-a} is
968: displayed as @samp{^A}. Non-ASCII characters 128 and up are displayed with
969: octal escape sequences; thus, character code 243 (octal), also called
970: @kbd{M-#} when used as an input character, is displayed as @samp{\243}.
971:
972: @node Keys, Commands, Characters, Top
973: @section Keys
974:
975: @cindex key
976: @cindex prefix key
977: A @dfn{complete key}---where `key' is short for @dfn{key sequence}---is a
978: sequence of keystrokes that are understood by Emacs as a unit, as a single
979: command (possibly undefined). Most single characters constitute complete
980: keys in the standard Emacs command set; there are also some multi-character
981: keys. Examples of complete keys are @kbd{C-a}, @kbd{X}, @key{RET},
982: @kbd{C-x C-f} and @kbd{C-x 4 C-f}.@refill
983:
984: @kindex C-c
985: @kindex C-x
986: @kindex C-h
987: @kindex ESC
988: A @dfn{prefix key} is a sequence of keystrokes that are the beginning of
989: a complete key, but not a whole one. Prefix keys and complete keys are
990: collectively called @dfn{keys}.
991:
992: A prefix key is the beginning of a series of longer sequences that are
993: valid keys; adding any single character to the end of the prefix gives a
994: valid key, which could be defined as an Emacs command, or could be a prefix
995: itself. For example, @kbd{C-x} is standardly defined as a prefix, so
996: @kbd{C-x} and the next input character combine to make a two-character key.
997: There are 256 different two-character keys starting with @kbd{C-x}, one for
998: each possible second character. Many of these two-character keys starting
999: with @kbd{C-x} are standardly defined as Emacs commands. Notable examples
1000: include @kbd{C-x C-f} and @kbd{C-x s} (@pxref{Files}).
1001:
1002: Adding one character to a prefix key does not have to form a complete
1003: key. It could make another, longer prefix. For example, @kbd{C-x 4} is
1004: itself a prefix that leads to 256 different three-character keys, including
1005: @kbd{C-x 4 f}, @kbd{C-x 4 b} and so on. It would be possible to define one
1006: of those three-character sequences as a prefix, creating a series of
1007: four-character keys, but we did not define any of them this way.@refill
1008:
1009: By contrast, the two-character sequence @kbd{C-f C-k} is not a key,
1010: because the @kbd{C-f} is a complete key in itself. It's impossible to give
1011: @kbd{C-f C-k} an independent meaning as a command as long as @kbd{C-f}
1012: retains its meaning. @kbd{C-f C-k} is two commands.@refill
1013:
1014: All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
1015: @kbd{C-x 4}, and @key{ESC}. But this is not built in; it is just a matter
1016: of Emacs's standard key bindings. In customizing Emacs, you could make
1017: new prefix keys, or eliminate these. @xref{Key Bindings}.@refill
1018:
1019: Whether a sequence is a key can be changed by customization. For
1020: example, if you redefine @kbd{C-f} as a prefix, @kbd{C-f C-k} automatically
1021: becomes a key (complete, unless you define it too as a prefix).
1022: Conversely, if you remove the prefix definition of @kbd{C-x 4}, then
1023: @kbd{C-x 4 f} (or @kbd{C-x 4 @var{anything}}) is no longer a key.
1024:
1025: @node Commands, Entering Emacs, Keys, Top
1026: @section Keys and Commands
1027:
1028: @cindex binding
1029: @cindex customization
1030: @cindex keymap
1031: @cindex function
1032: @cindex command
1033: This manual is full of passages that tell you what particular keys do.
1034: But Emacs does not assign meanings to keys directly. Instead, Emacs
1035: assigns meanings to @dfn{functions}, and then gives keys their meanings by
1036: @dfn{binding} them to functions.
1037:
1038: A function is a Lisp object that can be executed as a program. Usually
1039: it is a Lisp symbol which has been given a function definition; every
1040: symbol has a name, usually made of a few English words separated by dashes,
1041: such as @code{next-line} or @code{forward-word}. It also has a
1042: @dfn{definition} which is a Lisp program; this is what makes the function
1043: do what it does. Only some functions can be the bindings of keys; these
1044: are functions whose definitions use @code{interactive} to specify how to
1045: call them interactively. Such functions are called @dfn{commands}, and
1046: their names are @dfn{command names}. More information on this subject will
1047: appear in the @i{GNU Emacs Lisp Manual} (which is not yet written).
1048:
1049: The bindings between keys and functions are recorded in various tables
1050: called @dfn{keymaps}. @xref{Keymaps}.
1051:
1052: When we say that ``@kbd{C-n} moves down vertically one line'' we are
1053: glossing over a distinction that is irrelevant in ordinary use but is vital
1054: in understanding how to customize Emacs. It is the function
1055: @code{next-line} that is programmed to move down vertically. @kbd{C-n} has
1056: this effect @i{because} it is bound to that function. If you rebind
1057: @kbd{C-n} to the function @code{forward-word} then @kbd{C-n} will move
1058: forward by words instead. Rebinding keys is a common method of
1059: customization.@refill
1060:
1061: In the rest of this manual, we usually ignore this subtlety to keep
1062: things simple. To give the customizer the information he needs, we
1063: state the name of the command which really does the work in parentheses
1064: after mentioning the key that runs it. For example, we will say that
1065: ``The command @kbd{C-n} (@code{next-line}) moves point vertically down,''
1066: meaning that @code{next-line} is a command that moves vertically down
1067: and @kbd{C-n} is a key that is standardly bound to it.
1068:
1069: @cindex variables
1070: While we are on the subject of information for customization only, it's a
1071: good time to tell you about @dfn{variables}. Often the description of a
1072: command will say, ``To change this, set the variable @code{mumble-foo}.''
1073: A variable is a name used to remember a value. Most of the variables
1074: documented in this manual exist just to facilitate customization: some
1075: command or other part of Emacs examines the variable and behaves
1076: differently accordingly. Until you are interested in customizing, you can
1077: ignore the information about variables. When you are ready to be
1078: interested, read the basic information on variables, and then the
1079: information on individual variables will make sense. @xref{Variables}.
1080:
1081: @node Entering Emacs, Exiting, Commands, Top
1082: @chapter Entering and Exiting Emacs
1083: @cindex entering Emacs
1084:
1085: The usual way to invoke Emacs is just to type @kbd{emacs @key{RET}} at
1086: the shell. Emacs clears the screen and then displays an initial advisor
1087: message and copyright notice. You can begin typing Emacs commands
1088: immediately afterward.
1089:
1090: Some operating systems insist on discarding all type-ahead when Emacs
1091: starts up; they give Emacs no way to prevent this. Therefore, it is
1092: wise to wait until Emacs clears the screen before typing your first
1093: editing command.
1094:
1095: @vindex initial-major-mode
1096: Before Emacs reads the first command, you have not had a chance to give a
1097: command to specify a file to edit. But Emacs must always have a current
1098: buffer for editing. In an attempt to do something useful, Emacs presents a
1099: buffer named @samp{*scratch*} which is in Lisp Interaction mode; you can
1100: use it to type Lisp expressions and evaluate them, or you can ignore that
1101: capability and simply doodle. (You can specify a different major mode for
1102: this buffer by setting the variable @code{initial-major-mode} in your init
1103: file. @xref{Init File}.)
1104:
1105: It is also possible to specify files to be visited, Lisp files to be
1106: loaded, and functions to be called, by giving Emacs arguments in the
1107: shell command line. @xref{Command Switches}.
1108:
1109: @node Exiting, Command Switches, Entering Emacs, Top
1110: @section Exiting Emacs
1111: @cindex exiting
1112: @cindex killing Emacs
1113: @cindex suspending
1114:
1115: There are two commands for exiting Emacs because there are two kinds of
1116: exiting: @dfn{suspending} Emacs and @dfn{killing} Emacs. @dfn{Suspending} means
1117: stopping Emacs temporarily and returning control to its superior (usually
1118: the shell), allowing you to resume editing later in the same Emacs job,
1119: with the same files, same kill ring, same undo history, and so on. This is
1120: the usual way to exit. @dfn{Killing} Emacs means destroying the Emacs job.
1121: You can run Emacs again later, but you will get a fresh Emacs; there is no
1122: way to resume the same editing session after it has been killed.
1123:
1124: @table @kbd
1125: @item C-z
1126: Suspend Emacs (@code{suspend-emacs}).
1127: @item C-x C-c
1128: Kill Emacs (@code{save-buffers-kill-emacs}).
1129: @end table
1130:
1131: @kindex C-z
1132: @findex suspend-emacs
1133: To suspend Emacs, type @kbd{C-z} (@code{suspend-emacs}). This takes
1134: you back to the shell from which you invoked Emacs. You can resume
1135: Emacs with the command @code{%emacs} if you are using the C shell.
1136:
1137: On systems that do not permit programs to be suspended, @kbd{C-z} runs an
1138: inferior shell that communicates directly with the terminal, and Emacs
1139: waits until you exit the subshell. The only way on these systems to get
1140: back to the shell from which Emacs was run (to log out, for example) is to
1141: kill Emacs. @kbd{C-d} or @code{exit} are typical commands to exit a
1142: subshell.
1143:
1144: @kindex C-x C-c
1145: @findex save-buffers-kill-emacs
1146: To kill Emacs, type @kbd{C-x C-c} (@code{save-buffers-kill-emacs}). A
1147: two-character key is used for this to make it harder to type. Unless a
1148: numeric argument is used, this command first offers to save any modified
1149: buffers. If you do not save them all, it asks for reconfirmation with
1150: @kbd{yes} before killing Emacs, since any changes not saved before that will be
1151: lost forever. Also, if any subprocesses are still running, @kbd{C-x C-c}
1152: asks for confirmation about them, since killing Emacs will kill the
1153: subprocesses immediately.
1154:
1155: In most programs running on Unix, certain characters may instantly
1156: suspend or kill the program. (In Berkeley Unix these characters are
1157: normally @kbd{C-z} and @kbd{C-c}.) @b{This Unix feature is turned off
1158: while you are in Emacs.} The meanings of @kbd{C-z} and @kbd{C-x C-c} as
1159: keys in Emacs were inspired by the standard Berkeley Unix meanings of
1160: @kbd{C-z} and @kbd{C-c}, but that is their only relationship with
1161: Unix. You could customize these keys to do anything (@pxref{Keymaps}).
1162:
1163: @c ??? What about system V here?
1164:
1165: @node Command Switches, Basic, Exiting, Top
1166: @section Command Line Switches and Arguments
1167: @cindex command line arguments
1168: @cindex arguments (from shell)
1169:
1170:
1171: GNU Emacs supports command line arguments to request various actions
1172: when invoking Emacs. These are for compatibility with other editors and
1173: for sophisticated activities. They are not needed for ordinary editing
1174: with Emacs, so new users can skip this section.
1175:
1176: You may be used to using command line arguments with other editors
1177: to specify which file to edit. That's because many other editors are
1178: designed to be started afresh each time you want to edit. You
1179: edit one file and then exit the editor. The next time you want to edit
1180: either another file or the same one, you must run the editor again.
1181: With these editors, it makes sense to use a command line argument
1182: to say which file to edit.
1183:
1184: The recommended way to use GNU Emacs is to start it only once, just after
1185: you log in, and do all your editing in the same Emacs process. Each time
1186: you want to edit a different file, you visit it with the existing Emacs,
1187: which eventually comes to have many files in it ready for editing. Usually
1188: you do not kill the Emacs until you are about to log out.
1189:
1190: When files are nearly always read by typing commands to an editor that is
1191: already running, command line arguments for specifying a file when the
1192: editor is started are seldom needed.
1193:
1194: Emacs accepts command-line arguments that specify files to visit,
1195: functions to call, and other activities and operating modes.
1196:
1197: The command arguments are processed in the order they appear in the
1198: command argument list; however, certain arguments (the ones in the second
1199: table) must be at the front of the list if they are used.
1200:
1201: Here are the arguments allowed:
1202:
1203: @table @samp
1204: @item @var{file}
1205: Visit @var{file} using @code{find-file}. @xref{Visiting}.
1206:
1207: @item +@var{linenum} @var{file}
1208: Visit @var{file} using @code{find-file}, then go to line number
1209: @var{linenum} in it.
1210:
1211: @item -l @var{file}
1212: @itemx -load @var{file}
1213: Load a file @var{file} of Lisp code with the function @code{load}.
1214: @xref{Lisp Libraries}.
1215:
1216: @item -f @var{function}
1217: @itemx -funcall @var{function}
1218: Call Lisp function @var{function} with no arguments.
1219:
1220: @item -i @var{file}
1221: @itemx -insert @var{file}
1222: Insert the contents of @var{file} into the current buffer.
1223: This is like what @kbd{M-x insert-buffer} does; @xref{Misc File Ops}.
1224:
1225: @item -kill
1226: Exit from Emacs without asking for confirmation.
1227: @end table
1228:
1229: The remaining switches are recognized only at the beginning of the
1230: command line. If more than one of them appears, they must appear in the
1231: order that they appear in this table.
1232:
1233: @table @samp
1234: @item -t @var{device}
1235: Use @var{device} as the device for terminal input and output.
1236:
1237: @item -d @var{display}
1238: When running with the X window system, use the display named @var{display}
1239: to make the window that serves as Emacs's terminal.
1240:
1241: @cindex batch mode
1242: @item -batch
1243: Run Emacs in @dfn{batch mode}, which means that the text being edited is
1244: not displayed and the standard Unix interrupt characters such as @kbd{C-z}
1245: and @kbd{C-c} continue to have their normal effect. Emacs in batch mode
1246: outputs to @code{stdout} only what would normally be printed in the echo
1247: area under program control.
1248:
1249: Batch mode is used for running programs written in Emacs Lisp from
1250: shell scripts, makefiles, and so on. Normally the @samp{-l} switch
1251: or @samp{-f} switch will be used as well, to invoke a Lisp program
1252: to do the batch processing.
1253:
1254: @samp{-batch} implies @samp{-q} (do not load an init file). It also causes
1255: Emacs to kill itself after all command switches have been processed. In
1256: addition, auto-saving is not done except in buffers for which it has been
1257: explicitly requested.
1258:
1259: @item -q
1260: @itemx -no-init-file
1261: Do not load your Emacs init file @file{~/.emacs}.
1262:
1263: @item -u @var{user}
1264: @itemx -user @var{user}
1265: Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
1266: your own.
1267: @end table
1268:
1269: @vindex command-line-args
1270: Note that the init file can get access to the command line argument
1271: values as the elements of a list in the variable @code{command-line-args}.
1272: (The arguments in the second table above will already have been processed
1273: and will not be in the list.) The init file can override the normal
1274: processing of the other arguments by setting this variable.
1275:
1276: One way to use command switches is to visit many files automatically:
1277:
1278: @example
1279: emacs *.c
1280: @end example
1281:
1282: @noindent
1283: passes each @code{.c} file as a separate argument to Emacs, so that Emacs
1284: visits each file (@pxref{Visiting}).
1285:
1286: Here is an advanced example that assumes you have a Lisp program
1287: file called @file{hack-c-program.el} which, when loaded, performs some
1288: useful operation on current buffer, expected to be a C program.
1289:
1290: @example
1291: emacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
1292: @end example
1293:
1294: @noindent
1295: Here Emacs is told to visit @file{foo.c}, load @file{hack-c-program.el}
1296: (which makes changes in the visited file), save @file{foo.c} (note that
1297: @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
1298: then exit to the shell that this command was done with. @samp{-batch}
1299: guarantees there will be no problem redirecting output to @file{log},
1300: because Emacs will not assume that it has a display terminal to work with.
1301:
1302: @node Basic, Undo, Command Switches, Top
1303: @chapter Basic Editing Commands
1304:
1305: @kindex C-h t
1306: @findex help-with-tutorial
1307: We now give the basics of how to enter text, make corrections, and
1308: save the text in a file. If this material is new to you, you might
1309: learn it more easily by running the Emacs learn-by-doing tutorial. To
1310: do this, type @kbd{Control-h t} (@code{help-with-tutorial}).
1311:
1312: @section Inserting Text
1313:
1314: @cindex insertion
1315: @cindex point
1316: @cindex cursor
1317: @cindex graphic characters
1318: To insert printing characters into the text you are editing, just type
1319: them. This inserts the character into the buffer at the cursor (that is,
1320: at @dfn{point}; @pxref{Point}). The cursor moves forward. Any characters
1321: after the cursor move forward too. If the text in the buffer is
1322: @samp{FOOBAR}, with the cursor before the @samp{B}, then if you type
1323: @kbd{XX}, you get @samp{FOOXXBAR}, with the cursor still before the
1324: @samp{B}.
1325:
1326: @kindex DEL
1327: @cindex deletion
1328: To @dfn{delete} text you have just inserted, use @key{DEL}. @key{DEL}
1329: deletes the character @var{before} the cursor (not the one that the cursor
1330: is on top of or under; that is the character @var{after} the cursor). The
1331: cursor and all characters after it move backwards. Therefore, if you type
1332: a printing character and then type @key{DEL}, they cancel out.
1333:
1334: @kindex RET
1335: @cindex newline
1336: To end a line and start typing a new one, type @key{RET}. This inserts
1337: a newline character in the buffer. If point is in the middle of a line,
1338: @key{RET} splits the line. Typing @key{DEL} when the cursor is at the
1339: beginning of a line rubs out the newline before the line, thus joining the
1340: line with the preceding line.
1341:
1342: Emacs will split lines automatically when they become too long, if you
1343: turn on a special mode called @dfn{Auto Fill} mode. @xref{Filling}, for
1344: how to use Auto Fill mode.
1345:
1346: @findex delete-backward-char
1347: @findex newline
1348: @findex self-insert
1349: Customization information: @key{DEL} in most modes runs the command named
1350: @code{delete-backward-char}; @key{RET} runs the command @code{newline}, and
1351: self-inserting printing characters run the command @code{self-insert},
1352: which inserts whatever character was typed to invoke it. Some major modes
1353: rebind @key{DEL} to other commands.
1354:
1355: @cindex quoting
1356: @kindex C-q
1357: @findex quoted-insert
1358: Direct insertion works for printing characters and @key{SPC}, but other
1359: characters act as editing commands and do not insert themselves. If you
1360: need to insert a control character or a character whose code is above 200
1361: octal, you must @dfn{quote} it by typing the character @kbd{control-q}
1362: (@code{quoted-insert}) first. There are two ways to use @kbd{C-q}:@refill
1363:
1364: @itemize @bullet
1365: @item
1366: @kbd{Control-q} followed by any non-graphic character (even @kbd{C-g})
1367: inserts that character.
1368: @item
1369: @kbd{Control-q} followed by three octal digits inserts the character
1370: with the specified character code.
1371: @end itemize
1372:
1373: @noindent
1374: A numeric argument to @kbd{C-q} specifies how many copies of the
1375: quoted character should be inserted (@pxref{Arguments}).
1376:
1377: If you prefer to have text characters replace (overwrite) existing
1378: text rather than shove it to the right, you can enable Overwrite mode,
1379: a minor mode. @xref{Minor Modes}.
1380:
1381: @section Changing the Location of Point
1382:
1383: To do more than insert characters, you have to know how to move
1384: point (@pxref{Point}). Here are a few of the commands for doing that.
1385:
1386: @kindex C-a
1387: @kindex C-e
1388: @kindex C-f
1389: @kindex C-b
1390: @kindex C-n
1391: @kindex C-p
1392: @kindex C-l
1393: @kindex C-t
1394: @kindex M->
1395: @kindex M-<
1396: @kindex M-r
1397: @findex beginning-of-line
1398: @findex end-of-line
1399: @findex forward-char
1400: @findex backward-char
1401: @findex next-line
1402: @findex previous-line
1403: @findex recenter
1404: @findex transpose-chars
1405: @findex beginning-of-buffer
1406: @findex end-of-buffer
1407: @findex goto-char
1408: @findex goto-line
1409: @findex move-to-window-line
1410: @table @kbd
1411: @item C-a
1412: Move to the beginning of the line (@code{beginning-of-line}).
1413: @item C-e
1414: Move to the end of the line (@code{end-of-line}).
1415: @item C-f
1416: Move forward one character (@code{forward-char}).
1417: @item C-b
1418: Move backward one character (@code{backward-char}).
1419: @item M-f
1420: Move forward one word (@code{forward-word}).
1421: @item M-b
1422: Move backward one word (@code{backward-word}).
1423: @item C-n
1424: Move down one line, vertically (@code{next-line}). This command
1425: attempts to keep the horizontal position unchanged, so if you start in
1426: the middle of one line, you end in the middle of the next. When on
1427: the last line of text, @kbd{C-n} creates a new line and moves onto it.
1428: @item C-p
1429: Move up one line, vertically (@code{previous-line}).
1430: @item C-l
1431: Clear the screen and reprint everything (@code{recenter}). Text moves
1432: on the screen to bring point to the center of the window.
1433: @item M-r
1434: Move point to left margin on the line halfway down the screen or
1435: window (@code{move-to-window-line}). Text does not move on the
1436: screen. A numeric argument says how many screen lines down from the
1437: top of the window (zero for the top). A negative argument counts from
1438: the bottom (@minus{}1 for the bottom).
1439: @item C-t
1440: Transpose two characters, the ones before and after the cursor
1441: (@code{transpose-chars}).
1442: @item M-<
1443: Move to the top of the buffer (@code{beginning-of-buffer}). With
1444: numeric argument @var{n}, move to @var{n}/10 of the way from the top.
1445: @xref{Arguments}, for more information on numeric arguments.@refill
1446: @item M->
1447: Move to the end of the buffer (@code{end-of-buffer}).
1448: @item M-x goto-char
1449: Read a number @var{n} and move cursor to character number @var{n}.
1450: Position 1 is the beginning of the buffer.
1451: @item M-x goto-line
1452: Read a number @var{n} and move cursor to line number @var{n}. Line 1
1453: is the beginning of the buffer.
1454: @item C-x C-n
1455: @findex set-goal-column
1456: Use the current column of point as the @dfn{semipermanent goal column} for
1457: @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). Henceforth, those
1458: commands always move to this column in each line moved into, or as
1459: close as possible given the contents of the line. This goal column remains
1460: in effect until canceled.
1461: @item C-u C-x C-n
1462: Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} once
1463: again try to avoid changing the horizontal position, as usual.
1464: @end table
1465:
1466: @vindex track-eol
1467: If you set the variable @code{track-eol} to a non-@code{nil} value, then
1468: @kbd{C-n} and @kbd{C-p} when at the end of the starting line move to the
1469: end of the line. Normally, @code{track-eol} is @code{nil}.
1470:
1471: @section Erasing Text
1472:
1473: @table @kbd
1474: @item @key{DEL}
1475: Delete the character before the cursor (@code{delete-backward-char}).
1476: @item C-d
1477: Delete the character after the cursor (@code{delete-char}).
1478: @item C-k
1479: Kill to the end of the line (@code{kill-line}).
1480: @item M-d
1481: Kill forward to the end of the next word (@code{kill-word}).
1482: @item M-@key{DEL}
1483: Kill back to the beginning of the previous word
1484: (@code{backward-kill-word}).
1485: @end table
1486:
1487: You already know about the @key{DEL} key which deletes the character
1488: before the cursor. Another key, @kbd{Control-d}, deletes the character
1489: after the cursor, causing the rest of the text on the line to shift left.
1490: If @kbd{Control-d} is typed at the end of a line, that line and the next
1491: line are joined together.
1492:
1493: To erase a larger amount of text, use the @kbd{Control-k} key, which
1494: kills a line at a time. If @kbd{C-k} is done at the beginning or middle of
1495: a line, it kills all the text up to the end of the line. If @kbd{C-k} is
1496: done at the end of a line, it joins that line and the next line.
1497:
1498: @xref{Killing}, for more flexible ways of killing text.
1499:
1500: @section Files
1501:
1502: @cindex files
1503: The commands above are sufficient for creating and altering text in an
1504: Emacs buffer; the more advanced Emacs commands just make things easier.
1505: But to keep any text permanently you must put it in a @dfn{file}. Files
1506: are named units of text which are stored by the operating system for you to
1507: retrieve later by name. To look at or use the contents of a file in any
1508: way, including editing the file with Emacs, you must specify the file name.
1509:
1510: Consider a file named @file{/usr/rms/foo.c}. In Emacs, to begin editing
1511: this file, type
1512:
1513: @example
1514: C-x C-f /usr/rms/foo.c @key{RET}
1515: @end example
1516:
1517: @noindent
1518: Here the file name is given as an @dfn{argument} to the command @kbd{C-x
1519: C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to
1520: read the argument, and you type @key{RET} to terminate the argument
1521: (@pxref{Minibuffer}).@refill
1522:
1523: Emacs obeys the command by @dfn{visiting} the file: creating a buffer,
1524: copying the contents of the file into the buffer, and then displaying the
1525: buffer for you to edit. You can make changes in it, and then @dfn{save}
1526: the file by typing @kbd{C-x C-s} (@code{save-buffer}). This makes the
1527: changes permanent by copying the altered contents of the buffer back into
1528: the file @file{/usr/rms/foo.c}. Until then, the changes are only inside
1529: your Emacs, and the file @file{foo.c} is not changed.@refill
1530:
1531: To create a file, just visit the file with @kbd{C-x C-f} as if it already
1532: existed. Emacs will make an empty buffer in which you can insert the text
1533: you want to put in the file. When you save your text with @kbd{C-x C-s},
1534: the file will be created.
1535:
1536: Of course, there is a lot more to learn about using files. @xref{Files}.
1537:
1538: @section Help
1539:
1540: If you forget what a key does, you can find out with the Help character,
1541: which is @kbd{C-h}. Type @kbd{C-h k} followed by the key you want to know
1542: about; for example, @kbd{C-h k C-n} tells you all about what @kbd{C-n}
1543: does. @kbd{C-h} is a prefix key; @kbd{C-h k} is just one of its
1544: subcommands (the command @code{describe-key}). The other subcommands of
1545: @kbd{C-h} provide different kinds of help. Type @kbd{C-h} three times
1546: to get a description of all the help facilities. @xref{Help}.@refill
1547:
1548: @menu
1549: * Blank Lines:: Commands to make or delete blank lines.
1550: * Continuation Lines:: Lines too wide for the screen.
1551: * Position Info:: What page, line, row, or column is point on?
1552: * Arguments:: Numeric arguments for repeating a command.
1553: @end menu
1554:
1555: @page
1556: @node Blank Lines, Continuation Lines, Basic, Basic
1557: @section Blank Lines
1558:
1559: Here are special commands and techniques for putting in and taking out
1560: blank lines.
1561:
1562: @c widecommands
1563: @table @kbd
1564: @item C-o
1565: Insert one or more blank lines after the cursor (@code{open-line}).
1566: @item C-x C-o
1567: Delete all but one of many consecutive blank lines
1568: (@code{delete-blank-lines}).
1569: @end table
1570:
1571: @kindex C-o
1572: @kindex C-x C-o
1573: @cindex blank lines
1574: @findex open-line
1575: @findex delete-blank-lines
1576: When you want to insert a new line of text before an existing line, you
1577: can do it by typing the new line of text, followed by @key{RET}. However,
1578: it may be easier to see what you are doing if you first make a blank line
1579: and then insert the desired text into it. This is easy to do using the key
1580: @kbd{C-o} (@code{open-line}), which inserts a newline after point but leaves
1581: point in front of the newline. After @kbd{C-o}, type the text for the new
1582: line. @kbd{C-o F O O} has the same effect as @kbd{F O O @key{RET}}, except for
1583: the final location of point.
1584:
1585: You can make several blank lines by typing @kbd{C-o} several times, or by
1586: giving it an argument to tell it how many blank lines to make.
1587: @xref{Arguments}, for how.
1588:
1589: If you have many blank lines in a row and want to get rid of them, use
1590: @kbd{C-x C-o} (@code{delete-blank-lines}). When point is on a blank line which
1591: is adjacent to at least one other blank line, @kbd{C-x C-o} deletes all but
1592: one of the consecutive blank lines, leaving exactly one. With point on a
1593: blank line with no other blank line adjacent to it, the sole blank line is
1594: deleted, leaving none. When point is on a nonblank line, @kbd{C-x C-o}
1595: deletes any blank lines following that nonblank line.
1596:
1597: @node Continuation Lines, Position Info, Blank Lines, Basic
1598: @section Continuation Lines
1599:
1600: @cindex continuation line
1601: If you add too many characters to one line, without breaking it with a
1602: @key{RET}, the line will grow to occupy two (or more) lines on the screen,
1603: with a @samp{\} at the extreme right margin of all but the last of them.
1604: The @samp{\} says that the following screen line is not really a distinct
1605: line in the text, but just the @dfn{continuation} of a line too long to fit
1606: the screen. Sometimes it is nice to have Emacs insert newlines
1607: automatically when a line gets too long; for this, use Auto Fill mode
1608: (@pxref{Filling}).
1609:
1610: @vindex truncate-lines
1611: @cindex truncation
1612: Instead of continuation, long lines can be displayed by @dfn{truncation}.
1613: This means that all the characters that do not fit in the width of the
1614: screen or window do not appear at all. They remain in the buffer,
1615: temporarily invisible. @samp{$} is used in the last column instead of
1616: @samp{\} to inform you that truncation is in effect.
1617:
1618: Continuation can be turned off for a particular buffer by setting the
1619: variable @code{truncate-lines} to non-@code{nil} in that buffer.
1620: Truncation instead of continuation also happens whenever horizontal
1621: scrolling is in use, and optionally whenever side-by-side windows are in
1622: use (@pxref{Windows}). Altering the value of @code{truncate-lines} makes
1623: it local to the current buffer; until that time, the default value is in
1624: effect. The default is initially @code{nil}. @xref{Locals}.@refill
1625:
1626: @node Position Info, Arguments, Continuation Lines, Basic
1627: @section Cursor Position Information
1628:
1629: If you are accustomed to other display editors, you may be surprised that
1630: Emacs does not always display the page number or line number of point in
1631: the mode line. This is because the text is stored in a way that makes it
1632: difficult to compute this information. Displaying them all the time would
1633: be intolerably slow. They are not needed very often in Emacs anyway,
1634: but there are commands to compute them and print them.
1635:
1636: @table @kbd
1637: @item M-x what-page
1638: Print page number of point, and line number within page.
1639: @item M-x what-line
1640: Print line number of point in the buffer.
1641: @item M-=
1642: Print number of lines in the current region (@code{count-lines-region}).
1643: @item C-x =
1644: Print character code of character after point, character position of
1645: point, and column of point (@code{what-cursor-position}).
1646: @end table
1647:
1648: @findex what-page
1649: @findex what-line
1650: @cindex line number
1651: There are two commands for printing line numbers. @kbd{M-x what-line}
1652: counts lines from the beginning of the file and prints the line number
1653: point is on. The first line of the file is line number 1. These numbers
1654: can be used as arguments to @kbd{M-x goto-line}. By contrast, @kbd{M-x
1655: what-page} counts pages from the beginning of the file, and counts lines
1656: within the page, printing both of them. @xref{Pages}.
1657:
1658: @kindex M-=
1659: @findex count-lines-region
1660: While on this subject, we might as well mention @kbd{M-=} (@code{count-lines-region}),
1661: which prints the number of lines in the region (@pxref{Mark}).
1662: @xref{Pages}, for the command @kbd{C-x l} which counts the lines in the
1663: current page.
1664:
1665: @kindex C-x =
1666: @findex what-cursor-position
1667: The command @kbd{C-x =} (@code{what-cursor-position}) can be used to find out
1668: the column that the cursor is in, and other miscellaneous information about
1669: point. It prints a line in the echo area that looks like this:
1670:
1671: @example
1672: Char: x (0170) point=65986 of 563027(12%) x=44
1673: @end example
1674:
1675: @noindent
1676: (In fact, this is the output produced when point is before the @samp{x=44}
1677: in the example.)
1678:
1679: The two values after @samp{Char:} describe the character following point,
1680: first by showing it and second by giving its octal character code.
1681:
1682: @samp{point=} is followed by the position of point expressed as a character
1683: count. The front of the buffer counts as position 1, one character later
1684: as 2, and so on. The next, larger number is the total number of characters
1685: in the buffer. Afterward in parentheses comes the position expressed as a
1686: percentage of the total size.
1687:
1688: @samp{x=} is followed by the horizontal position of point, in columns from the
1689: left edge of the window.
1690:
1691: If the buffer has been narrowed, making some of the text at the beginning and
1692: the end temporarily invisible, @kbd{C-x =} prints additional text describing the
1693: current visible range. For example, it might say
1694:
1695: @smallexample
1696: Char: x (0170) point=65986 of 563025(12%) <65102 - 68533> x=44
1697: @end smallexample
1698:
1699: @noindent
1700: where the two extra numbers give the smallest and largest character position
1701: that point is allowed to assume. The characters between those two positions
1702: are the visible ones. @xref{Narrowing}.
1703:
1704: If point is at the end of the buffer (or the end of the visible part),
1705: @kbd{C-x =} omits any description of the character after point.
1706: The output looks like
1707:
1708: @smallexample
1709: point=563026 of 563025(100%) x=0
1710: @end smallexample
1711:
1712: @node Arguments,, Position Info, Basic
1713: @section Numeric Arguments
1714: @cindex numeric arguments
1715:
1716: Any Emacs command can be given a @dfn{numeric argument}. Some commands
1717: interpret the argument as a repetition count. For example, giving an
1718: argument of ten to the key @kbd{C-f} (the command @code{forward-char}, move
1719: forward one character) moves forward ten characters. With these commands,
1720: no argument is equivalent to an argument of one. Negative arguments are
1721: allowed. Often they tell a command to move or act backwards.
1722:
1723: @kindex M-1
1724: @kindex M-@t{-}
1725: @findex digit-argument
1726: @findex negative-argument
1727: If your terminal keyboard has a @key{META} key, the easiest way to
1728: specify a numeric argument is to type digits and/or a minus sign while
1729: holding down the the @key{META} key. For example,
1730: @example
1731: M-5 C-n
1732: @end example
1733: @noindent
1734: would move down five lines. The characters @kbd{Meta-1}, @kbd{Meta-2}, and
1735: so on, as well as @kbd{Meta--}, do this because they are keys bound to
1736: commands (@code{digit-argument} and @code{negative-argument}) that are
1737: defined to contribute to an argument for the next command.
1738:
1739: @kindex C-u
1740: @findex universal-argument
1741: Another way of specifying an argument is to use the @kbd{C-u}
1742: (@code{universal-argument}) command followed by the digits of the argument.
1743: With @kbd{C-u}, you can type the argument digits without holding
1744: down shift keys. To type a negative argument, start with a minus sign.
1745: Just a minus sign normally means @minus{}1. @kbd{C-u} works on all terminals.
1746:
1747: @kbd{C-u} followed by a character which is neither a digit nor a minus
1748: sign has the special meaning of ``multiply by four''. It multiplies the
1749: argument for the next command by four. @kbd{C-u} twice multiplies it by
1750: sixteen. Thus, @kbd{C-u C-u C-f} moves forward sixteen characters. This
1751: is a good way to move forward ``fast'', since it moves about 1/5 of a line
1752: in the usual size screen. Other useful combinations are @kbd{C-u C-n},
1753: @kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u C-u
1754: C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four
1755: lines).@refill
1756:
1757: Some commands care only about whether there is an argument, and not about
1758: its value. For example, the command @kbd{M-q} (@code{fill-paragraph}) with
1759: no argument fills text; with an argument, it justifies the text as well.
1760: (@xref{Filling}, for more information on @kbd{M-q}.) Just @kbd{C-u} is a
1761: handy way of providing an argument for such commands.
1762:
1763: Some commands use the value of the argument as a repeat count, but do
1764: something peculiar when there is no argument. For example, the command
1765: @kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines,
1766: including their terminating newlines. But @kbd{C-k} with no argument is
1767: special: it kills the text up to the next newline, or, if point is right at
1768: the end of the line, it kills the newline itself. Thus, two @kbd{C-k}
1769: commands with no arguments can kill a nonblank line, just like @kbd{C-k}
1770: with an argument of one. (@xref{Killing}, for more information on
1771: @kbd{C-k}.)@refill
1772:
1773: A few commands treat a plain @kbd{C-u} differently from an ordinary
1774: argument. A few others may treat an argument of just a minus sign
1775: differently from an argument of @minus{}1. These unusual cases will be described
1776: when they come up; they are always for reasons of convenience of use of the
1777: individual command.
1778:
1779: @c section Autoarg Mode
1780: @ignore
1781: @cindex autoarg mode
1782: Users of ASCII keyboards may prefer to use Autoarg mode. Autoarg mode
1783: means that you don't need to type C-U to specify a numeric argument.
1784: Instead, you type just the digits. Digits followed by an ordinary
1785: inserting character are themselves inserted, but digits followed by an
1786: Escape or Control character serve as an argument to it and are not
1787: inserted. A minus sign can also be part of an argument, but only at the
1788: beginning. If you type a minus sign following some digits, both the digits
1789: and the minus sign are inserted.
1790:
1791: To use Autoarg mode, set the variable Autoarg Mode nonzero.
1792: @xref{Variables}.
1793:
1794: Autoargument digits echo at the bottom of the screen; the first nondigit
1795: causes them to be inserted or uses them as an argument. To insert some
1796: digits and nothing else, you must follow them with a Space and then rub it
1797: out. C-G cancels the digits, while Delete inserts them all and then rubs
1798: out the last.
1799: @end ignore
1800:
1801: @node Undo, Minibuffer, Basic, Top
1802: @chapter Undoing Changes
1803: @cindex undo
1804: @cindex mistakes, correcting
1805:
1806: Emacs allows all changes made in the text of a buffer to be undone,
1807: up to a certain amount of change (8000 characters). Each buffer records
1808: changes individually, and the undo command always applies to the
1809: current buffer. Usually each editing command makes a separate entry
1810: in the undo records, but some commands such as @code{query-replace}
1811: make many entries, and very simple commands such as self-inserting
1812: characters are often grouped to make undoing less tedious.
1813:
1814: @table @kbd
1815: @item C-x u
1816: Undo one batch of changes (usually, one command worth) (@code{undo}).
1817: @item C-_
1818: The same.
1819: @end table
1820:
1821: @kindex C-x u
1822: @kindex C-_
1823: @findex undo
1824: The command @kbd{C-x u} or @kbd{C-_} is how you undo. The first time you give
1825: this command, it undoes the last change. Point moves to the text
1826: affected by the undo, so you can see what was undone.
1827:
1828: Consecutive repetitions of the @kbd{C-_} or @kbd{C-x u} commands undo earlier
1829: and earlier changes, back to the limit of what has been recorded. If all
1830: recorded changes have already been undone, the undo command prints an error
1831: message and does nothing.
1832:
1833: Any command other than an undo command breaks the sequence of undo
1834: commands. Starting at this moment, the previous undo commands are
1835: considered ordinary changes that can themselves be undone. Thus, you can
1836: redo changes you have undone by typing @kbd{C-f} or any other command that
1837: will have no important effect, and then using more undo commands.
1838:
1839: If you notice that a buffer has been modified accidentally, the easiest
1840: way to recover is to type @kbd{C-_} repeatedly until the stars disappear
1841: from the front of the mode line. At this time, all the modifications you
1842: made have been cancelled. If you do not remember whether you changed the
1843: buffer deliberately, type @kbd{C-_} once, and when you see the last change
1844: you made undone, you will remember why you made it. If it was an accident,
1845: leave it undone. If it was deliberate, redo the change as described in the
1846: preceding paragraph.
1847:
1848: Whenever an undo command makes the stars disappear from the mode line,
1849: it means that the buffer contents are the same as they were when the
1850: file was last read in or saved.
1851:
1852: Not all buffers record undo information. Buffers whose names start with
1853: spaces don't; these buffers are used internally by Emacs and its extensions
1854: to hold text that users don't normally look at or edit. Also, minibuffers,
1855: help buffers and documentation buffers don't record undo information.
1856:
1857: At most 8000 or so characters of deleted or modified text can be
1858: remembered in any one buffer for reinsertion by the undo command. Also,
1859: there is a limit on the number of individual insert, delete or change
1860: actions that can be remembered.
1861:
1862: The reason the @code{undo} command has two keys, @kbd{C-x u} and @kbd{C-_}, set
1863: up to run it is that it is worthy of a single-character key, but the way to
1864: type @kbd{C-_} on some keyboards is not obvious. @kbd{C-x u} is an alternative
1865: you can type in the same fashion on any terminal.
1866:
1867: @node Minibuffer, M-x, Undo, Top
1868: @chapter The Minibuffer
1869: @cindex minibuffer
1870:
1871: The @dfn{minibuffer} is the facility used by Emacs commands to read
1872: arguments more complicated than a single number. Minibuffer arguments can
1873: be file names, buffer names, Lisp function names, Emacs command names, Lisp
1874: expressions, and many other things, depending on the command reading the
1875: argument. The usual Emacs editing commands can be used in the minibuffer
1876: to edit the argument.
1877:
1878: @cindex prompt
1879: When the minibuffer is in use, it appears in the echo area, and the
1880: terminal's cursor moves there. The beginning of the minibuffer line
1881: displays a @dfn{prompt} which says what kind of input you should supply and
1882: how it will be used. Often this prompt is derived from the name of the
1883: command that the argument is for. The prompt normally ends with a colon.
1884:
1885: @cindex default argument
1886: Sometimes a @dfn{default argument} appears in parentheses after the
1887: colon; it too is part of the prompt. The default will be used as the
1888: argument value if you enter an empty argument (e.g., just type @key{RET}).
1889: For example, commands that read buffer names always show a default, which
1890: is the name of the buffer that will be used if you type just @key{RET}.
1891:
1892: @kindex C-g
1893: The simplest way to give a minibuffer argument is to type the text you
1894: want, terminated by @key{RET} which exits the minibuffer. You can get out
1895: of the minibuffer, canceling the command that it was for, by typing
1896: @kbd{C-g}.
1897:
1898: Since the minibuffer uses the screen space of the echo area, it can
1899: conflict with other ways Emacs customarily uses the echo area. Here is how
1900: Emacs handles such conflicts:
1901:
1902: @itemize @bullet
1903: @item
1904: If a command gets an error while you are in the minibuffer, this does
1905: not cancel the minibuffer. However, the echo area is needed for the
1906: error message and therefore the minibuffer itself is hidden for a
1907: while. It comes back after a few seconds, or as soon as you type
1908: anything.
1909:
1910: @item
1911: If in the minibuffer you use a command whose purpose is to print a
1912: message in the echo area, such as @kbd{C-x =}, the message is printed
1913: normally, and the minibuffer is hidden for a while. It comes back
1914: after a few seconds, or as soon as you type anything.
1915:
1916: @item
1917: Echoing of keystrokes does not take place while the minibuffer is in
1918: use.
1919: @end itemize
1920:
1921: @menu
1922: * File: Minibuffer File. Entering file names with the minibuffer.
1923: * Edit: Minibuffer Edit. How to edit in the minibuffer.
1924: * Completion:: An abbreviation facility for minibuffer input.
1925: * Repetition:: Re-executing commands that used the minibuffer.
1926: @end menu
1927:
1928: @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer
1929: @section Minibuffers for File Names
1930:
1931: Sometimes the minibuffer starts out with text in it. For example, when
1932: you are supposed to give a file name, the minibuffer starts out containing
1933: the @dfn{default directory}, which ends with a slash. This is to inform
1934: you which directory the file will be found in if you do not specify a
1935: directory. For example, the minibuffer might start out with
1936:
1937: @example
1938: Find File: /u2/emacs/src/
1939: @end example
1940:
1941: @noindent
1942: where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c} specifies
1943: the file @file{/u2/emacs/src/buffer.c}. To find files in nearby
1944: directories, use @kbd{..}; thus, if you type @kbd{../lisp/simple.el}, the
1945: file that you visit will be the one named @file{/u2/emacs/lisp/simple.el}.
1946: Alternatively, you can kill with @kbd{M-@key{DEL}} the directory names you
1947: don't want (@pxref{Words}).@refill
1948:
1949: You can also type an absolute file name, one starting with a slash or a
1950: tilde, ignoring the default directory. For example, to find the file
1951: @file{/etc/termcap}, just type the name, giving
1952:
1953: @example
1954: Find File: /u2/emacs/src//etc/termcap
1955: @end example
1956:
1957: @noindent
1958: Two slashes in a row are not normally meaningful in Unix file names, but
1959: they are allowed in GNU Emacs. They mean, ``ignore everything before the
1960: second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored, and
1961: you get the file @file{/etc/termcap}.
1962:
1963: @vindex insert-default-directory
1964: If you set @code{insert-default-directory} to @code{nil}, the default directory
1965: is not inserted in the minibuffer. This way, the minibuffer starts out
1966: empty. But the name you type, if relative, is still interpreted with
1967: respect to the same default directory.
1968:
1969: @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer
1970: @section Editing in the Minibuffer
1971:
1972: The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual
1973: Emacs commands are available for editing the text of an argument you are
1974: entering.
1975:
1976: Since @key{RET} in the minibuffer is defined to exit the minibuffer,
1977: inserting a newline into the minibuffer must be done with @kbd{C-o} or with
1978: @kbd{C-q @key{LFD}}. (Recall that a newline is really the @key{LFD}
1979: character.)
1980:
1981: The minibuffer has its own window which always has space on the screen
1982: but acts as if it were not there when the minibuffer is not in use. When
1983: the minibuffer is in use, its window is just like the others; you can
1984: switch to another window with @kbd{C-x o}, edit text in other windows and
1985: perhaps even visit more files, before returning to the minibuffer to submit
1986: the argument. You can kill text in another window, return to the
1987: minibuffer window, and then yank the text to use it in the argument.
1988: @xref{Windows}.
1989:
1990: There are some restrictions on the use of the minibuffer window, however.
1991: You cannot switch buffers in it---the minibuffer and its window are
1992: permanently attached. Also, you cannot split or kill the minibuffer
1993: window. But you can make it taller in the normal fashion with @kbd{C-x ^}.
1994:
1995: @kindex C-M-v
1996: If while in the minibuffer you issue a command that displays help text
1997: of any sort in another window, then that window is identified as the
1998: one to scroll if you type @kbd{C-M-v} while in the minibuffer. This
1999: lasts until you exit the minibuffer. This feature comes into play
2000: if a completing minibuffer gives you a list of possible completions.
2001:
2002: Recursive use of the minibuffer is supported by Emacs. However, it is
2003: easy to do this by accident (because of autorepeating keyboards, for
2004: example) and get confused. Therefore, most Emacs commands that use the
2005: minibuffer refuse to operate if the minibuffer window is selected. If the
2006: minibuffer is active but you have switched to a different window, recursive
2007: use of the minibuffer is allowed---if you know enough to try to do this,
2008: you probably will not get confused.
2009:
2010: @vindex enable-recursive-minibuffers
2011: If you set the variable @code{enable-recursive-minibuffers} to be
2012: non-@code{nil}, recursive use of the minibuffer is always allowed.
2013:
2014: @node Completion, Repetition, Minibuffer Edit, Minibuffer
2015: @section Completion
2016: @cindex completion
2017:
2018: When appropriate, the minibuffer provides a @dfn{completion} facility.
2019: This means that you type enough of the argument to determine the rest,
2020: based on Emacs's knowledge of which arguments make sense, and Emacs visibly
2021: fills in the rest, or as much as can be determined from the part you have
2022: typed.
2023:
2024: When completion is available, certain keys---@key{TAB}, @key{RET}, and @key{SPC}---are
2025: redefined to complete an abbreviation present in the minibuffer into a
2026: longer string that it stands for, by matching it against a set of
2027: @dfn{completion alternatives} provided by the command reading the argument.
2028: @kbd{?} is defined to display a list of possible completions of what you
2029: have inserted.
2030:
2031: For example, when the minibuffer is being used by @kbd{Meta-x} to read
2032: the name of a command, it is given a list of all available Emacs command
2033: names to complete against. The completion keys match the text in the
2034: minibuffer against all the command names, find any additional characters of
2035: the name that are implied by the ones already present in the minibuffer,
2036: and add those characters to the ones you have given.
2037:
2038: Case is normally significant in completion, because it is significant in
2039: most of the names that you can complete (buffer names, file names and
2040: command names). Thus, @samp{fo} will not complete to @samp{Foo}. When you
2041: are completing a name in which case does not matter, case may be ignored
2042: for completion's sake if the program said to do so.
2043:
2044: @subsection Completion Example
2045:
2046: @kindex TAB
2047: @findex minibuffer-complete
2048: A concrete example may help here. If you type @kbd{Meta-x au @key{TAB}},
2049: the @key{TAB} looks for alternatives (in this case, command names) that
2050: start with @samp{au}. There are only two: @code{auto-fill-mode} and
2051: @code{auto-save-mode}. These are the same as far as @code{auto-}, so the
2052: @samp{au} in the minibuffer changes to @samp{auto-}.@refill
2053:
2054: If you type @key{TAB} again immediately, there are multiple possibilities
2055: for the very next character---it could be @samp{s} or @samp{f}---so no more
2056: characters are added; but a list of all possible completions is displayed
2057: in another window.
2058:
2059: If you go on to type @kbd{f @key{TAB}}, this @key{TAB} sees
2060: @samp{auto-f}. The only command name starting this way is
2061: @code{auto-fill-mode}, so completion inserts the rest of that. You
2062: now have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au
2063: @key{TAB} f @key{TAB}}. Note that @key{TAB} has this effect because in the
2064: minibuffer it is bound to the function @code{minibuffer-complete} when
2065: completion is supposed to be done.@refill
2066:
2067: @subsection Completion Commands
2068:
2069: Here is a list of all the completion commands, defined in the minibuffer
2070: when completion is available.
2071:
2072: @table @kbd
2073: @item @key{TAB}
2074: Complete the text in the minibuffer as much as possible @*
2075: (@code{minibuffer-complete}).
2076: @item @key{SPC}
2077: Complete the text in the minibuffer but don't add or fill out more
2078: than one word (@code{minibuffer-complete-word}).
2079: @item @key{RET}
2080: Submit the text in the minibuffer as the argument, possibly completing
2081: first as described below (@code{minibuffer-complete-and-exit}).
2082: @item ?
2083: Print a list of all possible completions of the text in the minibuffer
2084: (@code{minibuffer-list-completions}).
2085: @end table
2086:
2087: @kindex SPC
2088: @findex minibuffer-complete-word
2089: @key{SPC} completes much like @key{TAB}, but never goes beyond the
2090: next hyphen or space. If you have @samp{auto-f} in the minibuffer and type
2091: @key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but it
2092: stops completing after @samp{fill-}. This gives @samp{auto-fill-}.
2093: Another @key{SPC} at this point completes all the way to
2094: @samp{auto-fill-mode}. @key{SPC} in the minibuffer runs the function
2095: @code{minibuffer-complete-word} when completion is available.@refill
2096:
2097: There are three different ways that @key{RET} can work in completing
2098: minibuffers, depending on how the argument will be used.
2099:
2100: @itemize @bullet
2101: @item
2102: @dfn{Strict} completion is used when it is meaningless to give any
2103: argument except one of the known alternatives. For example, when
2104: @kbd{C-x k} reads the name of a buffer to kill, it is meaningless to
2105: give anything but the name of an existing buffer. In strict
2106: completion, @key{RET} refuses to exit if the text in the minibuffer
2107: does not complete to an exact match.
2108:
2109: @item
2110: @dfn{Cautious} completion is similar to strict completion, except that
2111: @key{RET} exits only if the text was an exact match already, not
2112: needing completion. If the text is not an exact match, @key{RET} does
2113: not exit, but it does complete the text. If it completes to an exact
2114: match, a second @key{RET} will exit.
2115:
2116: Cautious completion is used for reading file names for files that must
2117: already exist.
2118:
2119: @item
2120: @dfn{Permissive} completion is used when any string whatever is
2121: meaningful, and the list of completion alternatives is just a guide.
2122: For example, when @kbd{C-x C-f} reads the name of a file to visit, any
2123: file name is allowed, in case you want to create a file. In
2124: permissive completion, @key{RET} takes the text in the minibuffer
2125: exactly as given, without completing it.
2126: @end itemize
2127:
2128: The completion commands display a list of all possible completions in a
2129: window whenever there is more than one possibility for the very next
2130: character. Also, typing @kbd{?} explicitly requests such a list. The
2131: list of completions counts as help text, so @kbd{C-M-v} typed in the
2132: minibuffer scrolls the list.
2133:
2134: @vindex completion-ignored-extensions
2135: When completion is done on file names, certain file names are usually
2136: ignored. The variable @code{completion-ignored-extensions} contains a list
2137: of strings; a file whose name ends in any of those strings is ignored as a
2138: possible completion. The standard value of this variable has several
2139: elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and @code{"~"}.
2140: The effect is that, for example, @samp{foo} can complete to @samp{foo.c}
2141: even though @samp{foo.o} exists as well. If the only possible completions
2142: are files that end in ``ignored'' strings, then they are not ignored.@refill
2143:
2144: @vindex completion-auto-help
2145: Normally, a completion command that finds the next character is undetermined
2146: automatically displays a list of all possible completions. If the variable
2147: @code{completion-auto-help} is set to @code{nil}, this does not happen,
2148: and you must type @kbd{?} to display the possible completions.
2149:
2150: @node Repetition,, Completion, Minibuffer
2151: @section Repeating Minibuffer Commands
2152: @cindex command history
2153: @cindex history of commands
2154:
2155: Every command that uses the minibuffer at least once is recorded on a
2156: special history list, together with the values of the minibuffer arguments,
2157: so that you can repeat the command easily. In particular, every
2158: use of @kbd{Meta-x} is recorded, since @kbd{M-x} uses the minibuffer to
2159: read the command name.
2160:
2161: @findex list-command-history
2162: @c widecommands
2163: @table @kbd
2164: @item C-x @key{ESC}
2165: Re-execute a recent minibuffer command @*(@code{repeat-complex-command}).
2166: @item M-p
2167: Within @kbd{C-x @key{ESC}}, move to previous recorded command
2168: (@code{previous-complex-command}).
2169: @item M-n
2170: Within @kbd{C-x @key{ESC}}, move to the next (more recent) recorded
2171: command (@code{next-complex-command}).
2172: @item M-x list-command-history
2173: Display the entire command history, showing all the commands
2174: @kbd{C-x @key{ESC}} can repeat, most recent first.
2175: @end table
2176:
2177: @kindex C-x ESC
2178: @findex repeat-complex-command
2179: @kbd{C-x @key{ESC}} is used to re-execute a recent minibuffer-using
2180: command. With no argument, it repeats the last such command. A numeric
2181: argument specifies which command to repeat; one means the last one, and
2182: larger numbers specify earlier ones.
2183:
2184: @kbd{C-x @key{ESC}} works by turning the previous command into a Lisp
2185: expression and then entering a minibuffer initialized with the text for
2186: that expression. If you type just @key{RET}, the command is repeated as
2187: before. You can also change the command by editing the Lisp expression.
2188: Whatever expression you finally submit is what will be executed. The
2189: repeated command is added to the front of the command history unless it is
2190: identical to the most recently executed command already there.
2191:
2192: Even if you don't understand Lisp syntax, it will probably be obvious
2193: which command is displayed for repetition. If you do not change the text,
2194: you can be sure it will repeat exactly as before.
2195:
2196: @kindex M-n
2197: @kindex M-p
2198: @findex next-complex-command
2199: @findex previous-complex-command
2200: Once inside the minibuffer for @kbd{C-x @key{ESC}}, if the command shown
2201: to you is not the one you want to repeat, you can move around the list of
2202: previous commands using @kbd{M-n} and @kbd{M-p}. @kbd{M-p} replaces the
2203: contents of the minibuffer with the next earlier recorded command, and
2204: @kbd{M-n} replaces them with the next later command. After finding the
2205: desired previous command, you can edit its expression as usual and then
2206: resubmit it by typing @key{RET} as usual. Any editing you have done on the
2207: command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}.
2208:
2209: @kbd{M-p} is more useful than @kbd{M-n}, since more often you will
2210: initially request to repeat the most recent command and then decide to
2211: repeat an older one instead. These keys are specially defined within
2212: @kbd{C-x @key{ESC}} to run the commands @code{previous-complex-command} and
2213: @code{next-complex-command}.
2214:
2215: @vindex command-history
2216: The list of previous minibuffer-using commands is stored as a Lisp list
2217: in the variable @code{command-history}. Each element is a Lisp expression
2218: which describes one command and its arguments. Lisp programs can reexecute
2219: a command by feeding the corresponding @code{command-history} element to
2220: @code{eval}.
2221:
2222: @node M-x, Help, Minibuffer, Top
2223: @chapter Running Commands by Name
2224:
2225: The Emacs commands that are used often or that must be quick to type are
2226: bound to keys---short sequences of characters---for convenient use. Other
2227: Emacs commands that do not need to be brief are not bound to keys; to run
2228: them, you must refer to them by name.
2229:
2230: A command name is, by convention, made up of one or more words, separated
2231: by hyphens; for example, @code{auto-fill-mode} or @code{manual-entry}. The
2232: use of English words makes the command name easier to remember than a key
2233: made up of obscure characters, even though it is more characters to type.
2234: Any command can be run by name, even if it is also runnable by keys.
2235:
2236: @kindex M-x
2237: @cindex minibuffer
2238: The way to run a command by name is to start with @kbd{M-x}, type the
2239: command name, and finish it with @key{RET}. @kbd{M-x} uses the minibuffer
2240: to read the command name. @key{RET} exits the minibuffer and runs the
2241: command.
2242:
2243: Emacs uses the minibuffer for reading input for many different purposes;
2244: on this occasion, the string @samp{M-x} is displayed at the beginning of
2245: the minibuffer as a @dfn{prompt} to remind you that your input should be
2246: the name of a command to be run. @xref{Minibuffer}, for full information
2247: on the features of the minibuffer.
2248:
2249: You can use completion to enter the command name. For example, the
2250: command @code{forward-char} can be invoked by name by typing
2251:
2252: @example
2253: M-x forward-char @key{RET}
2254:
2255: @exdent or
2256:
2257: M-x fo @key{TAB} c @key{RET}
2258: @end example
2259:
2260: @noindent
2261: Note that @code{forward-char} is the same command that you invoke with
2262: the key @kbd{C-f}. Any command (interactively callable function) defined
2263: in Emacs can be called by its name using @kbd{M-x} whether or not any
2264: keys are bound to it.
2265:
2266: If you type @kbd{C-g} while the command name is being read, you cancel
2267: the @kbd{M-x} command and get out of the minibuffer, ending up at top level.
2268:
2269: To pass a numeric argument to the command you are invoking with
2270: @kbd{M-x}, specify the numeric argument before the @kbd{M-x}. @kbd{M-x}
2271: passes the argument along to the function which it calls. The argument
2272: value appears in the prompt while the command name is being read.
2273:
2274: Normally, when describing a command that is run by name, we omit the
2275: @key{RET} that is needed to terminate the name. Thus we might speak of
2276: @kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode @key{RET}}.
2277: We mention the @key{RET} only when there is a need to emphasize its
2278: presence, such as when describing a sequence of input that contains a
2279: command name and arguments that follow it.
2280:
2281: @findex execute-extended-command
2282: @kbd{M-x} is defined to run the command @code{execute-extended-command},
2283: which is responsible for reading the name of another command and invoking
2284: it.
2285:
2286: @node Help, Mark, M-x, Top
2287: @chapter Help
2288: @kindex Help
2289: @cindex help
2290: @cindex self-documentation
2291:
2292: Emacs provides extensive help features which revolve around a single
2293: character, @kbd{C-h}. @kbd{C-h} is a prefix key that is used only for
2294: documentation-printing commands. The characters that you can type after
2295: @kbd{C-h} are called @dfn{help options}. One help option is @kbd{C-h};
2296: that is how you ask for help about using @kbd{C-h}.
2297:
2298: @kbd{C-h C-h} prints a list of the possible help options, and then asks
2299: you to go ahead and type the option. It prompts with a string
2300:
2301: @smallexample
2302: A, B, C, F, I, K, L, M, N, S, T, V, W, C-c, C-d, C-n, C-w or C-h for more help:
2303: @end smallexample
2304:
2305: @noindent
2306: and you should type one of those characters.
2307:
2308: Typing a third @kbd{C-h} displays a description of what the options mean;
2309: it still waits for you to type an option. To cancel, type @kbd{C-g}.
2310:
2311: Here is a summary of the defined help commands.
2312:
2313: @table @kbd
2314: @item C-h a @var{string} @key{RET}
2315: Display list of commands whose names contain @var{string}
2316: (@code{command-apropos}).
2317: @item C-h b
2318: Display a table of all key bindings in effect now; local bindings of
2319: the current major mode first, followed by all global bindings
2320: (@code{describe-bindings}).
2321: @item C-h c @var{key}
2322: Print the name of the command that @var{key} runs (@code{describe-key-briefly}).
2323: @kbd{c} is for `character'. For more extensive information on @var{key},
2324: use @kbd{C-h k}.
2325: @item C-h f @var{function} @key{RET}
2326: Display documentation on the Lisp function named @var{function}
2327: (@code{describe-function}). Note that commands are Lisp functions, so
2328: a command name may be used.
2329: @item C-h i
2330: Run Info, the program for browsing documentation files (@code{info}).
2331: The complete Emacs manual is available on-line in Info.
2332: @item C-h k @var{key}
2333: Display name and documentation of the command @var{key} runs (@code{describe-key}).
2334: @item C-h l
2335: Display a description of the last 100 characters you typed
2336: (@code{view-lossage}).
2337: @item C-h m
2338: Display documentation of the current major mode (@code{describe-mode}).
2339: @item C-h n
2340: Display documentation of Emacs changes, most recent first
2341: (@code{view-emacs-news}).
2342: @item C-h s
2343: Display current contents of the syntax table, plus an explanation of
2344: what they mean (@code{describe-syntax}).
2345: @item C-h t
2346: Display the Emacs tutorial (@code{help-with-tutorial}).
2347: @item C-h v @var{var} @key{RET}
2348: Display the documentation of the Lisp variable @var{var}
2349: (@code{describe-variable}).
2350: @item C-h w @var{command} @key{RET}
2351: Print which keys run the command named @var{command} (@code{where-is}).
2352: @end table
2353:
2354: @section Documentation for a Key
2355:
2356: @kindex C-h c
2357: @findex describe-key-briefly
2358: The most basic @kbd{C-h} options are @kbd{C-h c}
2359: (@code{describe-key-briefly}) and @kbd{C-h k} (@code{describe-key}).
2360: @kbd{C-h c @var{key}} prints in the echo area the name of the command that
2361: @var{key} is bound to. For example, @kbd{C-h c C-f} prints
2362: @samp{forward-char}. Since command names are chosen to describe what the
2363: command does, this is a good way to get a very brief description of what
2364: @var{key} does.@refill
2365:
2366: @kindex C-h k
2367: @findex describe-key
2368: @kbd{C-h k @var{key}} is similar but gives more information. It displays
2369: the documentation string of the command @var{key} is bound to as well as
2370: its name. This is too big for the echo area, so a window is used for the
2371: display.
2372:
2373: @section Help by Command or Variable Name
2374:
2375: @kindex C-h f
2376: @findex describe-function
2377: @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function
2378: using the minibuffer, then displays that function's documentation string
2379: in a window. Since commands are Lisp functions, you can use this to get
2380: the documentation of a command that is known by name. For example,
2381:
2382: @example
2383: C-h f auto-fill-mode @key{RET}
2384: @end example
2385:
2386: @noindent
2387: displays the documentation of @code{auto-fill-mode}. This is the only
2388: way to see the documentation of a command that is not bound to any key
2389: (one which you would normally call using @kbd{M-x}).
2390:
2391: @kbd{C-h f} is also useful for Lisp functions that you are planning to
2392: use in a Lisp program. For example, if you have just written the code
2393: @code{(make-vector len)} and want to be sure that you are using
2394: @code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. Because
2395: @kbd{C-h f} allows all function names, not just command names, you may find
2396: that some of your favorite abbreviations that work in @kbd{M-x} don't work
2397: in @kbd{C-h f}. An abbreviation may be unique among command names yet fail
2398: to be unique when other function names are allowed.
2399:
2400: The function name for @kbd{C-h f} to describe has a default which is
2401: used if you type @key{RET} leaving the minibuffer empty. The default is
2402: the function called by the innermost Lisp expression in the buffer around
2403: point, @i{provided} that is a valid, defined Lisp function name. For
2404: example, if point is located following the text @samp{(make-vector (car
2405: x)}, the innermost list containing point is the one that starts with
2406: @samp{(make-vector}, so the default is to describe the function
2407: @code{make-vector}.
2408:
2409: @kbd{C-h f} is often useful just to verify that you have the right
2410: spelling for the function name. If @kbd{C-h f} mentions a default in the
2411: prompt, you have typed the name of a defined Lisp function. If that tells
2412: you what you want to know, just type @kbd{C-g} to cancel the @kbd{C-h f}
2413: command and go on editing.
2414:
2415: @kindex C-h w
2416: @findex where-is
2417: @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
2418: @var{command}. It prints a list of the keys in the echo area.
2419: Alternatively, it says that the command is not on any keys, which implies
2420: that you must use @kbd{M-x} to call it.@refill
2421:
2422: @kindex C-h v
2423: @findex describe-variable
2424: @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes
2425: Lisp variables instead of Lisp functions. Its default is the Lisp symbol
2426: around or before point, but only if that is the name of a known Lisp
2427: variable. @xref{Variables}.@refill
2428:
2429: @section Apropos
2430:
2431: @kindex C-h a
2432: @findex command-apropos
2433: @cindex apropos
2434: A more sophisticated sort of question to ask is, ``What are the commands
2435: for working with files?'' For this, type @kbd{C-h a file @key{RET}}, which
2436: displays a list of all command names that contain @samp{file}, such as
2437: @code{copy-file}, @code{find-file}, and so on. With each command name
2438: appears a brief description of how to use the command, and what keys you
2439: can currently invoke it with. For example, it would say that you can
2440: invoke @code{find-file} by typing @kbd{C-x C-f}. The @kbd{a} in @kbd{C-h
2441: a} stands for `Apropos'; @kbd{C-h a} runs the Lisp function
2442: @code{command-apropos}.@refill
2443:
2444: Because @kbd{C-h a} looks only for functions whose names contain the
2445: string which you specify, you must use ingenuity in choosing the string.
2446: If you are looking for commands for killing backwards and @kbd{C-h a
2447: kill-backwards @key{RET}} doesn't reveal any, don't give up. Try just
2448: @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}. Be persistent.
2449: Pretend you are playing Adventure. Also note that you can use a
2450: regular expression as the argument (@pxref{Regexps}).
2451:
2452: Here is a set of arguments to give to @kbd{C-h a} that covers many
2453: classes of Emacs commands, since there are strong conventions for naming
2454: the standard Emacs commands. By giving you a feel for the naming
2455: conventions, this set should also serve to aid you in developing a
2456: technique for picking @code{apropos} strings.
2457:
2458: @quotation
2459: char, line, word, sentence, paragraph, region, page, sexp, list, defun,
2460: buffer, screen, window, file, dir, register, mode,
2461: beginning, end, forward, backward, next, previous, up, down, search, goto,
2462: kill, delete, mark, insert, yank, fill, indent, case,
2463: change, set, what, list, find, view, describe.
2464: @end quotation
2465:
2466: @findex apropos
2467: To list all Lisp symbols that contain a match for a regexp, not just
2468: the ones that are defined as commands, use the command @kbd{M-x apropos}
2469: instead of @kbd{C-h a}.
2470:
2471: @section Other Help Commands
2472:
2473: @kindex C-h i
2474: @findex info
2475: @kbd{C-h i} (@code{info}) runs the Info program, which is used for
2476: browsing through structured documentation files. The entire Emacs manual
2477: is available within Info. Eventually all the documentation of the GNU
2478: system will be available. Type @kbd{h} after entering Info to run
2479: a tutorial on using Info.
2480:
2481: @kindex C-h l
2482: @findex view-lossage
2483: If something surprising happens, and you are not sure what commands you
2484: typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} prints the last
2485: 100 command characters you typed in. If you see commands that you don't
2486: know, you can use @kbd{C-h c} to find out what they do.
2487:
2488: @kindex C-h m
2489: @findex describe-mode
2490: Emacs has several major modes, each of which redefines a few keys and
2491: makes a few other changes in how editing works. @kbd{C-h m} (@code{describe-mode})
2492: prints documentation on the current major mode, which normally describes
2493: all the commands that are changed in this mode.
2494:
2495: @kindex C-h b
2496: @findex describe-bindings
2497: @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
2498: (@code{describe-syntax}) present other information about the current
2499: Emacs mode. @kbd{C-h b} displays a list of all the key bindings now
2500: in effect; the local bindings of the current major mode first,
2501: followed by the global bindings (@pxref{Key Bindings}). @kbd{C-h s}
2502: displays the contents of the syntax table, with explanations of each
2503: character's syntax (@pxref{Syntax}).@refill
2504:
2505: @kindex C-h n
2506: @findex view-emacs-news
2507: @kindex C-h t
2508: @findex help-with-tutorial
2509: @kindex C-h C-c
2510: @findex describe-copying
2511: @kindex C-h C-d
2512: @findex describe-distribution
2513: @kindex C-h C-w
2514: @findex describe-no-warranty
2515: The other @kbd{C-h} options display various files of useful information.
2516: @kbd{C-h C-w} displays the full details on the complete absence of warranty
2517: for GNU Emacs. @kbd{C-h n} (@code{view-emacs-news}) displays the file
2518: @file{emacs/etc/NEWS}, which contains documentation on Emacs changes
2519: arranged chronologically. @kbd{C-h t} (@code{help-with-tutorial}) displays
2520: the learn-by-doing Emacs tutorial. @kbd{C-h C-c} (@code{describe-copying})
2521: displays the file @file{emacs/etc/COPYING}, which tells you the conditions
2522: you must obey in distributing copies of Emacs. @kbd{C-h C-d}
2523: (@code{describe-distribution}) displays the file @file{emacs/etc/DISTRIB},
2524: which tells you how you can order a copy of the latest version of
2525: Emacs.@refill
2526:
2527: @node Mark, Killing, Help, Top
2528: @chapter The Mark and the Region
2529: @cindex mark
2530: @cindex region
2531:
2532: There are many Emacs commands which operate on an arbitrary contiguous
2533: part of the current buffer. To specify the text for such a command to
2534: operate on, you set @dfn{the mark} at one end of it, and move point to the
2535: other end. The text between point and the mark is called @dfn{the region}.
2536: You can move point or the mark to adjust the boundaries of the region. It
2537: doesn't matter which one is set first chronologically, or which one comes
2538: earlier in the text.
2539:
2540: Once the mark has been set, it remains until it is set again at another
2541: place. The mark remains fixed with respect to the preceding character if
2542: text is inserted or deleted in the buffer. Each Emacs buffer has its own
2543: mark, so that when you return to a buffer that had been selected
2544: previously, it has the same mark it had before.
2545:
2546: Many commands that insert text, such as @kbd{C-y} (@code{yank}) and
2547: @kbd{M-x insert-buffer}, position the mark at one end of the inserted
2548: text---the opposite end from where point is positioned, so that the region
2549: contains the text just inserted.
2550:
2551: Aside from delimiting the region, the mark is also useful for remembering
2552: a spot that you may want to go back to. To make this feature more useful,
2553: Emacs remembers 16 previous locations of the mark, in the @code{mark ring}.
2554:
2555: @menu
2556: * Setting Mark:: Commands to set the mark.
2557: * Using Region:: Summary of ways to operate on contents of the region.
2558: * Marking Objects:: Commands to put region around textual units.
2559: * Mark Ring:: Previous mark positions saved so you can go back there.
2560: @end menu
2561:
2562: @node Setting Mark, Using Region, Mark, Mark
2563: @section Setting the Mark
2564:
2565: Here are some commands for setting the mark:
2566:
2567: @c WideCommands
2568: @table @kbd
2569: @item C-@key{SPC}
2570: Set the mark where point is (@code{set-mark-command}).
2571: @item C-@@
2572: The same.
2573: @item C-x C-x
2574: Interchange mark and point (@code{exchange-point-and-mark}).
2575: @end table
2576:
2577: For example, if you wish to convert part of the buffer to all upper-case,
2578: you can use the @kbd{C-x C-u} (@code{upcase-region}) command, which operates
2579: on the text in the region. You can first go to the beginning of the text
2580: to be capitalized, type @kbd{C-@key{SPC}} to put the mark there, move to
2581: the end, and then type @kbd{C-x C-u}. Or, you can set the mark at the end
2582: of the text, move to the beginning, and then type @kbd{C-x C-u}. Most
2583: commands that operate on the text in the region have the word @code{region}
2584: in their names.
2585:
2586: @kindex C-SPC
2587: @findex set-mark-command
2588: The most common way to set the mark is with the @kbd{C-@key{SPC}} command
2589: (@code{set-mark-command}). This sets the mark where point is. Then you
2590: can move point away, leaving the mark behind. It is actually incorrect to
2591: speak of the character @kbd{C-@key{SPC}}; there is no such character. When
2592: you type @key{SPC} while holding down @key{CTRL}, what you get on most
2593: terminals is the character @kbd{C-@@}. This is the key actually bound to
2594: @code{set-mark-command}. But unless you are unlucky enough to have a
2595: terminal where typing @kbd{C-@key{SPC}} does not produce @kbd{C-@@}, you
2596: might as well think of this character as @kbd{C-@key{SPC}}.
2597:
2598: @kindex C-x C-x
2599: @findex exchange-point-and-mark
2600: Since terminals have only one cursor, there is no way for Emacs to show
2601: you where the mark is located. You have to remember. The usual solution
2602: to this problem is to set the mark and then use it soon, before you forget
2603: where it is. But you can see where the mark is with the command @kbd{C-x
2604: C-x} (@code{exchange-point-and-mark}) which puts the mark where point was and
2605: point where the mark was. The extent of the region is unchanged, but the
2606: cursor and point are now at the previous location of the mark.
2607:
2608: @kbd{C-x C-x} is also useful when you are satisfied with the location of
2609: point but want to move the mark; do @kbd{C-x C-x} to put point there and
2610: then you can move it. A second use of @kbd{C-x C-x}, if necessary, puts
2611: the mark at the new location with point back at its original location.
2612:
2613: @node Using Region, Marking Objects, Setting Mark, Mark
2614: @section Operating on the Region
2615:
2616: Once you have created an active region, you can do many things to
2617: the text in it:
2618: @itemize @bullet
2619: @item
2620: Kill it with @kbd{C-w} (@pxref{Killing}).
2621: @item
2622: Save it in a register with @kbd{C-x x} (@pxref{Registers}).
2623: @item
2624: Save it in a buffer or a file (@pxref{Accumulating Text}).
2625: @item
2626: Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} @*(@pxref{Case}).
2627: @item
2628: Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
2629: @item
2630: Fill it as text with @kbd{M-g} (@pxref{Filling}).
2631: @item
2632: Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}).
2633: @item
2634: Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}).
2635: @end itemize
2636:
2637: @node Marking Objects, Mark Ring, Using Region, Mark
2638: @section Commands to Mark Textual Objects
2639:
2640: There are commands for placing point and the mark around a textual
2641: object such as a word, list, paragraph or page.
2642:
2643: @table @kbd
2644: @item M-@@
2645: Set mark after end of next word (@code{mark-word}). This command and
2646: the following one do not move point.
2647: @item C-M-@@
2648: Set mark after end of next Lisp expression (@code{mark-sexp}).
2649: @item M-h
2650: Put region around current paragraph (@code{mark-paragraph}).
2651: @item C-M-h
2652: Put region around current Lisp defun (@code{mark-defun}).
2653: @item C-x h
2654: Put region around entire buffer (@code{mark-whole-buffer}).
2655: @item C-x C-p
2656: Put region around current page (@code{mark-page}).
2657: @end table
2658:
2659: @kindex M-@@
2660: @kindex C-M-@@
2661: @findex mark-word
2662: @findex mark-sexp
2663: @kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next word,
2664: while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the next Lisp
2665: expression. These characters allow you to save a little typing or
2666: redisplay, sometimes.
2667:
2668: @kindex M-h
2669: @kindex C-M-h
2670: @kindex C-x C-p
2671: @kindex C-x h
2672: @findex mark-paragraph
2673: @findex mark-defun
2674: @findex mark-page
2675: @findex mark-whole-buffer
2676: Other commands set both point and mark, to delimit an object in the
2677: buffer. @kbd{M-h} (@code{mark-paragraph}) moves point to the beginning of
2678: the paragraph that surrounds or follows point, and puts the mark at the end
2679: of that paragraph (@pxref{Paragraphs}). @kbd{M-h} does all that's
2680: necessary if you wish to indent, case-convert, or kill a whole paragraph.
2681: @kbd{C-M-h} (@code{mark-defun}) similarly puts point before and the mark
2682: after the current or following defun (@pxref{Defuns}). @kbd{C-x C-p}
2683: (@code{mark-page}) puts point before the current page (or the next or
2684: previous, according to the argument), and mark at the end (@pxref{Pages}).
2685: The mark goes after the terminating page delimiter (to include it), while
2686: point goes after the preceding page delimiter (to exclude it). Finally,
2687: @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire buffer as the
2688: region, by putting point at the beginning and the mark at the end.
2689:
2690: @node Mark Ring,, Marking Objects, Mark
2691: @section The Mark Ring
2692:
2693: @kindex C-u C-SPC
2694: @cindex mark ring
2695: @kindex C-u C-@@
2696: Aside from delimiting the region, the mark is also useful for remembering
2697: a spot that you may want to go back to. To make this feature more useful,
2698: Emacs remembers 16 previous locations of the mark, in the @dfn{mark ring}.
2699: Most commands that set the mark push the old mark onto this ring. To
2700: return to a marked location, use @kbd{C-u C-@key{SPC}} (or @kbd{C-u C-@@}); this is
2701: the command @code{set-mark-command} given a numeric argument. It moves
2702: point to where the mark was, and restores the mark from the ring of former
2703: marks. So repeated use of this command moves point to all of the old marks
2704: on the ring, one by one. The marks you see go to the end of the ring,
2705: so no marks are lost.
2706:
2707: Each buffer has its own mark ring. All editing commands use the current
2708: buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} always stays in
2709: the same buffer.
2710:
2711: Many commands that can move long distances, such as @kbd{M-<}
2712: (@code{beginning-of-buffer}), start by setting the mark and saving the old
2713: mark on the mark ring. This is to make it easier for you to move back
2714: later. Searches do this except when they do not actually move point. You
2715: can tell when a command sets the mark because @samp{Mark Set} is printed in
2716: the echo area.
2717:
2718: @vindex mark-ring-max
2719: The variable @code{mark-ring-max} is the maximum number of entries to
2720: keep in the mark ring. If that many entries exist and another one is
2721: pushed, the last one in the list is discarded. Repeating @kbd{C-u
2722: C-@key{SPC}} circulates through the limited number of entries that are
2723: currently in the ring.
2724:
2725: @vindex mark-ring
2726: The variable @code{mark-ring} holds the mark ring itself, as a list of
2727: marker objects in the order most recent first. This variable is local
2728: in every buffer.
2729:
2730: @iftex
2731: @chapter Killing and Moving Text
2732:
2733: @dfn{Killing} means erasing text and copying it into the @dfn{kill ring},
2734: from which it can be retrieved by @dfn{yanking} it. Some other systems
2735: that have recently become popular use the terms ``cutting'' and ``pasting''
2736: for these operations.
2737:
2738: The commonest way of moving or copying text with Emacs is to kill it and
2739: later yank it in one or more places. This is very safe because all the
2740: text killed recently is remembered, and it is versatile, because the many
2741: commands for killing syntactic units can also be used for moving those
2742: units. There are also other ways of copying text for special purposes.
2743:
2744: Emacs has only one kill ring, so you can kill text in one buffer and yank
2745: it in another buffer.
2746:
2747: @end iftex
2748:
2749: @node Killing, Yanking, Mark, Top
2750: @section Deletion and Killing
2751: @findex delete-char
2752: @c ??? Should be backward-delete-char
2753: @findex delete-backward-char
2754:
2755: @cindex killing
2756: @cindex cutting
2757: @cindex deletion
2758: @kindex C-d
2759: @kindex DEL
2760: Most commands which erase text from the buffer save it so that you can
2761: get it back if you change your mind, or move or copy it to other parts of
2762: the buffer. These commands are known as @dfn{kill} commands. The rest of
2763: the commands that erase text do not save it; they are known as @dfn{delete}
2764: commands. (This distinction is made only for erasure of text in the
2765: buffer.)
2766:
2767: The delete commands include @kbd{C-d} (@code{delete-char}) and
2768: @key{DEL} (@code{delete-backward-char}), which delete only one character at
2769: a time, and those commands that delete only spaces or newlines. Commands
2770: that can destroy significant amounts of nontrivial data generally kill.
2771: The commands' names and individual descriptions use the words @samp{kill}
2772: and @samp{delete} to say which they do. If you do a kill or delete command
2773: by mistake, you can use the @kbd{C-x u} (@code{undo}) command to undo it
2774: (@pxref{Undo}).@refill
2775:
2776: @subsection Deletion
2777:
2778: @table @kbd
2779: @item C-d
2780: Delete next character (@code{delete-char}).
2781: @item @key{DEL}
2782: Delete previous character (@code{delete-backward-char}).
2783: @item M-\
2784: Delete spaces and tabs around point (@code{delete-horizontal-space}).
2785: @item M-@key{SPC}
2786: Delete spaces and tabs around point, leaving one space
2787: (@code{just-one-space}).
2788: @item C-x C-o
2789: Delete blank lines around the current line (@code{delete-blank-lines}).
2790: @item M-^
2791: Join two lines by deleting the intervening newline, and any indentation
2792: following it (@code{delete-indentation}).
2793: @end table
2794:
2795: The most basic delete commands are @kbd{C-d} (@code{delete-char}) and
2796: @key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the character
2797: after point, the one the cursor is ``on top of''. Point doesn't move.
2798: @key{DEL} deletes the character before the cursor, and moves point back.
2799: Newlines can be deleted like any other characters in the buffer; deleting a
2800: newline joins two lines. Actually, @kbd{C-d} and @key{DEL} aren't always
2801: delete commands; if given an argument, they kill instead, since they can
2802: erase more than one character this way.
2803:
2804: @kindex M-\
2805: @findex delete-horizontal-space
2806: @kindex M-SPC
2807: @findex just-one-space
2808: @kindex C-x C-o
2809: @findex delete-blank-lines
2810: @kindex M-^
2811: @findex delete-indentation
2812: The other delete commands are those which delete only formatting
2813: characters: spaces, tabs and newlines. @kbd{M-\} (@code{delete-horizontal-space})
2814: deletes all the spaces and tab characters before and after point.
2815: @kbd{M-@key{SPC}} (@code{just-one-space}) does likewise but leaves a single
2816: space after point, regardless of the number of spaces that existed
2817: previously (even zero).
2818:
2819: @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines after
2820: the current line, and if the current line is blank deletes all blank lines
2821: preceding the current line as well (leaving one blank line, the current
2822: line). @kbd{M-^} (@code{delete-indentation}) joins the current line and
2823: the previous line, or the current line and the next line if given an
2824: argument, by deleting a newline and all surrounding spaces, possibly
2825: leaving a single space. @xref{Indentation,M-^}.
2826:
2827: @subsection Killing by Lines
2828:
2829: @table @kbd
2830: @item C-k
2831: Kill rest of line or one or more lines (@code{kill-line}).
2832: @end table
2833:
2834: @kindex C-k
2835: @findex kill-line
2836: The simplest kill command is @kbd{C-k}. If given at the beginning of a
2837: line, it kills all the text on the line, leaving it blank. If given on a
2838: blank line, the blank line disappears. As a consequence, if you go to the
2839: front of a non-blank line and type @kbd{C-k} twice, the line disappears
2840: completely.
2841:
2842: More generally, @kbd{C-k} kills from point up to the end of the line,
2843: unless it is at the end of a line. In that case it kills the newline
2844: following the line, thus merging the next line into the current one.
2845: Invisible spaces and tabs at the end of the line are ignored when deciding
2846: which case applies, so if point appears to be at the end of the line, you
2847: can be sure the newline will be killed.
2848:
2849: If @kbd{C-k} is given a positive argument, it kills that many lines and
2850: the newlines that follow them (however, text on the current line before
2851: point is spared). With a negative argument, it kills back to a number of
2852: line beginnings. An argument of @minus{}2 means kill back to the second line
2853: beginning. If point is at the beginning of a line, that line beginning
2854: doesn't count, so @kbd{C-u - 2 C-k} with point at the front of a line kills
2855: the two previous lines.
2856:
2857: @kbd{C-k} with an argument of zero kills all the text before point on the
2858: current line.
2859:
2860: @subsection Other Kill Commands
2861: @findex kill-line
2862: @findex kill-region
2863: @findex kill-word
2864: @findex backward-kill-word
2865: @findex kill-sexp
2866: @findex kill-sentence
2867: @findex backward-kill-sentence
2868: @kindex M-d
2869: @kindex M-DEL
2870: @kindex C-M-k
2871: @kindex C-x DEL
2872: @kindex M-k
2873: @kindex C-k
2874: @kindex C-w
2875:
2876: @c DoubleWideCommands
2877: @table @kbd
2878: @item C-w
2879: Kill region (from point to the mark) (@code{kill-region}).
2880: @xref{Words}.
2881: @item M-d
2882: Kill word (@code{kill-word}).
2883: @item M-@key{DEL}
2884: Kill word backwards (@code{backward-kill-word}).
2885: @item C-x @key{DEL}
2886: Kill back to beginning of sentence (@code{backward-kill-sentence}).
2887: @xref{Sentences}.
2888: @item M-k
2889: Kill to end of sentence (@code{kill-sentence}).
2890: @item C-M-k
2891: Kill sexp (@code{kill-sexp}). @xref{Lists}.
2892: @item M-z @var{char}
2893: Kill up to next occurrence of @var{char} (@code{zap-to-char}).
2894: @end table
2895:
2896: A kill command which is very general is @kbd{C-w} (@code{kill-region}),
2897: which kills everything between point and the mark. With this command, you
2898: can kill any contiguous sequence of characters, if you first set the mark
2899: at one end of them and go to the other end.
2900:
2901: @kindex M-z
2902: @findex zap-to-char
2903: A convenient way of killing is combined with searching: @kbd{M-z}
2904: (@code{zap-to-char}) reads a character and kills from point up to (but not
2905: including) the next occurrence of that character in the buffer. If there
2906: is no next occurrence, killing goes to the end of the buffer. A numeric
2907: argument acts as a repeat count. A negative argument means to search
2908: backward and kill text before point.
2909:
2910: Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and
2911: @kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and
2912: sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k}
2913: (@pxref{Sentences}).@refill
2914:
2915: @node Yanking, Accumulating Text, Killing, Top
2916: @section Yanking
2917: @cindex moving text
2918: @cindex copying text
2919: @cindex kill ring
2920: @cindex yanking
2921: @cindex pasting
2922:
2923: @dfn{Yanking} is getting back text which was killed. This is what some
2924: systems call ``pasting''. The usual way to move or copy text is to kill it
2925: and then yank it one or more times.
2926:
2927: @table @kbd
2928: @item C-y
2929: Yank last killed text (@code{yank}).
2930: @item M-y
2931: Replace re-inserted killed text with the previously killed text
2932: (@code{yank-pop}).
2933: @item M-w
2934: Save region as last killed text without actually killing it
2935: (@code{copy-region-as-kill}).
2936: @item C-M-w
2937: Append next kill to last batch of killed text (@code{append-next-kill}).
2938: @end table
2939:
2940: @menu
2941: * Kill Ring:: Where killed text is stored. Basic yanking.
2942: * Appending Kills:: Several kills in a row all yank together.
2943: * Earlier Kills:: Yanking something killed some time ago.
2944: @end menu
2945:
2946: @node Kill Ring, Appending Kills, Yanking, Yanking
2947: @subsection The Kill Ring
2948:
2949: @kindex C-y
2950: @findex Yank
2951: All killed text is recorded in the @dfn{kill ring}, a list of blocks of
2952: text that have been killed. There is only one kill ring, used in all
2953: buffers, so you can kill text in one buffer and yank it in another buffer.
2954: This is the usual way to move text from one file to another.
2955: (@xref{Accumulating Text}, for some other ways.)
2956:
2957: The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent
2958: kill. It leaves the cursor at the end of the text. It sets the mark at
2959: the beginning of the text. @xref{Mark}.
2960:
2961: @kbd{C-u C-y} leaves the cursor in front of the text, and sets the mark
2962: after it. This is only if the argument is specified with just a @kbd{C-u},
2963: precisely. Any other sort of argument, including @kbd{C-u} and digits, has
2964: an effect described below (under ``Yanking Earlier Kills'').
2965:
2966: @kindex M-w
2967: @findex copy-region-as-kill
2968: If you wish to copy a block of text, you might want to use @kbd{M-w}
2969: (@code{copy-region-as-kill}), which copies the region into the kill ring
2970: without removing it from the buffer. This is approximately equivalent to
2971: @kbd{C-w} followed by @kbd{C-y}, except that @kbd{M-w} does not mark the
2972: buffer as ``modified'' and does not temporarily change the screen.
2973:
2974: @node Appending Kills, Earlier Kills, Kill Ring, Yanking
2975: @subsection Appending Kills
2976:
2977: @cindex television
2978: Normally, each kill command pushes a new block onto the kill ring.
2979: However, two or more kill commands in a row combine their text into a
2980: single entry, so that a single @kbd{C-y} gets it all back as it was before
2981: it was killed. This means that you don't have to kill all the text in one
2982: command; you can keep killing line after line, or word after word, until
2983: you have killed it all, and you can still get it all back at once. (Thus
2984: we join television in leading people to kill thoughtlessly.)
2985:
2986: Commands that kill forward from point add onto the end of the previous
2987: killed text. Commands that kill backward from point add onto the
2988: beginning. This way, any sequence of mixed forward and backward kill
2989: commands puts all the killed text into one entry without rearrangement.
2990: Numeric arguments do not break the sequence of appending kills. For
2991: example, suppose the buffer contains
2992:
2993: @example
2994: This is the first
2995: line of sample text
2996: and here is the third.
2997: @end example
2998:
2999: @noindent
3000: with point at the beginning of the second line. If you type @kbd{C-k C-u 2
3001: M-@key{DEL} C-k}, the first @kbd{C-k} kills the text @samp{line of sample
3002: text}, @kbd{C-u 2 M-@key{DEL}} kills @samp{the first} with the newline that
3003: followed it, and the second @kbd{C-k} kills the newline after the second
3004: line. The result is that the buffer contains @samp{This is and here is the
3005: third.} and a single kill entry contains @samp{the first@key{RET}line of
3006: sample text@key{RET}}---all the killed text, in its original order.
3007:
3008: @kindex C-M-w
3009: @findex append-next-kill
3010: If a kill command is separated from the last kill command by other
3011: commands (not just numeric arguments), it starts a new entry on the kill
3012: ring. But you can force it to append by first typing the command
3013: @kbd{C-M-w} (@code{append-next-kill}) in front of it. The @kbd{C-M-w}
3014: tells the following command, if it is a kill command, to append the text it
3015: kills to the last killed text, instead of starting a new entry. With
3016: @kbd{C-M-w}, you can kill several separated pieces of text and accumulate
3017: them to be yanked back in one place.@refill
3018:
3019: @node Earlier Kills,, Appending Kills, Yanking
3020: @subsection Yanking Earlier Kills
3021:
3022: @kindex M-y
3023: @findex yank-pop
3024: To recover killed text that is no longer the most recent kill, you need
3025: the @kbd{Meta-y} (@code{yank-pop}) command. @kbd{M-y} can be used only
3026: after a @kbd{C-y} or another @kbd{M-y}. It takes the text previously
3027: yanked and replaces it with the text from an earlier kill. So, to recover
3028: the text of the next-to-the-last kill, you first use @kbd{C-y} to recover
3029: the last kill, and then use @kbd{M-y} to replace it with the previous
3030: kill.@refill
3031:
3032: You can think in terms of a ``last yank'' pointer which points at an item
3033: in the kill ring. Each time you kill, the ``last yank'' pointer moves to
3034: the newly made item at the front of the ring. @kbd{C-y} yanks the item
3035: which the ``last yank'' pointer points to. @kbd{M-y} moves the ``last
3036: yank'' pointer to a different item, and the text in the buffer changes to
3037: match. Enough @kbd{M-y} commands can move the pointer to any item in the
3038: ring, so you can get any item into the buffer. Eventually the pointer
3039: reaches the end of the ring; the next @kbd{M-y} moves it to the first item
3040: again.
3041:
3042: Yanking moves the ``last yank'' pointer around the ring, but it does not
3043: change the order of the entries in the ring, which always runs from the
3044: most recent kill at the front to the oldest one still remembered.
3045:
3046: @kbd{M-y} can take a numeric argument, which tells it how many items to
3047: advance the ``last yank'' pointer by. A negative argument moves the
3048: pointer toward the front of the ring; from the front of the ring, it moves
3049: to the last entry and starts moving forward from there.
3050:
3051: Once the text you are looking for is brought into the buffer, you can
3052: stop doing @kbd{M-y} commands and it will stay there. It's just a copy of
3053: the kill ring item, so editing it in the buffer does not change what's in
3054: the ring. As long as no new killing is done, the ``last yank'' pointer
3055: remains at the same place in the kill ring, so repeating @kbd{C-y} will
3056: yank another copy of the same old kill.
3057:
3058: If you know how many @kbd{M-y} commands it would take to find the
3059: text you want, you can yank that text in one step using @kbd{C-y} with
3060: a numeric argument. @kbd{C-y} with an argument greater than one
3061: restores the text the specified number of entries back in the kill
3062: ring. Thus, @kbd{C-u 2 C-y} gets the next to the last block of killed
3063: text. It is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numeric
3064: argument starts counting from the ``last yank'' pointer, and sets the
3065: ``last yank'' pointer to the entry that it yanks.
3066:
3067: @vindex kill-ring-max
3068: The length of the kill ring is controlled by the variable
3069: @code{kill-ring-max}; no more than that many blocks of killed text are
3070: saved.
3071:
3072: @node Accumulating Text, Rectangles, Yanking, Top
3073: @section Accumulating Text
3074: @kindex C-x a
3075: @findex append-to-buffer
3076: @findex prepend-to-buffer
3077: @findex copy-to-buffer
3078: @findex append-to-file
3079:
3080: Usually we copy or move text by killing it and yanking it, but there are
3081: other ways that are useful for copying one block of text in many places, or
3082: for copying many scattered blocks of text into one place.
3083:
3084: You can accumulate blocks of text from scattered locations either into a
3085: buffer or into a file if you like. These commands are described here. You
3086: can also use Emacs registers for storing and accumulating text.
3087: @xref{Registers}.
3088:
3089: @table @kbd
3090: @item C-x a
3091: Append region to contents of specified buffer (@code{append-to-buffer}).
3092: @item M-x prepend-to-buffer
3093: Prepend region to contents of specified buffer.
3094: @item M-x copy-to-buffer
3095: Copy region into specified buffer, deleting that buffer's old contents.
3096: @item M-x insert-buffer
3097: Insert contents of specified buffer into current buffer at point.
3098: @item M-x append-to-file
3099: Append region to contents of specified file, at the end.
3100: @end table
3101:
3102: To accumulate text into a buffer, use the command @kbd{C-x a @var{buffername}}
3103: (@code{append-to-buffer}), which inserts a copy of the region into the
3104: buffer @var{buffername}, at the location of point in that buffer. If there
3105: is no buffer with that name, one is created. If you append text into a
3106: buffer which has been used for editing, the copied text goes into the
3107: middle of the text of the buffer, wherever point happens to be in it.
3108:
3109: Point in that buffer is left at the end of the copied text, so successive
3110: uses of @kbd{C-x a} accumulate the text in the specified buffer in the same
3111: order as they were copied. Strictly speaking, @kbd{C-x a} does not always
3112: append to the text already in the buffer; but if @kbd{C-x a} is the only
3113: command used to alter a buffer, it does always append to the existing text
3114: because point is always at the end.
3115:
3116: @kbd{M-x prepend-to-buffer} is just like @kbd{C-x a} except that point in
3117: the other buffer is left before the copied text, so successive prependings
3118: add text in reverse order. @kbd{M-x copy-to-buffer} is similar except that
3119: any existing text in the other buffer is deleted, so the buffer is left
3120: containing just the text newly copied into it.
3121:
3122: You can retrieve the accumulated text from that buffer with @kbd{M-x
3123: insert-buffer}; this too takes @var{buffername} as an argument. It inserts
3124: a copy of the text in buffer @var{buffername} into the selected buffer.
3125: You could alternatively select the other buffer for editing, perhaps moving
3126: text from it by killing or with @kbd{C-x a}. @xref{Buffers}, for
3127: background information on buffers.
3128:
3129: Instead of accumulating text within Emacs, in a buffer, you can append
3130: text directly into a file with @kbd{M-x append-to-file}, which takes
3131: @var{file-name} as an argument. It adds the text of the region to the end
3132: of the specified file. The file is changed immediately on disk. This
3133: command is normally used with files that are @i{not} being visited in
3134: Emacs. Using it on a file that Emacs is visiting can produce confusing
3135: results, because the text inside Emacs for that file will not change
3136: while the file itself changes.
3137:
3138: @node Rectangles, Registers, Accumulating Text, Top
3139: @section Rectangles
3140: @cindex rectangles
3141:
3142: The rectangle commands affect rectangular areas of the text: all the
3143: characters between a certain pair of columns, in a certain range of lines.
3144: Commands are provided to kill rectangles, yank killed rectangles, clear
3145: them out, or delete them. Rectangle commands are useful with text in
3146: multicolumnar formats, such as perhaps code with comments at the right,
3147: or for changing text into or out of such formats.
3148:
3149: When you must specify a rectangle for a command to work on, you do
3150: it by putting the mark at one corner and point at the opposite corner.
3151: The rectangle thus specified is called the @dfn{region-rectangle}
3152: because it is controlled about the same way the region is controlled.
3153: But remember that a given combination of point and mark values can be
3154: interpreted either as specifying a region or as specifying a
3155: rectangle; it is up to the command that uses them to choose the
3156: interpretation.
3157:
3158: @table @kbd
3159: @item M-x delete-rectangle
3160: Delete the text of the region-rectangle, moving any following text on
3161: each line leftward to the left edge of the region-rectangle.
3162: @item M-x kill-rectangle
3163: Similar, but also save the contents of the region-rectangle as the
3164: ``last killed rectangle''.
3165: @item M-x yank-rectangle
3166: Yank the last killed rectangle with its upper left corner at point.
3167: @item M-x open-rectangle
3168: Insert blank space to fill the space of the region-rectangle.
3169: The previous contents of the region-rectangle are pushed rightward.
3170: @item M-x clear-rectangle
3171: Clear the region-rectangle by replacing its contents with spaces.
3172: @end table
3173:
3174: The rectangle operations fall into two classes: commands deleting and
3175: moving rectangles, and commands for blank rectangles.
3176:
3177: @findex delete-rectangle
3178: @findex kill-rectangle
3179: There are two ways to get rid of the text in a rectangle: you can discard
3180: the text (delete it) or save it as the ``last killed'' rectangle. The
3181: commands for these two ways are @kbd{M-x delete-rectangle} and @kbd{M-x
3182: kill-rectangle}. In either case, the portion of each line that falls inside
3183: the rectangle's boundaries is deleted, causing following text (if any) on
3184: the line to move left.
3185:
3186: Note that ``killing'' a rectangle is not killing in the usual sense; the
3187: rectangle is not stored in the kill ring, but in a special place that
3188: can only record the most recent rectangle killed. This is because yanking
3189: a rectangle is so different from yanking linear text that different yank
3190: commands have to be used and yank-popping is hard to make sense of.
3191:
3192: Inserting a rectangle is the opposite of deleting one. All you need to
3193: specify is where to put the upper left corner; that is done by putting
3194: point there. The rectangle's first line is inserted there, the rectangle's
3195: second line is inserted at a point one line vertically down, and so on.
3196: The number of lines affected is determined by the height of the saved
3197: rectangle.
3198:
3199: @findex yank-rectangle
3200: To insert the last killed rectangle, type @kbd{M-x yank-rectangle}.
3201: This can be used to convert single-column lists into double-column
3202: lists; kill the second half of the list as a rectangle and then
3203: yank it beside the first line of the list.
3204:
3205: @findex open-rectangle
3206: @findex clear-rectangle
3207: There are two commands for working with blank rectangles: @kbd{M-x
3208: clear-rectangle} to blank out existing text, and @kbd{M-x open-rectangle}
3209: to insert a blank rectangle. Clearing a rectangle is equivalent to
3210: deleting it and then inserting as blank rectangle of the same size.
3211:
3212: Rectangles can also be copied into and out of registers.
3213: @xref{RegRect,,Rectangle Registers}.
3214:
3215: @node Registers, Display, Rectangles, Top
3216: @chapter Registers
3217: @cindex registers
3218:
3219: Emacs @dfn{registers} are places you can save text or positions for
3220: later use. Text saved in a register can be copied into the buffer
3221: once or many times; a position saved in a register is used by moving
3222: point to that position. Rectangles can also be copied into and out of
3223: registers (@pxref{Rectangles}).
3224:
3225: Each register has a name, which is a single character. A register can
3226: store either a piece of text or a position or a rectangle, but only one
3227: thing at any given time. Whatever you store in a register remains
3228: there until you store something else in that register.
3229:
3230: @menu
3231: * RegPos:: Saving positions in registers.
3232: * RegText:: Saving text in registers.
3233: * RegRect:: Saving rectangles in registers.
3234: @end menu
3235:
3236: @table @kbd
3237: @item M-x view-register @key{RET} @var{r}
3238: Display a description of what register @var{r} contains.
3239: @end table
3240:
3241: @findex view-register
3242: @kbd{M-x view-register} reads a register name as an argument and then
3243: displays the contents of the specified register.
3244:
3245: @node RegPos, RegText, Registers, Registers
3246: @section Saving Positions in Registers
3247:
3248: Saving a position records a spot in a buffer so that you can move
3249: back there later. Moving to a saved position reselects the buffer
3250: and moves point to the spot.
3251:
3252: @table @kbd
3253: @item C-x / @var{r}
3254: Save location of point in register @var{r} (@code{point-to-register}).
3255: @item C-x j @var{r}
3256: Jump to the location saved in register @var{r} (@code{register-to-point}).
3257: @end table
3258:
3259: @kindex C-x /
3260: @findex point-to-register
3261: To save the current location of point in a register, choose a name
3262: @var{r} and type @kbd{C-x / @var{r}}. The register @var{r} retains
3263: the location thus saved until you store something else in that
3264: register.@refill
3265:
3266: @kindex C-x j
3267: @findex register-to-point
3268: The command @kbd{C-x j @var{r}} moves point to the location recorded
3269: in register @var{r}. The register is not affected; it continues to
3270: record the same location. You can jump to the same position using the
3271: same register any number of times.
3272:
3273: @node RegText, RegRect, RegPos, Registers
3274: @section Saving Text in Registers
3275:
3276: When you want to insert a copy of the same piece of text frequently, it
3277: may be impractical to use the kill ring, since each subsequent kill moves
3278: the piece of text further down on the ring. It becomes hard to keep track
3279: of what argument is needed to retrieve the same text with @kbd{C-y}. An
3280: alternative is to store the text in a register with @kbd{C-x x}
3281: (@code{copy-to-register}) and then retrieve it with @kbd{C-x g}
3282: (@code{insert-register}).
3283:
3284: @table @kbd
3285: @item C-x x @var{r}
3286: Copy region into register @var{r} (@code{copy-to-register}).
3287: @item C-x g @var{r}
3288: Insert text contents of register @var{r} (@code{insert-register}).
3289: @end table
3290:
3291: @kindex C-x x
3292: @kindex C-x g
3293: @findex copy-to-register
3294: @findex insert-register
3295: @kbd{C-x x @var{r}} stores a copy of the text of the region into the
3296: register named @var{r}. Given a numeric argument, @kbd{C-x x} deletes the
3297: text from the buffer as well.
3298:
3299: @kbd{C-x g @var{r}} inserts in the buffer the text from register @var{r}.
3300: Normally it leaves point before the text and places the mark after, but
3301: with a numeric argument it puts point after the text and the mark before.
3302:
3303: @node RegRect,, RegText, Registers
3304: @section Saving Rectangles in Registers
3305: @cindex rectangle
3306:
3307: A register can contain a rectangle instead of linear text. The rectangle
3308: is represented as a list of strings. @xref{Rectangles}, for basic
3309: information on rectangles and how rectangles in the buffer are specified.
3310:
3311: @table @kbd
3312: @item C-x r @var{r}
3313: Copy the region-rectangle into register @var{r} @*(@code{copy-region-to-rectangle}).
3314: With numeric argument, delete it as well.
3315: @item C-x g @var{r}
3316: Insert the rectangle stored in register @var{r} (if it contains a
3317: rectangle) (@code{insert-register}).
3318: @end table
3319:
3320: The @kbd{C-x g} command inserts linear text if the register contains
3321: that, or inserts a rectangle if the register contains one.
3322:
3323: @node Display, Search, Registers, Top
3324: @chapter Controlling the Display
3325:
3326: Since only part of a large buffer fits in the window, Emacs tries to show
3327: the part that is likely to be interesting. The display control commands
3328: allow you to specify which part of the text you want to see.
3329:
3330: @table @kbd
3331: @item C-l
3332: Clear screen and redisplay, scrolling the selected window to center
3333: point vertically within it (@code{recenter}).
3334: @item C-v
3335: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
3336: @item M-v
3337: Scroll backward (@code{scroll-down}).
3338: @item @var{arg} C-l
3339: Scroll so point is on line @var{arg} (@code{recenter}).
3340: @item C-x <
3341: Scroll text in current window to the left (@code{scroll-left}).
3342: @item C-x >
3343: Scroll to the right (@code{scroll-right}).
3344: @item C-x $
3345: Make deeply indented lines invisible (@code{set-selective-display}).
3346: @end table
3347:
3348: @menu
3349: * Scrolling:: Moving text up and down in a window.
3350: * Horizontal Scrolling:: Moving text left and right in a window.
3351: * Selective Display:: Hiding lines with lots of indentation.
3352: * Display Vars:: Information on variables for customizing display.
3353: @end menu
3354:
3355: @node Scrolling, Horizontal Scrolling, Display, Display
3356: @section Scrolling
3357:
3358: If a buffer contains text that is too large to fit entirely within a
3359: window that is displaying the buffer, Emacs shows a contiguous section of
3360: the text. The section shown always contains point.
3361:
3362: @cindex scrolling
3363: @dfn{Scrolling} means moving text up or down in the window so that
3364: different parts of the text are visible. Scrolling forward means that text
3365: moves up, and new text appears at the bottom. Scrolling backward moves
3366: text down and new text appears at the top.
3367:
3368: Scrolling happens automatically if you move point past the bottom or top
3369: of the window. You can also explicitly request scrolling with the commands
3370: in this section.
3371:
3372: @ifinfo
3373: @table @kbd
3374: @item C-l
3375: Clear screen and redisplay, scrolling the selected window to center
3376: point vertically within it (@code{recenter}).
3377: @item C-v
3378: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
3379: @item M-v
3380: Scroll backward (@code{scroll-down}).
3381: @item @var{arg} C-l
3382: Scroll so point is on line @var{arg} (@code{recenter}).
3383: @end table
3384: @end ifinfo
3385:
3386: @kindex C-l
3387: @findex recenter
3388: The most basic scrolling command is @kbd{C-l} (@code{recenter}) with no
3389: argument. It clears the entire screen and redisplays all windows. In
3390: addition, the selected window is scrolled so that point is halfway down
3391: from the top of the window.
3392:
3393: @kindex C-v
3394: @kindex M-v
3395: @findex scroll-up
3396: @findex scroll-down
3397: The scrolling commands @kbd{C-v} and @kbd{M-v} let you move all the text
3398: in the window up or down a few lines. @kbd{C-v} (@code{scroll-up}) with an
3399: argument shows you that many more lines at the bottom of the window, moving
3400: the text and point up together as @kbd{C-l} might. @kbd{C-v} with a
3401: negative argument shows you more lines at the top of the window.
3402: @kbd{Meta-v} (@code{scroll-down}) is like @kbd{C-v}, but moves in the
3403: opposite direction.@refill
3404:
3405: @vindex next-screen-context-lines
3406: To read the buffer a windowful at a time, use @kbd{C-v} with no argument.
3407: It takes the last two lines at the bottom of the window and puts them at
3408: the top, followed by nearly a whole windowful of lines not previously
3409: visible. If point was in the text scrolled off the top, it moves to the
3410: new top of the window. @kbd{M-v} with no argument moves backward with
3411: overlap similarly. The number of lines of overlap across a @kbd{C-v} or
3412: @kbd{M-v} is controlled by the variable @code{next-screen-context-lines}; by
3413: default, it is two.
3414:
3415: Another way to do scrolling is with @kbd{C-l} with a numeric argument.
3416: @kbd{C-l} does not clear the screen when given an argument; it only scrolls
3417: the selected window. With a positive argument @var{n}, it repositions text
3418: to put point @var{n} lines down from the top. An argument of zero puts
3419: point on the very top line. Point does not move with respect to the text;
3420: rather, the text and point move rigidly on the screen. @kbd{C-l} with a
3421: negative argument puts point that many lines from the bottom of the window.
3422: For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u
3423: - 5 C-l} puts it five lines from the bottom. Just @kbd{C-u} as argument,
3424: as in @kbd{C-u C-l}, scrolls point to the center of the screen.
3425:
3426: @vindex scroll-step
3427: Scrolling happens automatically if point has moved out of the visible
3428: portion of the text when it is time to display. Usually the scrolling is
3429: done so as to put point vertically centered within the window. However, if
3430: the variable @code{scroll-step} has a nonzero value, an attempt is made to
3431: scroll the buffer by that many lines; if that is enough to bring point back
3432: into visibility, that is what is done.
3433:
3434: @node Horizontal Scrolling,, Scrolling, Display
3435: @section Horizontal Scrolling
3436:
3437: @ifinfo
3438: @table @kbd
3439: @item C-x <
3440: Scroll text in current window to the left (@code{scroll-left}).
3441: @item C-x >
3442: Scroll to the right (@code{scroll-right}).
3443: @end table
3444: @end ifinfo
3445:
3446: @kindex C-x <
3447: @kindex C-x >
3448: @findex scroll-left
3449: @findex scroll-right
3450: @cindex horizontal scrolling
3451: The text in a window can also be scrolled horizontally. This means that
3452: each line of text is shifted sideways in the window, and one or more
3453: characters at the beginning of each line are not displayed at all. When a
3454: window has been scrolled horizontally in this way, text lines are truncated
3455: rather than continued (@pxref{Continuation Lines}), with a @samp{$} appearing
3456: in the first column when there is text truncated to the left, and in the
3457: last column when there is text truncated to the right.
3458:
3459: The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected window
3460: to the left by @var{n} columns with argument @var{n}. With no argument, it scrolls
3461: by almost the full width of the window (two columns less, to be precise).
3462: @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right.
3463: The window cannot be scrolled any farther to the right once it is
3464: displaying normally (with each line starting at the window's left margin);
3465: attempting to do so has no effect.
3466:
3467: @node Selective Display, Display Vars, Display, Display
3468: @section Selective Display
3469: @findex set-selective-display
3470: @kindex C-x $
3471:
3472: Emacs has the ability to hide lines indented more than a certain number
3473: of columns (you specify how many columns). You can use this to get an
3474: overview of a part of a program.
3475:
3476: To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a
3477: numeric argument @var{n}. (@xref{Arguments}, for how to give the
3478: argument.) Then lines with at least @var{n} columns of indentation
3479: disappear from the screen. The only indication of their presence is that
3480: three dots (@samp{@dots{}}) appear at the end of each visible line that is
3481: followed by one or more invisible ones.@refill
3482:
3483: The invisible lines are still present in the buffer, and most editing
3484: commands see them as usual, so it is very easy to put point in the middle
3485: of invisible text. When this happens, the cursor appears at the end of the
3486: previous line, after the three dots. If point is at the end of the visible
3487: line, before the newline that ends it, the cursor appears before the three
3488: dots.
3489:
3490: The commands @kbd{C-n} and @kbd{C-p} move across the invisible lines as if they
3491: were not there.
3492:
3493: To make everything visible again, type @kbd{C-x $} with no argument.
3494:
3495: @node Display Vars,, Selective Display, Display
3496: @section Variables Controlling Display
3497:
3498: This section contains information for customization only. Beginning
3499: users should skip it.
3500:
3501: @vindex mode-line-inverse-video
3502: The variable @code{mode-line-inverse-video} controls whether the mode
3503: line is displayed in inverse video (assuming the terminal supports it);
3504: @code{nil} means don't do so. @xref{Mode Line}.
3505:
3506: @vindex inverse-video
3507: If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
3508: to invert all the lines of the display from what they normally are.
3509:
3510: @vindex visible-bell
3511: If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
3512: to make the whole screen blink when it would normally make an audible bell
3513: sound. This variable has no effect if your terminal does not have a way
3514: to make the screen blink.@refill
3515:
3516: @vindex no-redraw-on-reenter
3517: When you reenter Emacs after suspending, Emacs normally clears the screen
3518: and redraws the entire display. On some terminals with more than one page
3519: of memory, it is possible to arrange the termcap entry so that the
3520: @samp{ti} and @samp{te} strings (output to the terminal when Emacs is
3521: entered and exited, respectively) switch between pages of memory so as to
3522: use one page for Emacs and another page for other output. Then you might
3523: want to set the variable @code{no-redraw-on-reenter} non-@code{nil} so that
3524: Emacs will assume, when resumed, that the screen page it is using still
3525: contains what Emacs last wrote there.
3526:
3527: @vindex echo-keystrokes
3528: The variable @code{echo-keystrokes} controls the echoing of multi-character
3529: keys; its value is the number of seconds of pause required to cause echoing
3530: to start, or zero meaning don't echo at all. @xref{Echo Area}.
3531:
3532: @vindex ctl-arrow
3533: If the variable @code{ctl-arrow} is @code{nil}, control characters in the
3534: buffer are displayed with octal escape sequences, all except newline and
3535: tab. Altering the value of @code{ctl-arrow} makes it local to the current
3536: buffer; until that time, the default value is in effect. The default is
3537: initially @code{t}. @xref{Locals}.
3538:
3539: @vindex tab-width
3540: Normally, a tab character in the buffer is displayed as whitespace which
3541: extends to the next display tab stop position, and display tab stops come
3542: at intervals equal to eight spaces. The number of spaces per tab is
3543: controlled by the variable @code{tab-width}, which is made local by
3544: changing it, just like @code{ctl-arrow}. Note that how the tab character
3545: in the buffer is displayed has nothing to do with the definition of
3546: @key{TAB} as a command.
3547:
3548: @vindex selective-display-ellipses
3549: If you set the variable @code{selective-display-ellipses} to @code{nil},
3550: the three dots do not appear at the end of a line that precedes invisible
3551: lines. Then there is no visible indication of the invisible lines.
3552: This variable too becomes local automatically when set.
3553:
3554: @node Search, Fixit, Display, Top
3555: @chapter Searching and Replacement
3556: @cindex searching
3557:
3558: Like other editors, Emacs has commands for searching for occurrences of
3559: a string. The principal search command is unusual in that it is
3560: @dfn{incremental}; it begins to search before you have finished typing the
3561: search string. There are also nonincremental search commands more like
3562: those of other editors.
3563:
3564: Besides the usual @code{replace-string} command that finds all
3565: occurrences of one string and replaces them with another, Emacs has a fancy
3566: replacement command called @code{query-replace} which asks interactively
3567: which occurrences to replace.
3568:
3569: @menu
3570: * Incremental Search:: Search happens as you type the string.
3571: * Nonincremental Search:: Specify entire string and then search.
3572: * Word Search:: Search for sequence of words.
3573: * Regexp Search:: Search for match for a regexp.
3574: * Regexps:: Syntax of regular expressions.
3575: * Search Case:: To ignore case while searching, or not.
3576: * Replace:: Search, and replace some or all matches.
3577: * Other Repeating Search:: Operating on all matches for some regexp.
3578: @end menu
3579:
3580: @node Incremental Search, Nonincremental Search, Search, Search
3581: @section Incremental Search
3582:
3583: An incremental search begins searching as soon as you type the first
3584: character of the search string. As you type in the search string, Emacs
3585: shows you where the string (as you have typed it so far) would be found.
3586: When you have typed enough characters to identify the place you want, you
3587: can stop. Depending on what you will do next, you may or may not need to
3588: terminate the search explicitly with an @key{ESC} first.
3589:
3590: @c WideCommands
3591: @table @kbd
3592: @item C-s
3593: Incremental search forward (@code{isearch-forward}).
3594: @item C-r
3595: Incremental search backward (@code{isearch-backward}).
3596: @end table
3597:
3598: @kindex C-s
3599: @kindex C-r
3600: @findex isearch-forward
3601: @findex isearch-backward
3602: @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from
3603: the keyboard and positions the cursor at the first occurrence of the
3604: characters that you have typed. If you type @kbd{C-s} and then @kbd{F},
3605: the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see
3606: the cursor move to after the first @samp{FO}. After another @kbd{O}, the
3607: cursor is after the first @samp{FOO} after the place where you started the
3608: search. Meanwhile, the search string @samp{FOO} has been echoed in the
3609: echo area.@refill
3610:
3611: The echo area display ends with three dots when actual searching is going
3612: on. When search is waiting for more input, the three dots are removed.
3613: (On slow terminals, the three dots are not displayed.)
3614:
3615: If you make a mistake in typing the search string, you can erase
3616: characters with @key{DEL}. Each @key{DEL} cancels the last character of
3617: search string. This does not happen until Emacs is ready to read another
3618: input character; first it must either find, or fail to find, the character
3619: you want to erase. If you do not want to wait for this to happen, use
3620: @kbd{C-g} as described below.@refill
3621:
3622: When you are satisfied with the place you have reached, you can type
3623: @key{ESC}, which stops searching, leaving the cursor where the search
3624: brought it. Also, any command not specially meaningful in searches stops
3625: the searching and is then executed. Thus, typing @kbd{C-a} would exit the
3626: search and then move to the beginning of the line. @key{ESC} is necessary
3627: only if the next command you want to type is a printing character,
3628: @key{DEL}, @key{ESC}, or another control character that is special within
3629: searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s} or @kbd{C-y}).
3630:
3631: Sometimes you search for @samp{FOO} and find it, but not the one you
3632: expected to find. There was a second @samp{FOO} that you forgot about,
3633: before the one you were looking for. In this event, type another @kbd{C-s}
3634: to move to the next occurrence of the search string. This can be done any
3635: number of times. If you overshoot, you can cancel some @kbd{C-s}
3636: characters with @key{DEL}.
3637:
3638: After you exit a search, you can search for the same string again by
3639: typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
3640: incremental search, and the second @kbd{C-s} means ``search again''.
3641:
3642: If your string is not found at all, the echo area says @samp{Failing
3643: I-Search}. The cursor is after the place where Emacs found as much of your
3644: string as it could. Thus, if you search for @samp{FOOT}, and there is no
3645: @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
3646: At this point there are several things you can do. If your string was
3647: mistyped, you can rub some of it out and correct it. If you like the place
3648: you have found, you can type @key{ESC} or some other Emacs command to
3649: ``accept what the search offered''. Or you can type @kbd{C-g}, which
3650: removes from the search string the characters that could not be found (the
3651: @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
3652: @samp{FOOT}). A second @kbd{C-g} at that point cancels the search
3653: entirely, returning point to where it was when the search started.
3654:
3655: If a search is failing and you ask to repeat it by typing another
3656: @kbd{C-s}, it starts again from the beginning of the buffer. Repeating
3657: a failing reverse search with @kbd{C-r} starts again from the end. This
3658: is called @dfn{wrapping around}. @samp{Wrapped} appears in the search
3659: prompt once this has happened.
3660:
3661: @cindex quitting (in search)
3662: The @kbd{C-g} ``quit'' character does special things during searches;
3663: just what it does depends on the status of the search. If the search has
3664: found what you specified and is waiting for input, @kbd{C-g} cancels the
3665: entire search. The cursor moves back to where you started the search. If
3666: @kbd{C-g} is typed when there are characters in the search string that have
3667: not been found---because Emacs is still searching for them, or because it
3668: has failed to find them---then the search string characters which have not
3669: been found are discarded from the search string. With them gone, the
3670: search is now successful and waiting for more input, so a second @kbd{C-g}
3671: will cancel the entire search.
3672:
3673: To search for a control character such as @kbd{C-s} or @key{DEL} or @key{ESC},
3674: you must quote it by typing @kbd{C-q} first. This function of @kbd{C-q} is
3675: analogous to its meaning as an Emacs command: it causes the following
3676: character to be treated the way a graphic character would normally be
3677: treated in the same context.
3678:
3679: You can change to searching backwards with @kbd{C-r}. If a search fails
3680: because the place you started was too late in the file, you should do this.
3681: Repeated @kbd{C-r} keeps looking for more occurrences backwards. A
3682: @kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be cancelled
3683: with @key{DEL}.
3684:
3685: If you know initially that you want to search backwards, you can
3686: use @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r}
3687: is also a key running a command (@code{isearch-backward}) to search
3688: backward.
3689:
3690: The characters @kbd{C-y} and @kbd{C-w} can be used in incremental search
3691: to grab text from the buffer into the search string. This makes it
3692: convenient to search for another occurrence of text at point. @kbd{C-w}
3693: copies the word after point as part of the search string, advancing
3694: point over that word. Another @kbd{C-s} to repeat the search will then
3695: search for a string including that word. @kbd{C-y} is similar to @kbd{C-w}
3696: but copies all the rest of the current line into the search string.
3697:
3698: All the characters special in incremental search can be changed by setting
3699: the following variables:
3700:
3701: @vindex search-delete-char
3702: @vindex search-exit-char
3703: @vindex search-quote-char
3704: @vindex search-repeat-char
3705: @vindex search-reverse-char
3706: @vindex search-yank-line-char
3707: @vindex search-yank-word-char
3708: @table @code
3709: @item search-delete-char
3710: Character to delete from incremental search string (normally @key{DEL}).
3711: @item search-exit-char
3712: Character to exit incremental search (normally @key{ESC}).
3713: @item search-quote-char
3714: Character to quote special characters for incremental search (normally
3715: @kbd{C-q}).
3716: @item search-repeat-char
3717: Character to repeat incremental search forwards (normally @kbd{C-s}).
3718: @item search-reverse-char
3719: Character to repeat incremental search backwards (normally @kbd{C-r}).
3720: @item search-yank-line-char
3721: Character to pull rest of line from buffer into search string
3722: (normally @kbd{C-y}).
3723: @item search-yank-word-char
3724: Character to pull next word from buffer into search string (normally
3725: @kbd{C-w}).
3726: @end table
3727:
3728: @subsection Slow Terminal Incremental Search
3729:
3730: Incremental search on a slow terminal uses a modified style of display
3731: that is designed to take less time. Instead of redisplaying the buffer at
3732: each place the search gets to, it creates a new single-line window and uses
3733: that to display the line that the search has found. The single-line window
3734: comes into play as soon as point gets outside of the text that is already
3735: on the screen.
3736:
3737: When the search is terminated, the single-line window is removed. Only
3738: at this time is the window in which the search was done redisplayed to show
3739: its new value of point.
3740:
3741: The three dots at the end of the search string, normally used to indicate
3742: that searching is going on, are not displayed in slow style display.
3743:
3744: @vindex search-slow-speed
3745: The slow terminal style of display is used when the terminal baud rate is
3746: less than or equal to the value of the variable @code{search-slow-speed},
3747: initially 1200.
3748:
3749: @vindex search-slow-window-lines
3750: The number of lines to use in slow terminal search display is controlled
3751: by the variable @code{search-slow-window-lines}. 1 is its normal value.
3752:
3753: @node Nonincremental Search, Word Search, Incremental Search, Search
3754: @section Nonincremental Search
3755: @cindex nonincremental search
3756:
3757: Emacs also has conventional nonincremental search commands, which require
3758: you to type the entire search string before searching begins.
3759:
3760: @table @kbd
3761: @item C-s @key{ESC} @var{string} @key{RET}
3762: Search for @var{string}.
3763: @item C-r @key{ESC} @var{string} @key{RET}
3764: Search backward for @var{string}.
3765: @end table
3766:
3767: To do a nonincremental search, first type @kbd{C-s @key{ESC}}. This
3768: enters the minibuffer to read the search string; terminate the string with
3769: @key{RET}, and then the search is done. If the string is not found the
3770: search command gets an error.
3771:
3772: The way @kbd{C-s @key{ESC}} works is that the @kbd{C-s} invokes
3773: incremental search, which is specially programmed to invoke nonincremental
3774: search if the argument you give it is empty. (Such an empty argument would
3775: otherwise be useless.) @kbd{C-r @key{ESC}} also works this way.
3776:
3777: @findex search-forward
3778: @findex search-backward
3779: Forward and backward nonincremental searches are implemented by the
3780: commands @code{search-forward} and @code{search-backward}. These commands
3781: may be bound to keys in the usual manner. The reason that incremental
3782: search is programmed to invoke them as well is that @kbd{C-s @key{ESC}}
3783: is the traditional sequence of characters used in Emacs to invoke
3784: nonincremental search.
3785:
3786: However, nonincremental searches performed using @kbd{C-s @key{ESC}} do
3787: not call @code{search-forward} right away. The first thing done is to see
3788: if the next character is @kbd{C-w}, which requests a word search.
3789: @ifinfo
3790: @xref{Word Search}.
3791: @end ifinfo
3792:
3793: @node Word Search, Regexp Search, Nonincremental Search, Search
3794: @section Word Search
3795: @cindex word search
3796:
3797: Word search searches for a sequence of words without regard to how the
3798: words are separated. More precisely, you type a string of many words,
3799: using single spaces to separate them, and the string can be found even if
3800: there are multiple spaces, newlines or other punctuation between the words.
3801:
3802: Word search is useful in editing documents formatted by text formatters.
3803: If you edit while looking at the printed, formatted version, you can't tell
3804: where the line breaks are in the source file. With word search, you can
3805: search without having to know them.
3806:
3807: @table @kbd
3808: @item C-s @key{ESC} C-w @var{words} @key{RET}
3809: Search for @var{words}, ignoring differences in punctuation.
3810: @item C-r @key{ESC} C-w @var{words} @key{RET}
3811: Search backward for @var{words}, ignoring differences in punctuation.
3812: @end table
3813:
3814: Word search is a special case of nonincremental search and is invoked
3815: with @kbd{C-s @key{ESC} C-w}. This is followed by the search string, which
3816: must always be terminated with @key{RET}. Being nonincremental, this
3817: search does not start until the argument is terminated. It works by
3818: constructing a regular expression and searching for that. @xref{Regexp
3819: Search}.
3820:
3821: A backward word search can be done by @kbd{C-r @key{ESC} C-w}.
3822:
3823: @findex word-search-forward
3824: @findex word-search-backward
3825: Forward and backward word searches are implemented by the commands
3826: @code{word-search-forward} and @code{word-search-backward}. These commands
3827: may be bound to keys in the usual manner. The reason that incremental
3828: search is programmed to invoke them as well is that @kbd{C-s @key{ESC} C-w}
3829: is the traditional Emacs sequence of keys for word search.
3830:
3831: @node Regexp Search, Regexps, Word Search, Search
3832: @section Regular Expression Search
3833: @cindex regular expression
3834: @cindex regexp
3835:
3836: A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
3837: denotes a set of strings, possibly an infinite set. Searching for matches
3838: for a regexp is a very powerful operation that editors on Unix systems have
3839: traditionally offered. In GNU Emacs, you can search for the next match for
3840: a regexp either incrementally or not.
3841:
3842: @kindex C-M-s
3843: @findex isearch-forward-regexp
3844: @findex isearch-backward-regexp
3845: Incremental search for a regexp is done by typing @kbd{C-M-s}
3846: (@code{isearch-forward-regexp}). This command reads a search string
3847: incrementally just like @kbd{C-s}, but it treats the search string as a
3848: regexp rather than looking for an exact match against the text in the
3849: buffer. Each time you add text to the search string, you make the regexp
3850: longer, and the new regexp is searched for. A reverse regexp search command
3851: @code{isearch-backward-regexp} also exists but no key runs it.
3852:
3853: All of the control characters that do special things within an ordinary
3854: incremental search have the same function in incremental regexp search.
3855: Typing @kbd{C-s} or @kbd{C-r} immediately after starting the search
3856: retrieves the last incremental search regexp used; that is to say,
3857: incremental regexp and non-regexp searches have independent defaults.
3858:
3859: Note that adding characters to the regexp in an incremental regexp search
3860: does not make the cursor move back and start again. Perhaps it ought to; I
3861: am not sure. As it stands, if you have searched for @samp{foo} and you
3862: add @samp{\|bar}, the search will not check for a @samp{bar} in the
3863: buffer before the @samp{foo}.
3864:
3865: @findex re-search-forward
3866: @findex re-search-backward
3867: Nonincremental search for a regexp is done by the functions
3868: @code{re-search-forward} and @code{re-search-backward}. You can invoke
3869: these with @kbd{M-x}, or bind them to keys. Also, you can call
3870: @code{re-search-forward} by way of incremental regexp search with
3871: @kbd{C-M-s @key{ESC}}.
3872:
3873: @node Regexps, Search Case, Regexp Search, Search
3874: @section Syntax of Regular Expressions
3875:
3876: Regular expressions have a syntax in which a few characters are special
3877: constructs and the rest are @dfn{ordinary}. An ordinary character is a
3878: simple regular expression which matches that character and nothing else.
3879: The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*},
3880: @samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}; no new special
3881: characters will be defined. Any other character appearing in a regular
3882: expression is ordinary, unless a @samp{\} precedes it.@refill
3883:
3884: For example, @samp{f} is not a special character, so it is ordinary, and
3885: therefore @samp{f} is a regular expression that matches the string @samp{f}
3886: and no other string. (It does @i{not} match the string @samp{ff}.) Likewise,
3887: @samp{o} is a regular expression that matches only @samp{o}.@refill
3888:
3889: Any two regular expressions @var{a} and @var{b} can be concatenated. The
3890: result is a regular expression which matches a string if @var{a} matches
3891: some amount of the beginning of that string and @var{b} matches the rest of
3892: the string.@refill
3893:
3894: As a simple example, we can concatenate the regular expressions @samp{f}
3895: and @samp{o} to get the regular expression @samp{fo}, which matches only
3896: the string @samp{fo}. Still trivial. To do something nontrivial, you
3897: need to use one of the special characters. Here is a list of them.
3898:
3899: @table @kbd
3900: @item .@: @r{(Period)}
3901: is a special character that matches any single character except a newline.
3902: Using concatenation, we can make regular expressions like @samp{a.b} which
3903: matches any three-character string which begins with @samp{a} and ends with
3904: @samp{b}.@refill
3905:
3906: @item *
3907: is not a construct by itself; it is a suffix, which means the
3908: preceding regular expression is to be repeated as many times as
3909: possible. In @samp{fo*}, the @samp{*} applies to the @samp{o}, so
3910: @samp{fo*} matches one @samp{f} followed by any number of @samp{o}s.
3911: The case of zero @samp{o}s is allowed: @samp{fo*} does match
3912: @samp{f}.@refill
3913:
3914: @samp{*} always applies to the @i{smallest} possible preceding
3915: expression. Thus, @samp{fo*} has a repeating @samp{o}, not a
3916: repeating @samp{fo}.@refill
3917:
3918: The matcher processes a @samp{*} construct by matching, immediately,
3919: as many repetitions as can be found. Then it continues with the rest
3920: of the pattern. If that fails, backtracking occurs, discarding some
3921: of the matches of the @samp{*}-modified construct in case that makes
3922: it possible to match the rest of the pattern. For example, matching
3923: @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
3924: tries to match all three @samp{a}s; but the rest of the pattern is
3925: @samp{ar} and there is only @samp{r} left to match, so this try fails.
3926: The next alternative is for @samp{a*} to match only two @samp{a}s.
3927: With this choice, the rest of the regexp matches successfully.@refill
3928:
3929: @item +
3930: Is a suffix character similar to @samp{*} except that it requires that
3931: the preceding expression be matched at least once. So, for example,
3932: @samp{ca+r} will match the strings @samp{car} and @samp{caaaar}
3933: but not the string @samp{cr}, whereas @samp{ca*r} would match all
3934: three strings.@refill
3935:
3936: @item ?
3937: Is a suffix character similar to @samp{*} except that it can match the
3938: preceding expression either once or not at all. For example,
3939: @samp{ca?r} will match @samp{car} or @samp{cr}; nothing else.
3940:
3941: @item [ @dots{} ]
3942: @samp{[} begins a @dfn{character set}, which is terminated by a
3943: @samp{]}. In the simplest case, the characters between the two form
3944: the set. Thus, @samp{[ad]} matches either one @samp{a} or one
3945: @samp{d}, and @samp{[ad]*} matches any string composed of just
3946: @samp{a}s and @samp{d}s (including the empty string), from which it
3947: follows that @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
3948: @samp{caddaar}, etc.@refill
3949:
3950: Character ranges can also be included in a character set, by writing
3951: two characters with a @samp{-} between them. Thus, @samp{[a-z]}
3952: matches any lower-case letter. Ranges may be intermixed freely with
3953: individual characters, as in @samp{[a-z$%.]}, which matches any lower
3954: case letter or @samp{$}, @samp{%} or period.@refill
3955:
3956: Note that the usual special characters are not special any more inside
3957: a character set. A completely different set of special characters
3958: exists inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
3959:
3960: To include a @samp{]} in a character set, you must make it the first
3961: character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
3962: include a @samp{-}, write @samp{---}, which is a range containing only
3963: @samp{-}. To include @samp{^}, make it other than the first character
3964: in the set.@refill
3965:
3966: @item [^ @dots{} ]
3967: @samp{[^} begins a @dfn{complement character set}, which matches any
3968: character except the ones specified. Thus, @samp{[^a-z0-9A-Z]}
3969: matches all characters @i{except} letters and digits.@refill
3970:
3971: @samp{^} is not special in a character set unless it is the first
3972: character. The character following the @samp{^} is treated as if it
3973: were first (@samp{-} and @samp{]} are not special there).
3974:
3975: Note that a complement character set can match a newline, unless
3976: newline is mentioned as one of the characters not to match.
3977:
3978: @item ^
3979: is a special character that matches the empty string, but only if at
3980: the beginning of a line in the text being matched. Otherwise it fails
3981: to match anything. Thus, @samp{^foo} matches a @samp{foo} which occurs
3982: at the beginning of a line.
3983:
3984: @item $
3985: is similar to @samp{^} but matches only at the end of a line. Thus,
3986: @samp{xx*$} matches a string of one @samp{x} or more at the end of a line.
3987:
3988: @item \
3989: has two functions: it quotes the special characters (including
3990: @samp{\}), and it introduces additional special constructs.
3991:
3992: Because @samp{\} quotes special characters, @samp{\$} is a regular
3993: expression which matches only @samp{$}, and @samp{\[} is a regular
3994: expression which matches only @samp{[}, and so on.@refill
3995: @end table
3996:
3997: Note: for historical compatibility, special characters are treated as
3998: ordinary ones if they are in contexts where their special meanings make no
3999: sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is
4000: no preceding expression on which the @samp{*} can act. It is poor practice
4001: to depend on this behavior; better to quote the special character anyway,
4002: regardless of where is appears.@refill
4003:
4004: For the most part, @samp{\} followed by any character matches only
4005: that character. However, there are several exceptions: characters
4006: which, when preceded by @samp{\}, are special constructs. Such
4007: characters are always ordinary when encountered on their own. Here
4008: is a table of @samp{\} constructs.
4009:
4010: @table @kbd
4011: @item \|
4012: specifies an alternative.
4013: Two regular expressions @var{a} and @var{b} with @samp{\|} in
4014: between form an expression that matches anything that either @var{a} or
4015: @var{b} will match.@refill
4016:
4017: Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
4018: but no other string.@refill
4019:
4020: @samp{\|} applies to the largest possible surrounding expressions. Only a
4021: surrounding @samp{$ @dots{} $} grouping can limit the grouping power of
4022: @samp{\|}.@refill
4023:
4024: Full backtracking capability exists to handle multiple uses of @samp{\|}.
4025:
4026: @item $ @dots{} $
4027: is a grouping construct that serves three purposes:
4028:
4029: @enumerate
4030: @item
4031: To enclose a set of @samp{\|} alternatives for other operations.
4032: Thus, @samp{$foo\|bar$x} matches either @samp{foox} or @samp{barx}.
4033:
4034: @item
4035: To enclose a complicated expression for the postfix @samp{*} to operate on.
4036: Thus, @samp{ba$na$*} matches @samp{bananana}, etc., with any (zero or
4037: more) number of @samp{na} strings.@refill
4038:
4039: @item
4040: To mark a matched substring for future reference.
4041:
4042: @end enumerate
4043:
4044: This last application is not a consequence of the idea of a
4045: parenthetical grouping; it is a separate feature which happens to be
4046: assigned as a second meaning to the same @samp{$ @dots{} $} construct
4047: because there is no conflict in practice between the two meanings.
4048: Here is an explanation of this feature:
4049:
4050: @item \@var{digit}
4051: after the end of a @samp{$ @dots{} $} construct, the matcher remembers the
4052: beginning and end of the text matched by that construct. Then, later on
4053: in the regular expression, you can use @samp{\} followed by @var{digit}
4054: to mean ``match the same text matched the @var{digit}'th time by the
4055: @samp{$ @dots{} $} construct.''@refill
4056:
4057: The strings matching the first nine @samp{$ @dots{} $} constructs appearing
4058: in a regular expression are assigned numbers 1 through 9 in order that the
4059: open-parentheses appear in the regular expression. @samp{\1} through
4060: @samp{\9} may be used to refer to the text matched by the corresponding
4061: @samp{$ @dots{} $} construct.
4062:
4063: For example, @samp{$.*$\1} matches any newline-free string that is
4064: composed of two identical halves. The @samp{$.*$} matches the first
4065: half, which may be anything, but the @samp{\1} that follows must match
4066: the same exact text.
4067:
4068: @item \`
4069: matches the empty string, provided it is at the beginning
4070: of the buffer.
4071:
4072: @item \'
4073: matches the empty string, provided it is at the end of
4074: the buffer.
4075:
4076: @item \b
4077: matches the empty string, provided it is at the beginning or
4078: end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
4079: @samp{foo} as a separate word. @samp{\bballs?\b} matches
4080: @samp{ball} or @samp{balls} as a separate word.@refill
4081:
4082: @item \B
4083: matches the empty string, provided it is @i{not} at the beginning or
4084: end of a word.
4085:
4086: @item \<
4087: matches the empty string, provided it is at the beginning of a word.
4088:
4089: @item \>
4090: matches the empty string, provided it is at the end of a word.
4091:
4092: @item \w
4093: matches any word-constituent character. The editor syntax table
4094: determines which characters these are.
4095:
4096: @item \W
4097: matches any character that is not a word-constituent.
4098:
4099: @item \s@var{code}
4100: matches any character whose syntax is @var{code}. @var{code} is a
4101: character which represents a syntax code: thus, @samp{w} for word
4102: constituent, @samp{-} for whitespace, @samp{(} for open-parenthesis,
4103: etc. @xref{Syntax}.@refill
4104:
4105: @item \S@var{code}
4106: matches any character whose syntax is not @var{code}.
4107: @end table
4108:
4109: Here is a complicated regexp, used by Emacs to recognize the end of a
4110: sentence together with any whitespace that follows. It is given in Lisp
4111: syntax to enable you to distinguish the spaces from the tab characters. In
4112: Lisp syntax, the string constant begins and ends with a double-quote.
4113: @samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a
4114: backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a
4115: newline.
4116:
4117: @example
4118: "[.?!][]\"')]*\$$\\|\t\\| \$[ \t\n]*"
4119: @end example
4120:
4121: @noindent
4122: This contains four parts in succession: a character set matching period,
4123: @samp{?} or @samp{!}; a character set matching close-brackets,
4124: quotes or parentheses, repeated any number of times; an alternative in
4125: backslash-parentheses that matches end-of-line, a tab or two spaces; and a
4126: character set matching whitespace characters, repeated any number of times.
4127:
4128: @node Search Case, Replace, Regexps, Search
4129: @section Searching and Case
4130:
4131: @vindex case-fold-search
4132: All sorts of searches in Emacs normally ignore the case of the text they
4133: are searching through; if you specify searching for @samp{FOO}, then
4134: @samp{Foo} and @samp{foo} are also considered a match. Regexps, and in
4135: particular character sets, are included: @samp{[aB]} would match @samp{a}
4136: or @samp{A} or @samp{b} or @samp{B}.@refill
4137:
4138: If you do not want this feature, set the variable @code{case-fold-search}
4139: to @code{nil}. Then all letters must match exactly, including case. This
4140: is a per-buffer variable; altering the variable affects only the current
4141: buffer, but there is a default value which you can change as well.
4142: @xref{Locals}.
4143:
4144: @node Replace, Other Repeating Search, Search Case, Search
4145: @section Replacement Commands
4146: @cindex replacement
4147: @cindex string substitution
4148: @cindex global substitution
4149:
4150: Global search-and-replace operations are not needed as often in Emacs as
4151: they are in other editors, but they are available. In addition to the
4152: simple @code{replace-string} command which is like that found in most
4153: editors, there is a @code{query-replace} command which asks you, for each
4154: occurrence of the pattern, whether to replace it.
4155:
4156: The replace commands all replace one string (or regexp) with one
4157: replacement string. It is possible to perform several replacements in
4158: parallel using the command @code{expand-region-abbrevs}. @xref{Expanding
4159: Abbrevs}.
4160:
4161: @menu
4162: * Unconditional Replace:: Replacing all matches for a string.
4163: * Regexp Replace:: Replacing all matches for a regexp.
4164: * Replacement and Case:: How replacements preserve case of letters.
4165: * Query Replace:: How to use querying.
4166: @end menu
4167:
4168: @node Unconditional Replace, Regexp Replace, Replace, Replace
4169: @subsection Unconditional Replacement
4170: @findex replace-string
4171: @findex replace-regexp
4172:
4173: @table @kbd
4174: @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
4175: Replace every occurrence of @var{string} with @var{newstring}.
4176: @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
4177: Replace every match for @var{regexp} with @var{newstring}.
4178: @end table
4179:
4180: To replace every instance of @samp{foo} after point with @samp{bar}, use
4181: the command @kbd{M-x replace-string} with the two arguments @samp{foo} and
4182: @samp{bar}. Replacement occurs only after point, so if you want to cover
4183: the whole buffer you must go to the beginning first. All occurrences up to
4184: the end of the buffer are replaced; to limit replacement to part of the
4185: buffer, narrow to that part of the buffer before doing the replacement
4186: (@pxref{Narrowing}).
4187:
4188: When @code{replace-string} exits, point is left at the last occurrence
4189: replaced. The value of point when the @code{replace-string} command was
4190: issued is remembered on the mark ring; @kbd{C-u C-@key{SPC}} moves back
4191: there.
4192:
4193: A numeric argument restricts replacement to matches that are surrounded
4194: by word boundaries.
4195:
4196: @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
4197: @subsection Regexp Replacement
4198:
4199: @code{replace-string} replaces exact matches for a single string. The
4200: similar command @code{replace-regexp} replaces any match for a specified
4201: pattern.
4202:
4203: In @code{replace-regexp}, the @var{newstring} need not be constant. It
4204: can refer to all or part of what is matched by the @var{regexp}. @samp{\&}
4205: in @var{newstring} stands for the entire text being replaced.
4206: @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for
4207: whatever matched the @var{d}'th parenthesized grouping in @var{regexp}.
4208: For example,@refill
4209:
4210: @example
4211: M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
4212: @end example
4213:
4214: @noindent
4215: would replace (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
4216: with @samp{cddr-safe}.
4217:
4218: @example
4219: M-x replace-regexp @key{RET} $c[ad]+r$-safe @key{RET} \1 @key{RET}
4220: @end example
4221:
4222: @noindent
4223: would perform exactly the opposite replacements. To include a @samp{\}
4224: in the text to replace with, you must give @samp{\\}.
4225:
4226: @node Replacement and Case, Query Replace, Regexp Replace, Replace
4227: @subsection Replace Commands and Case
4228:
4229: @vindex case-replace
4230: @vindex case-fold-search
4231: If the arguments to a replace command are in lower case, it preserves
4232: case when it makes a replacement. Thus, the command
4233:
4234: @example
4235: M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
4236: @end example
4237:
4238: @noindent
4239: replaces a lower case @samp{foo} with a lower case @samp{bar}, @samp{FOO}
4240: with @samp{BAR}, and @samp{Foo} with @samp{Bar}. If upper case letters are
4241: used in the second argument, they remain upper case every time that
4242: argument is inserted. If upper case letters are used in the first
4243: argument, the second argument is always substituted exactly as given, with
4244: no case conversion. Likewise, if the variable @code{case-replace} is set
4245: to @code{nil}, replacement is done without case conversion. If
4246: @code{case-fold-search} is set to @code{nil}, case is significant in
4247: matching occurrences of @samp{foo} to replace; also, case conversion of the
4248: replacement string is not done.
4249:
4250: @node Query Replace,, Replacement and Case, Replace
4251: @subsection Query Replace
4252: @cindex query replace
4253:
4254: @table @kbd
4255: @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
4256: @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
4257: Replace some occurrences of @var{string} with @var{newstring}.
4258: @item M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
4259: Replace some matches for @var{regexp} with @var{newstring}.
4260: @end table
4261:
4262: @kindex M-%
4263: @findex query-replace
4264: If you want to change only some of the occurrences of @samp{foo} to
4265: @samp{bar}, not all of them, then you cannot use an ordinary
4266: @code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}).
4267: This command finds occurrences of @samp{foo} one by one, displays each
4268: occurrence and asks you whether to replace it. A numeric argument to
4269: @code{query-replace} tells it to consider only occurrences that are bounded
4270: by word-delimiter characters.@refill
4271:
4272: @findex query-replace-regexp
4273: Aside from querying, @code{query-replace} works just like
4274: @code{replace-string}, and @code{query-replace-regexp} works
4275: just like @code{replace-regexp}.@refill
4276:
4277: The things you can type when you are shown an occurrence of @var{string}
4278: or a match for @var{regexp} are:
4279:
4280: @kindex SPC (query-replace)
4281: @kindex DEL (query-replace)
4282: @kindex , (query-replace)
4283: @kindex ESC (query-replace)
4284: @kindex . (query-replace)
4285: @kindex ! (query-replace)
4286: @kindex ^ (query-replace)
4287: @kindex C-r (query-replace)
4288: @kindex C-w (query-replace)
4289: @kindex C-l (query-replace)
4290:
4291: @c WideCommands
4292: @table @kbd
4293: @item @key{SPC}
4294: to replace the occurrence with @var{newstring}. This preserves case, just
4295: like @code{replace-string}, provided @code{case-replace} is non-@code{nil},
4296: as it normally is.@refill
4297:
4298: @item @key{DEL}
4299: to skip to the next occurrence without replacing this one.
4300:
4301: @item , @r{(Comma)}
4302: to replace this occurrence and display the result. You are then asked
4303: for another input character, except that since the replacement has
4304: already been made, @key{DEL} and @key{SPC} are equivalent. You could
4305: type @kbd{C-r} at this point (see below) to alter the replaced text. You
4306: could also type @kbd{C-x u} to undo the replacement; this exits the
4307: @code{query-replace}, so if you want to do further replacement you must use
4308: @kbd{C-x ESC} to restart (@pxref{Repetition}).
4309:
4310: @item @key{ESC}
4311: to exit without doing any more replacements.
4312:
4313: @item .@: @r{(Period)}
4314: to replace this occurrence and then exit.
4315:
4316: @item !
4317: to replace all remaining occurrences without asking again.
4318:
4319: @item ^
4320: to go back to the location of the previous occurrence (or what used to
4321: be an occurrence), in case you changed it by mistake. This works by
4322: popping the mark ring. Only one @kbd{^} in a row is allowed, because
4323: only one previous replacement location is kept during @code{query-replace}.
4324:
4325: @item C-r
4326: to enter a recursive editing level, in case the occurrence needs to be
4327: edited rather than just replaced with @var{newstring}. When you are
4328: done, exit the recursive editing level with @kbd{C-M-c} and the next
4329: occurrence will be displayed. @xref{Recursive Edit}.
4330:
4331: @item C-w
4332: to delete the occurrence, and then enter a recursive editing level as
4333: in @kbd{C-r}. Use the recursive edit to insert text to replace the
4334: deleted occurrence of @var{string}. When done, exit the recursive
4335: editing level with @kbd{C-M-c} and the next occurrence will be
4336: displayed.
4337:
4338: @item C-l
4339: to redisplay the screen and then give another answer.
4340:
4341: @item C-h
4342: to display a message summarizing these options, then give another
4343: answer.
4344: @end table
4345:
4346: If you type any other character, the @code{query-replace} is exited, and
4347: the character executed as a command. To restart the @code{query-replace},
4348: use @kbd{C-x @key{ESC}}, which repeats the @code{query-replace} because it
4349: used the minibuffer to read its arguments. @xref{Repetition, C-x ESC}.
4350:
4351: @node Other Repeating Search,, Replace, Search
4352: @section Other Search-and-Loop Commands
4353:
4354: Here are some other commands that find matches for a regular expression.
4355: They all operate from point to the end of the buffer.
4356:
4357: @findex list-matching-lines
4358: @findex occur
4359: @findex count-matches
4360: @findex delete-non-matching-lines
4361: @findex delete-matching-lines
4362: @c grosscommands
4363: @table @kbd
4364: @item M-x occur
4365: Print each line that follows point and contains a match for the
4366: specified regexp. A numeric argument specifies the number of context
4367: lines to print before and after each matching line; the default is
4368: none.
4369:
4370: @kindex C-c C-c (Occur mode)
4371: The buffer @samp{*Occur*} containing the output serves as a menu for
4372: finding the occurrences in their original context. Find an occurrence
4373: as listed in @samp{*Occur*}, position point there and type @kbd{C-c
4374: C-c}; this switches to the buffer that was searched and moves point to
4375: the original of the same occurrence.
4376:
4377: @item M-x list-matching-lines
4378: Synonym for @kbd{M-x occur}.
4379:
4380: @item M-x count-matches
4381: Print the number of matches following point for the specified regexp.
4382:
4383: @item M-x delete-non-matching-lines
4384: Delete each line that follows point and does not contain a match for
4385: the specified regexp.
4386:
4387: @item M-x delete-matching-lines
4388: Delete each line that follows point and contains a match for the
4389: specified regexp.
4390: @end table
4391:
4392: @node Fixit, Files, Search, Top
4393: @chapter Commands for Fixing Typos
4394: @cindex typos
4395: @cindex mistakes, correcting
4396:
4397: In this chapter we describe the commands that are especially useful for
4398: the times when you catch a mistake in your text just after you have made
4399: it, or change your mind while composing text on line.
4400:
4401: @menu
4402: * Kill Errors:: Commands to kill a batch of recently entered text.
4403: * Transpose:: Exchanging two characters, words, lines, lists...
4404: * Fixing Case:: Correcting case of last word entered.
4405: * Spelling:: Apply spelling checker to a word, or a whole file.
4406: @end menu
4407:
4408: @node Kill Errors, Transpose, Fixit, Fixit
4409: @section Killing Your Mistakes
4410:
4411: @table @kbd
4412: @item @key{DEL}
4413: Delete last character (@code{delete-backward-char}).
4414: @item M-@key{DEL}
4415: Kill last word (@code{backward-kill-word}).
4416: @item C-x @key{DEL}
4417: Kill to beginning of sentence (@code{backward-kill-sentence}).
4418: @end table
4419:
4420: @kindex DEL
4421: @findex delete-backward-char
4422: The @key{DEL} character (@code{delete-backward-char}) is the most
4423: important correction command. When used among graphic (self-inserting)
4424: characters, it can be thought of as canceling the last character typed.
4425:
4426: @kindex M-DEL
4427: @kindex C-x DEL
4428: @findex backward-kill-word
4429: @findex backward-kill-sentence
4430: When your mistake is longer than a couple of characters, it might be more
4431: convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}.
4432: @kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x
4433: @key{DEL}} kills back to the start of the last sentence. @kbd{C-x
4434: @key{DEL}} is particularly useful when you are thinking of what to write as
4435: you type it, in case you change your mind about phrasing.
4436: @kbd{M-@key{DEL}} and @kbd{C-x @key{DEL}} save the killed text for
4437: @kbd{C-y} and @kbd{M-y} to retrieve. @xref{Yanking}.@refill
4438:
4439: @kbd{M-@key{DEL}} is often useful even when you have typed only a few
4440: characters wrong, if you know you are confused in your typing and aren't
4441: sure exactly what you typed. At such a time, you cannot correct with
4442: @key{DEL} except by looking at the screen to see what you did. It requires
4443: less thought to kill the whole word and start over again.
4444:
4445: @node Transpose, Fixing Case, Kill Errors, Fixit
4446: @section Transposing Text
4447:
4448: @table @kbd
4449: @item C-t
4450: Transpose two characters (@code{transpose-chars}).
4451: @item M-t
4452: Transpose two words (@code{transpose-words}).
4453: @item C-M-t
4454: Transpose two balanced expressions (@code{transpose-sexps}).
4455: @item C-x C-t
4456: Transpose two lines (@code{transpose-lines}).
4457: @end table
4458:
4459: @cindex transposition
4460: @kindex C-t
4461: @findex transpose-chars
4462: The common error of transposing two characters can be fixed, when they
4463: are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally,
4464: @kbd{C-t} transposes the two characters on either side of point. When
4465: given at the end of a line, rather than transposing the last character of
4466: the line with the newline, which would be useless, @kbd{C-t} transposes the
4467: last two characters on the line. So, if you catch your transposition error
4468: right away, you can fix it with just a @kbd{C-t}. If you don't catch it so
4469: fast, you must move the cursor back to between the two transposed
4470: characters. If you transposed a space with the last character of the word
4471: before it, the word motion commands are a good way of getting there.
4472: Otherwise, a reverse search (@kbd{C-r}) is often the best way.
4473: @xref{Search}.
4474:
4475:
4476: @kindex C-x C-t
4477: @findex transpose-lines
4478: @kindex M-t
4479: @findex transpose-words
4480: @kindex C-M-t
4481: @findex transpose-sexps
4482: @kbd{Meta-t} (@code{transpose-words}) transposes the word before point
4483: with the word after point. It moves point forward over a word, dragging
4484: the word preceding or containing point forward as well. The punctuation
4485: characters between the words do not move. For example, @w{@samp{FOO, BAR}}
4486: transposes into @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.
4487:
4488: @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing
4489: two expressions (@pxref{Lists}), and @kbd{C-x C-t} (@code{transpose-lines})
4490: exchanges lines. They work like @kbd{M-t} except in determining the
4491: division of the text into syntactic units.
4492:
4493: A numeric argument to a transpose command serves as a repeat count: it
4494: tells the transpose command to move the character (word, sexp, line) before
4495: or containing point across several other characters (words, sexps, lines).
4496: For example, @kbd{C-u 3 C-t} moves the character before point forward
4497: across three other characters. This is equivalent to repeating @kbd{C-t}
4498: three times. @kbd{C-u - 4 M-t} moves the word before point backward across
4499: four words. @kbd{C-u - C-M-t} would cancel the effect of plain
4500: @kbd{C-M-t}.@refill
4501:
4502: A numeric argument of zero is assigned a special meaning (because
4503: otherwise a command with a repeat count of zero would do nothing): to
4504: transpose the character (word, sexp, line) ending after point with the
4505: one ending after the mark.
4506:
4507: @node Fixing Case, Spelling, Transpose, Fixit
4508: @section Case Conversion
4509:
4510: @table @kbd
4511: @item M-- M-l
4512: Convert last word to lower case. Note @kbd{Meta--} is Meta-minus.
4513: @item M-- M-u
4514: Convert last word to all upper case.
4515: @item M-- M-c
4516: Convert last word to lower case with capital initial.
4517: @end table
4518:
4519: @findex downcase-word
4520: @findex upcase-word
4521: @findex capitalize-word
4522: @kindex M-@t{-} M-l
4523: @kindex M-@t{-} M-u
4524: @kindex M-@t{-} M-c
4525: @cindex case conversion
4526: @cindex words
4527: A very common error is to type words in the wrong case. Because of this,
4528: the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a
4529: special feature when used with a negative argument: they do not move the
4530: cursor. As soon as you see you have mistyped the last word, you can simply
4531: case-convert it and go on typing. @xref{Case}.@refill
4532:
4533: @node Spelling,, Fixing Case, Fixit
4534: @section Checking and Correcting Spelling
4535: @cindex spelling
4536:
4537: @c doublewidecommands
4538: @table @kbd
4539: @item M-$
4540: Check and correct spelling of word (@code{spell-word}).
4541: @item M-x spell-buffer
4542: Check and correct spelling of each word in the buffer.
4543: @item M-x spell-region
4544: Check and correct spelling of each word in the region.
4545: @item M-x spell-string
4546: Check spelling of specified word.
4547: @end table
4548:
4549: @kindex M-$
4550: @findex spell-word
4551: To check the spelling of the word before point, and optionally correct it
4552: as well, use the command @kbd{M-$} (@code{spell-word}). This command runs
4553: an inferior process containing the @code{spell} program to see whether the
4554: word is correct English. If it is not, it asks you to edit the word (in
4555: the minibuffer) into a corrected spelling, and then does a @code{query-replace}
4556: to substitute the corrected spelling for the old one throughout the buffer.
4557:
4558: If you exit the minibuffer without altering the original spelling, it
4559: means you do not want to do anything to that word. Then the @code{query-replace}
4560: is not done.
4561:
4562: @findex spell-buffer
4563: @kbd{M-x spell-buffer} checks each word in the buffer the same way that
4564: @code{spell-word} does, doing a @code{query-replace} if appropriate for
4565: every incorrect word.@refill
4566:
4567: @findex spell-region
4568: @kbd{M-x spell-region} is similar but operates only on the region, not
4569: the entire buffer.
4570:
4571: @findex spell-string
4572: @kbd{M-x spell-string} reads a string as an argument and checks whether
4573: that is a correctly spelled English word. It prints in the echo area a
4574: message giving the answer.
4575:
4576: @node Files, Buffers, Fixit, Top
4577: @chapter File Handling
4578: @cindex files
4579:
4580: The basic unit of stored data in Unix is the @dfn{file}. To edit a file,
4581: you must tell Emacs to examine the file and prepare a buffer containing a
4582: copy of the file's text. This is called @dfn{visiting} the file. Editing
4583: commands apply directly to text in the buffer; that is, to the copy inside
4584: Emacs. Your changes appear in the file itself only when you @dfn{save} the
4585: buffer back into the file.
4586:
4587: In addition to visiting and saving files, Emacs can delete, copy, rename,
4588: and append to files, and operate on file directories.
4589:
4590: @menu
4591: * File Names:: How to type and edit file name arguments.
4592: * Visiting:: Visiting a file prepares Emacs to edit the file.
4593: * Saving:: Saving makes your changes permanent.
4594: * Reverting:: Reverting cancels all the changes not saved.
4595: * Auto Save:: Auto Save periodically protects against loss of data.
4596: * ListDir:: Listing the contents of a file directory.
4597: * Dired:: ``Editing'' a directory to delete, rename, etc.
4598: the files in it.
4599: * Misc File Ops:: Other things you can do on files.
4600: @end menu
4601:
4602: @node File Names, Visiting, Files, Files
4603: @section File Names
4604: @cindex file names
4605:
4606: Most Emacs commands that operate on a file require you to specify the
4607: file name. (Saving and reverting are exceptions; the buffer knows which
4608: file name to use for them.) File names are specified using the minibuffer
4609: (@pxref{Minibuffer}). @dfn{Completion} is available, to make it easier to
4610: specify long file names. @xref{Completion}.
4611:
4612: There is always a @dfn{default file name} which will be used if you type
4613: just @key{RET}, entering an empty argument. Normally the default file name
4614: is the name of the file visited in the current buffer; this makes it easy
4615: to operate on that file with any of the Emacs file commands.
4616:
4617: @vindex default-directory
4618: Each buffer has a default directory, normally the same as the directory
4619: of the file visited in that buffer. When Emacs reads a file name, if you
4620: do not specify a directory, the default directory is used. If you specify
4621: a directory in a relative fashion, with a name that does not start with a
4622: slash, it is interpreted with respect to the default directory. The
4623: default directory is kept in the variable @code{default-directory}, which
4624: has a separate value in every buffer.
4625:
4626: For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then
4627: the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo},
4628: which does not specify a directory, it is short for @file{/u/rms/gnu/foo}.
4629: @samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo}
4630: would stand for the filename @file{/u/rms/gnu/new/foo}.
4631:
4632: The command @kbd{M-x pwd} prints the current buffer's default directory,
4633: and the command @kbd{M-x cd} sets it (to a value read using the
4634: minibuffer). A buffer's default directory changes only when the @code{cd}
4635: command is used. A file-visiting buffer's default directory is initialized
4636: to the directory of the file that is visited there. If a buffer is made
4637: randomly with @kbd{C-x b}, its default directory is copied from that of the
4638: buffer that was current at the time.
4639:
4640: @vindex insert-default-directory
4641: The default directory actually appears in the minibuffer when the
4642: minibuffer becomes active to read a file name. This serves two purposes:
4643: it shows you what the default is, so that you can type a relative file name
4644: and know with certainty what it will mean, and it allows you to edit the
4645: default to specify a different directory. This insertion of the default
4646: directory is inhibited if the variable @code{insert-default-directory} is
4647: set to @code{nil}.
4648:
4649: Note that it is legitimate to type an absolute file name after you enter
4650: the minibuffer, ignoring the presence of the default directory name as part
4651: of the text. The final minibuffer contents may look invalid, but that is
4652: not so. @xref{Minibuffer File}.
4653:
4654: @samp{$} in a file name is used to substitute environment variables. For
4655: example, if you have used the shell command @samp{setenv FOO rms/hacks} to
4656: set up an environment variable named @samp{FOO}, then you can use
4657: @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an abbreviation for
4658: @file{/u/rms/hacks/test.c}. The environment variable name consists of all
4659: the alphanumeric characters after the @samp{$}; alternatively, it may be
4660: enclosed in braces after the @samp{$}. Note that the @samp{setenv} command
4661: affects Emacs only if done before Emacs is started.
4662:
4663: To access a file with @samp{$} in its name, type @samp{$$}. This pair
4664: is converted to a single @samp{$} at the same time as variable substitution
4665: is performed for single @samp{$}. The Lisp function that performs the
4666: substitution is called @code{substitute-in-file-name}. The substitution
4667: is performed only on filenames read as such using the minibuffer.
4668:
4669: @node Visiting, Saving, File Names, Files
4670: @section Visiting Files
4671: @cindex visiting files
4672:
4673: @c WideCommands
4674: @table @kbd
4675: @item C-x C-f
4676: Visit a file (@code{find-file}).
4677: @item C-x C-v
4678: Visit a different file instead of the one visited last
4679: (@code{find-alternate-file}).
4680: @item C-x 4 C-f
4681: Visit a file, in another window (@code{find-file-other-window}). Don't
4682: change this window.
4683: @end table
4684:
4685: @cindex files
4686: @cindex visiting
4687: @cindex saving
4688: @dfn{Visiting} a file means copying its contents into Emacs where you can
4689: edit them. Emacs makes a new buffer for each file that you visit. We say
4690: that the buffer is visiting the file that it was created to hold. Emacs
4691: constructs the buffer name from the file name by throwing away the
4692: directory, keeping just the name proper. For example, a file named
4693: @file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}. If
4694: there is already a buffer with that name, a unique name is constructed by
4695: appending @samp{<2>}, @samp{<3>}, or so on, using the lowest number that
4696: makes a name that is not already in use.
4697:
4698: Each window's mode line shows the name of the buffer that is being displayed
4699: in that window, so you can always tell what buffer you are editing.
4700:
4701: The changes you make with Emacs are made in the Emacs buffer. They do
4702: not take effect in the file that you visited, or any place permanent, until
4703: you @dfn{save} the buffer. Saving the buffer means that Emacs writes the
4704: current contents of the buffer into its visited file. @xref{Saving}.
4705:
4706: @cindex modified (buffer)
4707: If a buffer contains changes that have not been saved, the buffer is said
4708: to be @dfn{modified}. This is important because it implies that some
4709: changes will be lost if the buffer is not saved. The mode line displays
4710: two stars near the left margin if the buffer is modified.
4711:
4712: @kindex C-x C-f
4713: @findex find-file
4714: To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow
4715: the command with the name of the file you wish to visit, terminated by a
4716: @key{RET}.
4717:
4718: The file name is read using the minibuffer (@pxref{Minibuffer}), with
4719: defaulting and completion in the standard manner (@pxref{File Names}).
4720: While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}.
4721:
4722: Your confirmation that @kbd{C-x C-f} has completed successfully is the
4723: appearance of new text on the screen and a new buffer name in the mode
4724: line. If the specified file does not exist and could not be created, or
4725: cannot be read, then an error results. The error message is printed in the
4726: echo area, and includes the file name which Emacs was trying to visit.
4727:
4728: If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
4729: another copy. It selects the existing buffer containing that file.
4730: However, before doing so, it checks that the file itself has not changed
4731: since you visited or saved it last. If the file has changed, a warning
4732: message is printed. @xref{Interlocking,,Simultaneous Editing}.
4733:
4734: @cindex creating files
4735: What if you want to create a file? Just visit it. Emacs prints
4736: @samp{(New File)} in the echo area, but in other respects behaves as if you
4737: had visited an existing empty file. If you make any changes and save them,
4738: the file is created.
4739:
4740: @kindex C-x C-v
4741: @findex find-alternate-file
4742: If you visit a nonexistent file unintentionally (because you typed the
4743: wrong file name), use the @kbd{C-x C-v} (@code{find-alternate-file})
4744: command to visit the file you wanted. @kbd{C-x C-v} is similar to @kbd{C-x
4745: C-f}, but it kills the current buffer (after first offering to save it if
4746: it is modified). @kbd{C-x C-v} is allowed even if the current buffer
4747: is not visiting a file.
4748:
4749: @vindex find-file-run-dired
4750: If the file you specify is actually a directory, Dired is called on that
4751: directory (@pxref{Dired}). This can be inhibited by setting the variable
4752: @code{find-file-run-dired} to @code{nil}; then it is an error to try to
4753: visit a directory.
4754:
4755: @kindex C-x 4 f
4756: @findex find-file-other-window
4757: @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
4758: except that the buffer containing the specified file is selected in another
4759: window. The window that was selected before @kbd{C-x 4 f} continues to
4760: show the same buffer it was already showing. If this command is used when
4761: only one window is being displayed, that window is split in two, with one
4762: window showing the same before as before, and the other one showing the
4763: newly requested file. @xref{Windows}.
4764:
4765: @vindex find-file-hooks
4766: @vindex find-file-not-found-hooks
4767: There are two hook variables that allow extensions to modify the
4768: operation of visiting files. Visiting a file that does not exist runs the
4769: functions in the list @code{find-file-not-found-hooks}; the value of this
4770: variable is expected to be a list of functions, and the functions are
4771: called one by one until one of them returns non-@code{nil}. Any visiting
4772: of a file, whether extant or not, expects @code{find-file-hooks} to
4773: contain list of functions and calls them all, one by one. In both cases
4774: the functions receive no arguments. Visiting a nonexistent file
4775: runs the @code{find-file-not-found-hooks} first.
4776:
4777: @node Saving, Reverting, Visiting, Files
4778: @section Saving Files
4779:
4780: @dfn{Saving} a buffer in Emacs means writing its contents back into the file
4781: that was visited in the buffer.
4782:
4783: @table @kbd
4784: @item C-x C-s
4785: Save the current buffer in its visited file (@code{save-buffer}).
4786: @item C-x s
4787: Save any or all buffers in their visited files (@code{save-some-buffers}).
4788: @item M-~
4789: Forget that the current buffer has been changed (@code{not-modified}).
4790: @item C-x C-w
4791: Save the current buffer in a specified file, and record that file as
4792: the one visited in the buffer (@code{write-file}).
4793: @item M-x set-visited-file-name
4794: Change file the name under which the current buffer will be saved.
4795: @end table
4796:
4797: @kindex C-x C-s
4798: @findex save-buffer
4799: When you wish to save the file and make your changes permanent, type
4800: @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
4801: prints a message such as
4802:
4803: @example
4804: Wrote /u/rms/gnu/gnu.tasks
4805: @end example
4806:
4807: @noindent
4808: If the selected buffer is not modified (no changes have been made in it
4809: since the buffer was created or last saved), saving is not really done,
4810: because it would have no effect. Instead, @kbd{C-x C-s} prints a message
4811: in the echo area saying
4812:
4813: @example
4814: (No changes need to be written)
4815: @end example
4816:
4817: @kindex C-x s
4818: @findex save-some-buffers
4819: The command @kbd{C-x s} (@code{save-some-buffers}) can save any or all modified
4820: buffers. First it asks, for each modified buffer, whether to save it.
4821: These questions should be answered with @kbd{y} or @kbd{n}. @kbd{C-x C-c},
4822: the key that kills Emacs, invokes @code{save-some-buffers} and therefore
4823: asks the same questions.
4824:
4825: @kindex M-~
4826: @findex not-modified
4827: If you have changed a buffer and do not want the changes to be saved, you
4828: should take some action to prevent it. Otherwise, each time you use
4829: @code{save-some-buffers} you are liable to save it by mistake. One thing
4830: you can do is type @kbd{M-~} (@code{not-modified}), which clears out the
4831: indication that the buffer is modified. If you do this, none of the save
4832: commands will believe that the buffer needs to be saved. (@samp{~} is often
4833: used as a mathematical symbol for `not'; thus @kbd{Meta-~} is `not', metafied.)
4834: You could also use @code{set-visited-file-name} (see below) to mark the
4835: buffer as visiting a different file name, one which is not in use for
4836: anything important. Alternatively, you can undo all the changes made since
4837: the file was visited or saved, by reading the text from the file again.
4838: This is called @dfn{reverting}. @xref{Reverting}. You could also undo all
4839: the changes by repeating the undo command @kbd{C-x u} until you have undone
4840: all the changes; but this only works if you have not made more changes than
4841: the undo mechanism can remember.
4842:
4843: @findex set-visited-file-name
4844: @kbd{M-x set-visited-file-name} alters the name of the file that the
4845: current buffer is visiting. It reads the new file name using the
4846: minibuffer. It can be used on a buffer that is not visiting a file, too.
4847: The buffer's name is changed to correspond to the file it is now visiting
4848: in the usual fashion (unless the new name is in use already for some other
4849: buffer; in that case, the buffer name is not changed).
4850: @code{set-visited-file-name} does not save the buffer in the newly visited
4851: file; it just alters the records inside Emacs so that, if you save the
4852: buffer, it will be saved in that file. It also marks the buffer as
4853: ``modified'' so that @kbd{C-x C-s} @i{will} save.
4854:
4855: @kindex C-x C-w
4856: @findex write-file
4857: If you wish to mark the buffer as visiting a different file and save it
4858: right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely
4859: equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}.
4860: @kbd{C-x C-s} used on a buffer that is not visiting with a file has the
4861: same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
4862: buffer as visiting that file, and saves it there. The default file name in
4863: a buffer that is not visiting a file is made by combining the buffer name
4864: with the buffer's default directory.
4865:
4866: If Emacs is about to save a file and sees that the date of the latest
4867: version on disk does not match what Emacs last read or wrote, Emacs
4868: notifies you of this fact, because it probably indicates a problem caused
4869: by simultaneous editing and requires your immediate attention.
4870: @xref{Interlocking,, Simultaneous Editing}.
4871:
4872: @vindex require-final-newline
4873: If the variable @code{require-final-newline} is non-@code{nil}, Emacs
4874: puts a newline at the end of any file that doesn't already end in one,
4875: every time a file is saved or written.
4876:
4877: @vindex write-file-hooks
4878: You can implement other ways to write files, and other things to be done
4879: before writing them, using the hook variable @code{write-file-hooks}. The
4880: value of this variable should be a list of Lisp functions. When a file is
4881: to be written, the functions in the list are called, one by one, with no
4882: arguments. If one of them returns a non-@code{nil} value, Emacs takes this
4883: to mean that the file has been written in some suitable fashion; the rest
4884: of the functions are not called, and normal writing is not done.
4885:
4886: @menu
4887: * Backup:: How Emacs saves the old version of your file.
4888: * Interlocking:: How Emacs protects against simultaneous editing
4889: of one file by two users.
4890: @end menu
4891:
4892: @node Backup, Interlocking, Saving, Saving
4893: @subsection Backup Files
4894: @cindex backup file
4895: @vindex make-backup-files
4896:
4897: Because Unix does not provide version numbers in file names, rewriting a
4898: file in Unix automatically destroys all record of what the file used to
4899: contain. Thus, saving a file from Emacs throws away the old contents of
4900: the file---or it would, except that Emacs carefully copies the old contents
4901: to another file, called the @dfn{backup} file, before actually saving.
4902: (Provided the variable @code{make-backup-files} is non-@code{nil}.
4903: Backup files are not written if this variable is @code{nil}).
4904:
4905: At your option, Emacs can keep either a single backup file or a series of
4906: numbered backup files for each file that you edit.
4907:
4908: Emacs makes a backup for a file only the first time the file is saved
4909: from one buffer. No matter how many times you save a file, its backup file
4910: continues to contain the contents from before the file was visited.
4911: Normally this means that the backup file contains the contents from before
4912: the current editing session; however, if you kill the buffer and then visit
4913: the file again, a new backup file will be made by the next save.
4914:
4915: @menu
4916: * Names: Backup Names. How backup files are named;
4917: Choosing single or numbered backup files.
4918: * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
4919: * Copying: Backup Copying. Backups can be made by copying or renaming.
4920: @end menu
4921:
4922: @node Backup Names, Backup Deletion, Backup, Backup
4923: @subsubsection Single or Numbered Backups
4924:
4925: If you choose to have a single backup file (this is the default),
4926: the backup file's name is constructed by appending @samp{~} to the
4927: file name being edited; thus, the backup file for @file{eval.c} would
4928: be @file{eval.c~}.
4929:
4930: If you choose to have a series of numbered backup files, backup file
4931: names are made by appending @samp{.~}, the number, and another @samp{~} to
4932: the original file name. Thus, the backup files of @file{eval.c} would be
4933: called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names
4934: like @file{eval.c.~259~} and beyond.
4935:
4936: If protection stops you from writing backup files under the usual names,
4937: the backup file is written as @file{%backup%~} in your home directory.
4938: Only one such file can exist, so only the most recently made such backup is
4939: available.
4940:
4941: @vindex version-control
4942: The choice of single backup or numbered backups is controlled by the
4943: variable @code{version-control}. Its possible values are
4944:
4945: @table @code
4946: @item t
4947: Make numbered backups.
4948: @item nil
4949: Make numbered backups for files that have numbered backups already.
4950: Otherwise, make single backups.
4951: @item never
4952: Do not in any case make numbered backups; always make single backups.
4953: @end table
4954:
4955: @noindent
4956: @code{version-control} may be set locally in an individual buffer to
4957: control the making of backups for that buffer's file. For example,
4958: Rmail mode locally sets @code{version-control} to @code{never} to make sure
4959: that there is only one backup for an Rmail file. @xref{Locals}.
4960:
4961: @node Backup Deletion, Backup Copying, Backup Names, Backup
4962: @subsubsection Automatic Deletion of Backups
4963:
4964: @vindex kept-old-versions
4965: @vindex kept-new-versions
4966: To prevent unlimited consumption of disk space, Emacs can delete numbered
4967: backup versions automatically. Generally Emacs keeps the first few backups
4968: and the latest few backups, deleting any in between. This happens every
4969: time a new backup is made. The two variables that control the deletion are
4970: @code{kept-old-versions} and @code{kept-new-versions}. Their values are, respectively
4971: the number of oldest (lowest-numbered) backups to keep and the number of
4972: newest (highest-numbered) ones to keep, each time a new backup is made.
4973: Recall that these values are used just after a new backup version is made;
4974: that newly made backup is included in the count in @code{kept-new-versions}.
4975: By default, both variables are 2.
4976:
4977: @vindex trim-versions-without-asking
4978: If @code{trim-versions-without-asking} is non-@code{nil}, the excess
4979: middle versions are deleted without a murmur. If it is @code{nil}, the
4980: default, then you are asked whether the excess middle versions should
4981: really be deleted.
4982:
4983: Dired's @kbd{.} (Period) command can also be used to delete old versions.
4984: @xref{Dired}.
4985:
4986: @node Backup Copying,, Backup Deletion, Backup
4987: @subsubsection Copying vs.@: Renaming
4988:
4989: Backup files can be made by copying the old file or by renaming it. This
4990: makes a difference when the old file has multiple names. If the old file
4991: is renamed into the backup file, then the alternate names become names for
4992: the backup file. If the old file is copied instead, then the alternate
4993: names remain names for the file that you are editing, and the contents
4994: accessed by those names will be the new contents.
4995:
4996: The method of making a backup file may also affect the file's owner
4997: and group. If copying is used, these do not change. If renaming is used,
4998: you become the file's owner, and the file's group becomes the default
4999: (different operating systems have different defaults for the group).
5000:
5001: Having the owner change is usually a good idea, because then the owner
5002: always shows who last edited the file. Also, the owners of the backups
5003: show who produced those versions. Occasionally there is a file whose
5004: owner should not change; it is a good idea for such files to contain
5005: local variable lists to set @code{backup-by-copying-when-mismatch} for
5006: them alone (@pxref{File Variables}).
5007:
5008: @vindex backup-by-copying
5009: @vindex backup-by-copying-when-linked
5010: @vindex backup-by-copying-when-mismatch
5011: The choice of renaming or copying is controlled by three variables.
5012: Normally, renaming is done. If the variable @code{backup-by-copying} is
5013: non-@code{nil}, copying is used. Otherwise, if the variable
5014: @code{backup-by-copying-when-linked} is non-@code{nil}, then copying is
5015: done for files that have multiple names, but renaming may still done when
5016: the file being edited has only one name. If the variable
5017: @code{backup-by-copying-when-mismatch} is non-@code{nil}, then copying is
5018: done if renaming would cause the file's owner or group to change. @refill
5019:
5020: @node Interlocking,,Backup,Saving
5021: @subsection Protection against Simultaneous Editing
5022:
5023: @cindex file dates
5024: @cindex simultaneous editing
5025: Simultaneous editing occurs when two users visit the same file, both make
5026: changes, and then both save them. If nobody were informed that this was
5027: happening, whichever user saved first would later find that his changes
5028: were lost. On some systems, Emacs notices immediately when the second user
5029: starts to change the file, and issues an immediate warning. When this is
5030: not possible, or if the second user has gone on to change the file despite
5031: the warning, Emacs checks later when the file is saved, and issues a second
5032: warning when a user is about to overwrite a file containing another user's
5033: changes. If the editing user takes the proper corrective action at this
5034: point, he can prevent actual loss of work.
5035:
5036: @findex ask-user-about-lock
5037: When you make the first modification in an Emacs buffer that is visiting
5038: a file, Emacs records that you have locked the file. (It does this by
5039: writing another file in a directory reserved for this purpose.) The lock
5040: is removed when you save the changes. The idea is that the file is locked
5041: whenever the buffer is modified. If you begin to modify the buffer while
5042: the visited file is locked by someone else, this constitutes a collision,
5043: and Emacs asks you what to do. It does this by calling the Lisp function
5044: @code{ask-user-about-lock}, which you can redefine for the sake of
5045: customization. The standard definition of this function asks you a
5046: question and accepts three possible answers:
5047:
5048: @table @kbd
5049: @item s
5050: Steal the lock. Whoever was already changing the file loses the lock,
5051: and you gain the lock.
5052: @item p
5053: Proceed. Go ahead and edit the file despite its being locked by someone else.
5054: @item q
5055: Quit. This causes an error (@code{file-locked}) and the modification you
5056: were trying to make in the buffer does not actually take place.
5057: @end table
5058:
5059: Note that locking works on the basis of a file name; if a file has
5060: multiple names, Emacs does not realize that the two names are the same file
5061: and cannot prevent two user from editing it simultaneously under different
5062: names. However, basing locking on names means that Emacs can interlock the
5063: editing of new files that will not really exist until they are saved.
5064:
5065: Some systems are not configured to allow Emacs to make locks. On
5066: these systems, Emacs cannot detect trouble in advance, but it still can
5067: detect it in time to prevent you from overwriting someone else's changes.
5068:
5069: Every time Emacs saves a buffer, it first checks the last-modification
5070: date of the existing file on disk to see that it has not changed since the
5071: file was last visited or saved. If the date does not match, it implies
5072: that changes were made in the file in some other way, and these changes are
5073: about to be lost if Emacs actually does save. To prevent this, Emacs
5074: prints a warning message and asks for confirmation before saving.
5075: Occasionally you will know why the file was changed and know that it does
5076: not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should
5077: cancel the save with @kbd{C-g} and investigate the situation.
5078:
5079: The first thing you should do when notified that simultaneous editing has
5080: already taken place is to list the directory with @kbd{C-u C-x C-d}
5081: (@pxref{ListDir,,Directory Listing}). This will show the file's current
5082: author. You should attempt to contact him to warn him not to continue
5083: editing. Often the next step is to save the contents of your Emacs buffer
5084: under a different name, and use @code{diff} to compare the two
5085: files.@refill
5086:
5087: Simultaneous editing checks are also made when you visit with @kbd{C-x
5088: C-f} a file that is already visited and when you start to modify a file.
5089: This is not strictly necessary, but it can cause you to find out about the
5090: problem earlier, when perhaps correction takes less work.
5091:
5092: @node Reverting, Auto Save, Saving, Files
5093: @section Reverting a Buffer
5094: @findex revert-buffer
5095: @cindex drastic changes
5096:
5097: If you have made extensive changes to a file and then change your mind
5098: about them, you can get rid of them by reading in the previous version of
5099: the file. To do this, use @kbd{M-x revert-buffer}, which operates on the
5100: current buffer. Since this is a very dangerous thing to do, you must
5101: confirm it with @kbd{yes}.
5102:
5103: If the current buffer has been auto-saved more recently than it has been
5104: saved for real, @code{revert-buffer} offers to read the auto save file
5105: instead of the visited file (@pxref{Auto Save}). This question comes
5106: before the usual request for confirmation, and demands @kbd{y} or @kbd{n}
5107: as an answer. If you have started to type @kbd{yes} for confirmation
5108: without realizing that the other question was going to be asked, the
5109: @kbd{y} will answer that question, but the @kbd{es} will not be valid
5110: confirmation. So you will have a chance to cancel the operation with
5111: @kbd{C-g} and try it again with the answers that you really intend.
5112:
5113: @code{revert-buffer} keeps point at the same distance (measured in
5114: characters) from the beginning of the file. If the file was edited only
5115: slightly, you will be at approximately the same piece of text after
5116: reverting as before. If you have made drastic changes, the same value of
5117: point in the old file may address a totally different piece of text.
5118:
5119: A buffer reverted from its visited file is marked ``not modified'' until
5120: another change is made.
5121:
5122: Some kinds of buffers whose contents reflect data bases other than files,
5123: such as Dired buffers, can also be reverted. For them, reverting means
5124: recalculating their contents from the appropriate data base. Buffers
5125: created randomly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
5126: reports an error when asked to do so.
5127:
5128: @node Auto Save, ListDir, Reverting, Files
5129: @section Auto-Saving: Protection Against Disasters
5130: @cindex Auto-Save mode
5131: @cindex crashes
5132:
5133: Emacs saves all the visited files from time to time (based on counting
5134: your keystrokes) without being asked. This is called @dfn{auto-saving}.
5135: It prevents you from losing more than a limited amount of work if the
5136: system crashes.
5137:
5138: When Emacs determines that it is time for auto-saving, each buffer is
5139: considered, and is auto-saved if auto-saving is turned on for it and it has
5140: been changed since the last time it was auto-saved. If any auto-saving is
5141: done, the message @samp{Auto-saving...} is displayed in the echo area until
5142: auto-saving is finished. Errors occurring during auto-saving are caught
5143: so that they do not interfere with the execution of commands you have been
5144: typing.
5145:
5146: @menu
5147: * Files: Auto Save Files.
5148: * Control: Auto Save Control.
5149: * Recover:: Recovering text from auto-save files.
5150: @end menu
5151:
5152: @node Auto Save Files, Auto Save Control, Auto Save, Auto Save
5153: @subsection Auto-Save Files
5154:
5155: Auto-saving does not normally save in the files that you visited, because
5156: it can be very undesirable to save a program that is in an inconsistent
5157: state when you have made half of a planned change. Instead, auto-saving
5158: is done in a different file called the @dfn{auto-save file}, and the
5159: visited file is changed only when you request saving explicitly (such as
5160: with @kbd{C-x C-s}).
5161:
5162: Normally, the auto-save file name is made by appending @samp{#} to the
5163: front and rear of the visited file name. Thus, a buffer visiting file
5164: @file{foo.c} would be auto-saved in a file @file{#foo.c#}. Most buffers
5165: that are not visiting files are auto-saved only if you request it
5166: explicitly; when they are auto-saved, the auto-save file name is made by
5167: appending @samp{#%} to the front and @samp{#} to the rear of buffer name.
5168: For example, the @samp{*mail*} buffer in which you compose messages to be
5169: sent is auto-saved in a file named @file{#%*mail*#}. Auto-save file names
5170: are made this way unless you reprogram parts of Emacs to do something
5171: different (the functions @code{make-auto-save-file-name} and
5172: @code{auto-save-file-name-p}). The file name to be used for auto-saving
5173: in a buffer is calculated when auto-saving is turned on in that buffer.
5174:
5175: @vindex auto-save-visited-file-name
5176: If you want auto-saving to be done in the visited file, set the variable
5177: @code{auto-save-visited-file-name} to be non-@code{nil}. In this mode,
5178: there is really no difference between auto-saving and explicit saving.
5179:
5180: @vindex delete-auto-save-files
5181: A buffer's auto-save file is deleted when you save the buffer in its
5182: visited file. To inhibit this, set the variable @code{delete-auto-save-files}
5183: to @code{nil}. Changing the visited file name with @kbd{C-x C-w} or
5184: @code{set-visited-file-name} renames any auto-save file to go with
5185: the new visited name.
5186:
5187: @node Auto Save Control, Recover, Auto Save Files, Auto Save
5188: @subsection Controlling Auto-Saving
5189:
5190: @vindex auto-save-default
5191: @findex auto-save-mode
5192: Each time you visit a file, auto-saving is turned on for that file's
5193: buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
5194: in batch mode; @pxref{Entering Emacs}). The default for this variable is
5195: @code{t}, so auto-saving is the usual practice for file-visiting buffers.
5196: Auto-saving can be turned on or off for any existing buffer with the
5197: command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x
5198: auto-save-mode} turns auto-saving on with a positive argument, off with a
5199: zero or negative argument; with no argument, it toggles.
5200:
5201: @vindex auto-save-interval
5202: @findex do-auto-save
5203: Emacs does auto-saving periodically based on counting how many characters
5204: you have typed since the last time auto-saving was done. The variable
5205: @code{auto-save-interval} specifies how many characters there are between
5206: auto-saves. By default, it is 300. Emacs also auto-saves whenever you
5207: call the function @code{do-auto-save}.
5208:
5209: Emacs also does auto-saving whenever it gets a fatal error. This
5210: includes killing the Emacs job with a shell command such as @code{kill
5211: %emacs}, or disconnecting a phone line or network connection.
5212:
5213: @node Recover,, Auto Save Control, Auto Save
5214: @subsection Recovering Data from Auto-Saves
5215:
5216: @findex recover-file
5217: The way to use the contents of an auto-save file to recover from a loss
5218: of data is with the command @kbd{M-x recover-file @key{RET} @var{file}
5219: @key{RET}}. This visits @var{file} and then (after your confirmation)
5220: restores the contents from from its auto-save file @file{#@var{file}#}. You
5221: can then save with @kbd{C-x C-s} to put the recovered text into @var{file}
5222: itself. For example, to recover file @file{foo.c} from its auto-save file
5223: @file{#foo.c#}, do:@refill
5224:
5225: @example
5226: M-x recover-file @key{RET} foo.c @key{RET}
5227: C-x C-s
5228: @end example
5229:
5230: Before asking for confirmation, @kbd{M-x recover-file} displays a
5231: directory listing describing the specified file and the auto-save file,
5232: so you can compare their sizes and dates. If the auto-save file
5233: is older, @kbd{M-x recover-file} does not offer to read it.
5234:
5235: Auto-saving is disabled by @kbd{M-x recover-file} because using
5236: this command implies that the auto-save file contains valuable data
5237: from a past session. If you save the data in the visited file and
5238: then go on to make new changes, you should turn auto-saving back on
5239: with @kbd{M-x auto-save-mode}.
5240:
5241: @node ListDir, Dired, Auto Save, Files
5242: @section Listing a File Directory
5243:
5244: @cindex file directory
5245: @cindex directory listing
5246: Files are classified by Unix into @dfn{directories}. A @dfn{directory
5247: listing} is a list of all the files in a directory. Emacs provides
5248: directory listings in brief format (file names only) and verbose format
5249: (sizes, dates, and authors included).
5250:
5251: @table @kbd
5252: @item C-x C-d @var{dir-or-pattern}
5253: Print a brief directory listing (@code{list-directory}).
5254: @item C-u C-x C-d @var{dir-or-pattern}
5255: Print a verbose directory listing.
5256: @end table
5257:
5258: @findex list-directory
5259: @kindex C-x C-d
5260: The command to print a directory listing is @kbd{C-x C-d} (@code{list-directory}).
5261: It reads using the minibuffer a file name which is either a directory to be
5262: listed or a wildcard-containing pattern for the files to be listed. For
5263: example,
5264:
5265: @example
5266: C-x C-d /u2/emacs/etc @key{RET}
5267: @end example
5268:
5269: @noindent
5270: lists all the files in directory @file{/u2/emacs/etc}. An example of
5271: specifying a file name pattern is
5272:
5273: @example
5274: C-x C-d /u2/emacs/src/*.c @key{RET}
5275: @end example
5276:
5277: Normally, @kbd{C-x C-d} prints a brief directory listing containing just
5278: file names. A numeric argument (regardless of value) tells it to print a
5279: verbose listing (like @code{ls -l}).
5280:
5281: @vindex list-directory-brief-switches
5282: @vindex list-directory-verbose-switches
5283: The text of a directory listing is obtained by running @code{ls} in an
5284: inferior process. Two Emacs variables control the switches passed to
5285: @code{ls}: @code{list-directory-brief-switches} is a string giving the
5286: switches to use in brief listings (@code{"-CF"} by default), and
5287: @code{list-directory-verbose-switches} is a string giving the switches to
5288: use in a verbose listing (@code{"-l"} by default).
5289:
5290: @node Dired, Misc File Ops, ListDir, Files
5291: @section Dired, the Directory Editor
5292: @cindex Dired
5293: @cindex deletion (of files)
5294:
5295: Dired makes it easy to delete or visit many of the files in a single
5296: directory at once. It makes an Emacs buffer containing a listing of the
5297: directory. You can use the normal Emacs commands to move around in this
5298: buffer, and special Dired commands to operate on the files.
5299:
5300: @menu
5301: * Enter: Dired Enter. How to invoke Dired.
5302: * Edit: Dired Edit. Editing the Dired buffer.
5303: * Deletion: Dired Deletion. Deleting files with Dired.
5304: * Immed: Dired Immed. Other file operations through Dired.
5305: @end menu
5306:
5307: @node Dired Enter, Dired Edit, Dired, Dired
5308: @subsection Entering Dired
5309:
5310: @findex dired
5311: @kindex C-x d
5312: @vindex dired-listing-switches
5313: To invoke dired, do @kbd{C-x d} or @kbd{M-x dired}. The command reads a
5314: directory name or wildcard file name pattern as a minibuffer argument just
5315: like the @code{list-directory} command, @kbd{C-x C-d}. Where @code{dired}
5316: differs from @code{list-directory} is in naming the buffer after the
5317: directory name or the wildcard pattern used for the listing, and putting
5318: the buffer into Dired mode so that the special commands of Dired are
5319: available in it. The variable @code{dired-listing-switches} is a string
5320: used as an argument to @code{ls} in making the directory; this string
5321: @i{must} contain @samp{-l}.
5322:
5323: @findex dired-other-window
5324: @kindex C-x 4 d
5325: To display the Dired buffer in another window rather than in the selected
5326: window, use @kbd{C-x 4 d} (@code{dired-other-window)} instead of @kbd{C-x d}.
5327:
5328: @node Dired Edit, Dired Deletion, Dired Enter, Dired
5329: @subsection Editing in Dired
5330:
5331: Once the Dired buffer exists, you can switch freely between it and other
5332: Emacs buffers. Whenever the Dired buffer is selected, certain special
5333: commands are provided that operate on files that are listed. The Dired
5334: buffer is ``read-only'', and inserting text in it is not useful, so
5335: ordinary printing characters such as @kbd{d} and @kbd{x} are used for Dired
5336: commands. Most Dired commands operate on the file described by the line
5337: that point is on. Some commands perform operations immediately; others
5338: ``flag'' the file to be operated on later.
5339:
5340: Most Dired commands that operate on the current line's file also treat a
5341: numeric argument as a repeat count, meaning to act on the files of the
5342: next few lines. A negative argument means to operate on the files of the
5343: preceding lines, and leave point on the first of those lines.
5344:
5345: All the usual Emacs cursor motion commands are available in Dired
5346: buffers. Some special purpose commands are also provided. The keys
5347: @kbd{C-n} and @kbd{C-p} are redefined so that they try to position
5348: the cursor at the beginning of the filename on the line, rather than
5349: at the beginning of the line.
5350:
5351: For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent to
5352: @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. Moving by lines is done so
5353: often in Dired that it deserves to be easy to type. @key{DEL} (move up and
5354: unflag) is often useful simply for moving up.@refill
5355:
5356: The @kbd{g} command in Dired runs @code{revert-buffer} to reinitialize
5357: the buffer from the actual disk directory and show any changes made in the
5358: directory by programs other than Dired. All deletion flags in the Dired
5359: buffer are lost when this is done.
5360:
5361: @node Dired Deletion, Dired Immed, Dired Edit, Dired
5362: @subsection Deleting Files with Dired
5363:
5364: The primary use of Dired is to flag files for deletion and then delete
5365: them.
5366:
5367: @table @kbd
5368: @item d
5369: Flag this file for deletion.
5370: @item u
5371: Remove deletion-flag on this line.
5372: @item @key{DEL}
5373: Remove deletion-flag on previous line, moving point to that line.
5374: @item x
5375: Delete the files that are flagged for deletion.
5376: @item #
5377: Flag all auto-save files (files whose names start and end with @samp{#})
5378: for deletion (@pxref{Auto Save}).
5379: @item ~
5380: Flag all backup files (files whose names end with @samp{~}) for deletion
5381: (@pxref{Backup}).
5382: @item .@: @r{(Period)}
5383: Flag excess numeric backup files for deletion. The oldest and newest
5384: few backup files of any one file are exempt; the middle ones are flagged.
5385: @end table
5386:
5387: You can flag a file for deletion by moving to the line describing the
5388: file and typing @kbd{d} or @kbd{C-d}. The deletion flag is visible as a
5389: @samp{D} at the beginning of the line. Point is moved to the beginning of
5390: the next line, so that repeated @kbd{d} commands flag successive files.
5391:
5392: The files are flagged for deletion rather than deleted immediately to
5393: avoid the danger of deleting a file accidentally. Until you direct Dired
5394: to delete the flagged files, you can remove deletion flags using the
5395: commands @kbd{u} and @key{DEL}. @kbd{u} works just like @kbd{d}, but
5396: removes flags rather than making flags. @key{DEL} moves upward, removing
5397: flags; it is like @kbd{u} with numeric argument automatically negated.
5398:
5399: To delete the flagged files, type @kbd{x}. This command first displays a
5400: list of all the file names flagged for deletion, and requests confirmation
5401: with @kbd{yes}. Once you confirm, all the flagged files are deleted, and their
5402: lines are deleted from the text of the Dired buffer. The shortened Dired
5403: buffer remains selected. If you answer @kbd{no} or quit with @kbd{C-g}, you
5404: return immediately to Dired, with the deletion flags still present and no
5405: files actually deleted.
5406:
5407: The @kbd{#}, @kbd{~} and @kbd{.} commands flag many files for
5408: deletion, based on their names. These commands are useful precisely
5409: because they do not actually delete any files; you can remove the
5410: deletion flags from any flagged files that you really wish to keep.@refill
5411:
5412: @kbd{#} flags for deletion all files that appear to have been made by
5413: auto-saving (that is, files whose names begin and end with @samp{#}).
5414: @kbd{~} flags for deletion all files that appear to have been made as
5415: backups for files that were edited (that is, files whose names end with
5416: @samp{~}).
5417:
5418: @vindex dired-kept-versions
5419: @kbd{.} (Period) flags just some of the backup files for deletion: only
5420: numeric backups that are not among the oldest few nor the newest few
5421: backups of any one file. Normally @code{dired-kept-versions} (not
5422: @code{kept-new-versions}; that applies only when saving) specifies the
5423: number of newest versions of each file to keep, and
5424: @code{kept-old-versions} specifies the number of oldest versions to keep.
5425: Period with a positive numeric argument, as in @kbd{C-u 3 .}, specifies the
5426: number of newest versions to keep, overriding @code{dired-kept-versions}.
5427: A negative numeric argument overrides @code{kept-old-versions}, using minus
5428: the value of the argument to specify the number of oldest versions of each
5429: file to keep.@refill
5430:
5431: @node Dired Immed,, Dired Deletion, Dired
5432: @subsection Immediate File Operations in Dired
5433:
5434: Some file operations in Dired take place immediately when they are
5435: requested.
5436:
5437: @table @kbd
5438: @item c
5439: Copies the file described on the current line. You must supply a file name
5440: to copy to, using the minibuffer.
5441: @item f
5442: Visits the file described on the current line. It is just like typing
5443: @kbd{C-x C-f} and supplying that file name. If the file on this line is a
5444: subdirectory, @kbd{f} actually causes Dired to be invoked on that
5445: subdirectory. @xref{Visiting}.
5446: @item o
5447: Like @kbd{f}, but uses another window to display the file's buffer. The
5448: Dired buffer remains visible in the first window. This is like using
5449: @kbd{C-x 4 C-f} to visit the file. @xref{Windows}.
5450: @item r
5451: Renames the file described on the current line. You must supply a file
5452: name to rename to, using the minibuffer.
5453: @item v
5454: Views the file described on this line using @kbd{M-x view-file}. Viewing a
5455: file is like visiting it, but is slanted toward moving around in the file
5456: conveniently and does not allow changing the file. @xref{Misc File
5457: Ops,View File}. Viewing a file that is a directory runs Dired on that
5458: directory.@refill
5459: @end table
5460:
5461: @node Misc File Ops,, Dired, Files
5462: @section Miscellaneous File Operations
5463:
5464: Emacs has commands for performing many other operations on files.
5465: All operate on one file; they do not accept wild card file names.
5466:
5467: @findex view-file
5468: @cindex viewing
5469: @kbd{M-x view-file} allows you to scan or read a file by sequential
5470: screenfuls. It reads a file name argument using the minibuffer. After
5471: reading the file into an Emacs buffer, @code{view-file} reads and displays
5472: one windowful. You can then type @key{SPC} to scroll forward one windowful,
5473: or @key{DEL} to scroll backward. Various other commands are provided for
5474: moving around in the file, but none for changing it; type @kbd{C-h} while
5475: viewing for a list of them. They are mostly the same as normal Emacs
5476: cursor motion commands. To exit from viewing, type @kbd{C-c}.
5477:
5478: @findex insert-file
5479: @kbd{M-x insert-file} inserts a copy of the contents of the specified
5480: file into the current buffer at point, leaving point unchanged before the
5481: contents and the mark after them. @xref{Mark}.
5482:
5483: @findex write-region
5484: @findex append-to-file
5485: @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it copies
5486: the contents of the region into the specified file. @kbd{M-x append-to-file}
5487: adds the text of the region to the end of the specified file.
5488:
5489: @findex delete-file
5490: @cindex deletion (of files)
5491: @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
5492: command in the shell. If you are deleting many files in one directory, it
5493: may be more convenient to use Dired (@pxref{Dired}).
5494:
5495: @findex rename-file
5496: @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
5497: the minibuffer, then renames file @var{old} as @var{new}. If a file named
5498: @var{new} already exists, you must confirm with @kbd{yes} or renaming is not
5499: done; this is because renaming causes the old meaning of the name @var{new}
5500: to be lost. If @var{old} and @var{new} are on different file systems, the
5501: file @var{old} is copied and deleted.
5502:
5503: @findex add-name-to-file
5504: The similar command @kbd{M-x add-name-to-file} is used to add an
5505: additional name to an existing file without removing its old name.
5506: The new name must belong on the same file system that the file is on.
5507:
5508: @findex copy-file
5509: @cindex copying files
5510: @kbd{M-x copy-file} reads the file @var{old} and writes a new file named
5511: @var{new} with the same contents. Confirmation is required if a file named
5512: @var{new} already exists, because copying has the consequence of overwriting
5513: the old contents of the file @var{new}.
5514:
5515: @findex make-symbolic-link
5516: @kbd{M-x make-symbolic-link} reads two file names @var{old} and @var{linkname},
5517: and then creates a symbolic link named @var{linkname} and pointing at @var{old}.
5518: The effect is that future attempts to open file @var{linkname} will refer
5519: to whatever file is named @var{old} at the time the opening is done, or
5520: will get an error if the name @var{old} is not in use at that time.
5521: Confirmation is required when creating the link if @var{linkname} is in
5522: use. Note that not all systems support symbolic links.
5523:
5524: @node Buffers, Windows, Files, Top
5525: @chapter Using Multiple Buffers
5526:
5527: @cindex buffers
5528: The text you are editing in Emacs resides in an object called a
5529: @dfn{buffer}. Each time you visit a file, a buffer is created to hold the
5530: file's text. Each time you invoke Dired, a buffer is created to hold the
5531: directory listing. If you send a message with @kbd{C-x m}, a buffer named
5532: @samp{*mail*} is used to hold the text of the message. When you ask for a
5533: command's documentation, that appears in a buffer called @samp{*Help*}.
5534:
5535: @cindex selected buffer
5536: @cindex current buffer
5537: At any time, one and only one buffer is @dfn{selected}. It is also
5538: called the @dfn{current buffer}. Often we say that a command operates on
5539: ``the buffer'' as if there were only one; but really this means that the
5540: command operates on the selected buffer (most commands do).
5541:
5542: When Emacs makes multiple windows, each window has a chosen buffer which
5543: is displayed there, but at any time only one of the windows is selected and
5544: its chosen buffer is the selected buffer. Each window's mode line displays
5545: the name of the buffer that the window is displaying (@pxref{Windows}).
5546:
5547: Each buffer has a name, which can be of any length, and you can select
5548: any buffer by giving its name. Most buffers are made by visiting files,
5549: and their names are derived from the files' names. But you can also create
5550: an empty buffer with any name you want. A newly started Emacs has a buffer
5551: named @samp{*scratch*} which can be used for evaluating Lisp expressions in
5552: Emacs. The distinction between upper and lower case matters in buffer
5553: names.
5554:
5555: Each buffer records individually what file it is visiting, whether it is
5556: modified, and what major mode and minor modes are in effect in it
5557: (@pxref{Major Modes}). Any Emacs variable can be made @dfn{local to} a
5558: particular buffer, meaning its value in that buffer can be different from
5559: the value in other buffers. @xref{Locals}.
5560:
5561: @menu
5562: * Select Buffer:: Creating a new buffer or reselecting an old one.
5563: * List Buffers:: Getting a list of buffers that exist.
5564: * Misc Buffer:: Renaming; changing read-onliness; copying text.
5565: * Kill Buffer:: Killing buffers you no longer need.
5566: * Several Buffers:: How to go through the list of all buffers
5567: and operate variously on several of them.
5568: @end menu
5569:
5570: @node Select Buffer, List Buffers, Buffers, Buffers
5571: @section Creating and Selecting Buffers
5572: @cindex change buffers
5573: @cindex switch buffers
5574:
5575: @table @kbd
5576: @item C-x b @var{buffer} @key{RET}
5577: Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
5578: @item C-x 4 b @var{buffer} @key{RET}
5579: Similar but select a buffer named @var{buffer} in another window
5580: (@code{switch-to-buffer-other-window}).
5581: @end table
5582:
5583: @kindex C-x 4 b
5584: @findex switch-to-buffer-other-window
5585: @kindex C-x b
5586: @findex switch-to-buffer
5587: To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
5588: @key{RET}}. This is the command @code{switch-to-buffer} with argument
5589: @var{bufname}. You can use completion on an abbreviation for the buffer
5590: name you want (@pxref{Completion}). An empty argument to @kbd{C-x b}
5591: specifies the most recently selected buffer that is not displayed in any
5592: window.@refill
5593:
5594: Most buffers are created by visiting files, or by Emacs commands that
5595: want to display some text, but you can also create a buffer explicitly by
5596: typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty buffer which
5597: is not visiting any file, and selects it for editing. Such buffers are
5598: used for making notes to yourself. If you try to save one, you are asked
5599: for the file name to use. The new buffer's major mode is determined by the
5600: value of @code{default-major-mode} (@pxref{Major Modes}).
5601:
5602: Note that @kbd{C-x C-f}, and any other command for visiting a file, can
5603: also be used to switch buffers. @xref{Visiting}.
5604:
5605: @node List Buffers, Misc Buffer, Select Buffer, Buffers
5606: @section Listing Existing Buffers
5607:
5608: @table @kbd
5609: @item C-x C-b
5610: List the existing buffers (@code{list-buffers}).
5611: @end table
5612:
5613: @kindex C-x C-b
5614: @findex list-buffers
5615: To print a list of all the buffers that exist, type @kbd{C-x C-b}.
5616: Each line in the list shows one buffer's name, major mode and visited file.
5617: @samp{*} at the beginning of a line indicates the buffer is ``modified''.
5618: If several buffers are modified, it may be time to save some with @kbd{C-x
5619: s} (@pxref{Saving}). @samp{%} indicates a read-only buffer. @samp{.}
5620: marks the selected buffer. Here is an example of a buffer list:@refill
5621:
5622: @smallexample
5623: MR Buffer Size Mode File
5624: -- ------ ---- ---- ----
5625: .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
5626: *Help* 1287 Fundamental
5627: files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
5628: % RMAIL 64042 RMAIL /u/rms/RMAIL
5629: *% man 747 Dired
5630: net.emacs 343885 Fundamental /u/rms/net.emacs
5631: fileio.c 27691 C /u2/emacs/src/fileio.c
5632: NEWS 67340 Text /u2/emacs/etc/NEWS
5633: *scratch* 0 Lisp Interaction
5634: @end smallexample
5635:
5636: @noindent
5637: Note that the buffer @samp{*Help*} was made by a help request; it is not
5638: visiting any file. The buffer @code{man} was made by Dired on the
5639: directory @file{/u2/emacs/man/}.
5640:
5641: @node Misc Buffer, Kill Buffer, List Buffers, Buffers
5642: @section Miscellaneous Buffer Operations
5643:
5644: @table @kbd
5645: @item C-x C-q
5646: Toggle read-only status of buffer (@code{toggle-read-only}).
5647: @item M-x rename-buffer
5648: Change the name of the current buffer.
5649: @item M-x view-buffer
5650: Scroll through a buffer.
5651: @end table
5652:
5653: @cindex read-only buffer
5654: @kindex C-x C-q
5655: @findex toggle-read-only
5656: @vindex buffer-read-only
5657: A buffer can be @dfn{read-only}, which means that commands to change its
5658: text are not allowed. Normally, read-only buffers are made by subsystems
5659: such as Dired and Rmail that have special commands to operate on the text;
5660: a read-only buffer is also made if you visit a file that is protected so
5661: you cannot write it. If you wish to make changes in a read-only buffer,
5662: use the command @kbd{C-x C-q} (@code{toggle-read-only}). It makes a
5663: read-only buffer writable, and makes a writable buffer read-only. This
5664: works by setting the variable @code{buffer-read-only}, which has a local
5665: value in each buffer and makes the buffer read-only if its value is
5666: non-@code{nil}.
5667:
5668: @findex rename-buffer
5669: @kbd{M-x rename-buffer} changes the name of the current buffer. Specify
5670: the new name as a minibuffer argument. There is no default. If you
5671: specify a name that is in use for some other buffer, an error happens and
5672: no renaming is done.
5673:
5674: @findex view-buffer
5675: @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc File Ops})
5676: except that it examines an already existing Emacs buffer. View mode
5677: provides commands for scrolling through the buffer conveniently but not
5678: for changing it. When you exit View mode, the value of point that resulted
5679: from your perusal remains in effect.
5680:
5681: The commands @kbd{C-x a} (@code{append-to-buffer}) and @kbd{M-x
5682: insert-buffer} can be used to copy text from one buffer to another.
5683: @xref{Accumulating Text}.@refill
5684:
5685: @node Kill Buffer, Several Buffers, Misc Buffer, Buffers
5686: @section Killing Buffers
5687:
5688: After you use Emacs for a while, you may accumulate a large number of
5689: buffers. You may then find it convenient to eliminate the ones you no
5690: longer need. There are several commands provided for doing this.
5691:
5692: @c WideCommands
5693: @table @kbd
5694: @item C-x k
5695: Kill a buffer, specified by name (@code{kill-buffer}).
5696: @item M-x kill-some-buffers
5697: Offer to kill each buffer, one by one.
5698: @end table
5699:
5700: @findex kill-buffer
5701: @findex kill-some-buffers
5702: @kindex C-x k
5703:
5704: @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you specify
5705: in the minibuffer. The default, used if you type just @key{RET} in the
5706: minibuffer, is to kill the current buffer. If the current buffer is
5707: killed, another buffer is selected; a buffer that has been selected
5708: recently but does not appear in any window now is chosen to be selected.
5709: If the buffer being killed is modified (has unsaved editing) then you are
5710: asked to confirm with @kbd{yes} before the buffer is killed.
5711:
5712: The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
5713: one. An answer of @kbd{y} means to kill the buffer. Killing the current
5714: buffer or a buffer containing unsaved changes selects a new buffer or asks
5715: for confirmation just like @code{kill-buffer}.
5716:
5717: @node Several Buffers,, Kill Buffer, Buffers
5718: @section Operating on Several Buffers
5719: @cindex buffer menu
5720:
5721: The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
5722: you to request operations on various Emacs buffers by editing an Emacs
5723: buffer containing a list of them. You can save buffers, kill them
5724: (here called @dfn{deleting} them, for consistency with Dired), or display
5725: them.
5726:
5727: @table @kbd
5728: @item M-x buffer-menu
5729: Begin editing a buffer listing all Emacs buffers.
5730: @end table
5731:
5732: @findex buffer-menu
5733: The command @code{buffer-menu} writes a list of all Emacs buffers into
5734: the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
5735: mode. The buffer is read-only, and can only be changed through the special
5736: commands described in this section. Most of these commands are graphic
5737: characters. The usual Emacs cursor motion commands can be used in the
5738: @samp{*Buffer List*} buffer. The following special commands apply to the
5739: buffer described on the current line.
5740:
5741: @table @kbd
5742: @item d
5743: Request to delete (kill) the buffer, then move down. The request
5744: shows as a @samp{D} on the line, before the buffer name. Requested
5745: deletions take place when the @kbd{x} command is used.
5746: @item k
5747: Synonym for @kbd{d}.
5748: @item C-d
5749: Like @kbd{d} but move up afterwards instead of down.
5750: @item s
5751: Request to save the buffer. The request shows as an @samp{S} on the
5752: line. Requested saves take place when the @kbd{x} command is used.
5753: You may request both saving and deletion for the same buffer.
5754: @item ~
5755: Mark buffer ``unmodified''. The command @kbd{~} does this
5756: immediately when typed.
5757: @item x
5758: Perform previously requested deletions and saves.
5759: @item u
5760: Remove any request made for the current line, and move down.
5761: @item @key{DEL}
5762: Move to previous line and remove any request made for that line.
5763: @end table
5764:
5765: All the commands that put in or remove flags to request later operations
5766: also move down a line, and accept a numeric argument as a repeat count,
5767: unless otherwise specified.
5768:
5769: There are also special commands to use the buffer list to select another
5770: buffer, and to specify one or more other buffers for display in additional
5771: windows.
5772:
5773: @table @kbd
5774: @item 1
5775: Select the buffer in a full-screen window. This command takes effect
5776: immediately.
5777: @item 2
5778: Immediately set up two windows, with this buffer in one, and the
5779: previously selected buffer (aside from the buffer @samp{*Buffer List*})
5780: in the other.
5781: @item f
5782: Immediately select the buffer in place of the @samp{*Buffer List*} buffer.
5783: @item o
5784: Immediately select the buffer in another window as if by @kbd{C-x 4 b},
5785: leaving @samp{*Buffer List*} visible.
5786: @item q
5787: Immediately select this buffer, and also display in other windows any
5788: buffers previously flagged with the @kbd{m} command. If there are no
5789: such buffers, this command is equivalent to @kbd{1}.
5790: @item m
5791: Flag this buffer to be displayed in another window if the @kbd{q}
5792: command is used. The request shows as a @samp{>} at the beginning of
5793: the line. The same buffer may not have both a delete request and a
5794: display request.
5795: @end table
5796:
5797: All that @code{buffer-menu} does directly is create and select a suitable
5798: buffer, and turn on Buffer Menu mode. Everything else described above is
5799: implemented by the special commands provided in Buffer Menu mode. One
5800: consequence of this is that you can switch from the @samp{*Buffer List*}
5801: buffer to another Emacs buffer, and edit there. You can reselect the
5802: @code{buffer-menu} buffer later, to perform the operations already
5803: requested, or you can kill it, or pay no further attention to it.
5804:
5805: The only difference between @code{buffer-menu} and @code{list-buffers} is
5806: that @code{buffer-menu} selects the @samp{*Buffer List*} buffer and
5807: @code{list-buffers} does not. If you run @code{list-buffers} (that is,
5808: type @kbd{C-x C-b}) and select the buffer list manually, you can use all of
5809: the commands described here.
5810:
5811: @node Windows, Major Modes, Buffers, Top
5812: @chapter Multiple Windows
5813: @cindex windows
5814:
5815: Emacs can split the screen into two or many windows, which can display
5816: parts of different buffers, or different parts of one buffer.
5817:
5818: @menu
5819: * Basic Window:: Introduction to Emacs windows.
5820: * Split Window:: New windows are made by splitting existing windows.
5821: * Other Window:: Moving to another window or doing something to it.
5822: * Pop Up Window:: Finding a file or buffer in another window.
5823: * Change Window:: Deleting windows and changing their sizes.
5824: @end menu
5825:
5826: @node Basic Window, Split Window, Windows, Windows
5827: @section Concepts of Emacs Windows
5828:
5829: When multiple windows are being displayed, each window has an Emacs
5830: buffer designated for display in it. The same buffer may appear in more
5831: than one window; if it does, any changes in its text are displayed in all
5832: the windows where it appears. But the windows showing the same buffer can
5833: show different parts of it, because each window has its own value of point.
5834:
5835: @cindex selected window
5836: At any time, one of the windows is the @dfn{selected window}; the buffer
5837: this window is displaying is the current buffer. The terminal's cursor
5838: shows the location of point in this window. Each other window has a
5839: location of point as well, but since the terminal has only one cursor there
5840: is no way to show where those locations are.
5841:
5842: Commands to move point affect the value of point for the selected Emacs
5843: window only. They do not change the value of point in any other Emacs
5844: window, even one showing the same buffer. The same is true for commands
5845: such as @kbd{C-x b} to change the selected buffer in the selected window;
5846: they do not affect other windows at all. However, there are other commands
5847: such as @kbd{C-x 4 b} that select a different window and switch buffers in
5848: it. Also, all commands that display information in a window, including
5849: (for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
5850: (@code{list-buffers}), work by switching buffers in a nonselected window
5851: without affecting the selected window.
5852:
5853: Each window has its own mode line, which displays the buffer name,
5854: modification status and major and minor modes of the buffer that is
5855: displayed in the window. @xref{Mode Line}, for full details on the mode
5856: line.
5857:
5858: @node Split Window, Other Window, Basic Window, Windows
5859: @section Splitting Windows
5860:
5861: @table @kbd
5862: @item C-x 2
5863: Split the selected window into two windows, one above the other
5864: (@code{split-window-vertically}).
5865: @item C-x 5
5866: Split the selected window into two windows positioned side by side
5867: (@code{split-window-horizontally}).
5868: @end table
5869:
5870: @kindex C-x 2
5871: @findex split-window-vertically
5872: The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the
5873: selected window into two windows, one above the other. Both windows start
5874: out displaying the same buffer, with the same value of point. By default
5875: the two windows each get half the height of the window that was split; a
5876: numeric argument specifies how many lines to give to the top window.
5877:
5878: @kindex C-x 5
5879: @findex split-window-horizontally
5880: @kbd{C-x 5} (@code{split-window-horizontally}) breaks the selected
5881: window into two side-by-side windows. A numeric argument specifies
5882: how many columns to give the one on the left. A line of vertical bars
5883: separates the two windows. Windows that are not the full width of the
5884: screen have mode lines, but they are truncated; also, they do not
5885: always appear in inverse video, because, the Emacs display routines
5886: have not been taught how to display a region of inverse video that is
5887: only part of a line on the screen.
5888:
5889: @vindex truncate-partial-width-windows
5890: When a window is less than the full width, text lines too long to fit are
5891: frequent. Continuing all those lines might be confusing. The variable
5892: @code{truncate-partial-width-windows} can be set non-@code{nil} to force
5893: truncation in all windows less than the full width of the screen,
5894: independent of the buffer being displayed and its value for
5895: @code{truncate-lines}. @xref{Continuation Lines}.@refill
5896:
5897: Horizontal scrolling is often used in side-by-side windows.
5898: @xref{Display}.
5899:
5900: @node Other Window, Pop Up Window, Split Window, Windows
5901: @section Using Other Windows
5902:
5903: @table @kbd
5904: @item C-x o
5905: Select another window (@code{other-window}). That is @kbd{o}, not zero.
5906: @item C-M-v
5907: Scroll the next window (@code{scroll-other-window}).
5908: @item M-x compare-windows
5909: Find next place where the text in the selected window does not match
5910: the text in the next window.
5911: @end table
5912:
5913: @kindex C-x o
5914: @findex other-window
5915: To select a different window, use @kbd{C-x o} (@code{other-window}).
5916: That is an @kbd{o}, for `other', not a zero. When there are more than two
5917: windows, this command moves through all the windows in a cyclic order,
5918: generally top to bottom and left to right. From the rightmost and
5919: bottommost window, it goes back to the one at the upper left corner. A
5920: numeric argument means to move several steps in the cyclic order of
5921: windows. A negative argument moves around the cycle in the opposite order.
5922: When the minibuffer is active, the minibuffer is the last window in the
5923: cycle; you can switch from the minibuffer window to one of the other
5924: windows, and later switch back and finish supplying the minibuffer argument
5925: that is requested. @xref{Minibuffer Edit}.
5926:
5927: @kindex C-M-v
5928: @findex scroll-other-window
5929: The usual scrolling commands (@pxref{Display}) apply to the selected
5930: window only, but there is one command to scroll the next window.
5931: @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that @kbd{C-x o}
5932: would select. It takes arguments, positive and negative, like @kbd{C-v}.
5933:
5934: @findex compare-windows
5935: The command @kbd{M-x compare-windows} compares the text in the current
5936: window with that in the next window. Comparison starts at point in each
5937: window. Point moves forward in each window, a character at a time in each
5938: window, until the next characters in the two windows are different. Then
5939: the command is finished.
5940:
5941: @node Pop Up Window, Change Window, Other Window, Windows
5942: @section Displaying in Another Window
5943:
5944: @kindex C-x 4
5945: @kbd{C-x 4} is a prefix key for commands that select another window
5946: (splitting the window if there is only one) and select a buffer in that
5947: window. Different @kbd{C-x 4} commands have different ways of finding the
5948: buffer to select.
5949:
5950: @findex switch-to-buffer-other-window
5951: @findex find-file-other-window
5952: @findex find-tag-other-window
5953: @findex dired-other-window
5954: @findex mail-other-window
5955: @table @kbd
5956: @item C-x 4 b @var{bufname} @key{RET}
5957: Select buffer @var{bufname} in another window. This runs @*
5958: @code{switch-to-buffer-other-window}.
5959: @item C-x 4 f @var{filename} @key{RET}
5960: Visit file @var{filename} and select its buffer in another window. This
5961: runs @code{find-file-other-window}. @xref{Visiting}.
5962: @item C-x 4 d @var{directory} @key{RET}
5963: Select a Dired buffer for directory @var{directory} in another window.
5964: This runs @code{dired-other-window}. @xref{Dired}.
5965: @item C-x 4 m
5966: Start composing a mail message in another window. This runs
5967: @code{mail-other-window}, and its same-window version is @kbd{C-x m}
5968: (@pxref{Sending Mail}).
5969: @item C-x 4 .
5970: Find a tag in the current tag table in another window. This runs
5971: @code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
5972: (@pxref{Tags}).
5973: @end table
5974:
5975: @node Change Window,, Pop Up Window, Windows
5976: @section Deleting and Rearranging Windows
5977:
5978: @table @kbd
5979: @item C-x 0
5980: Get rid of the selected window (@code{kill-window}). That is a zero.
5981: @item C-x 1
5982: Get rid of all windows except the selected one (@code{delete-other-windows}).
5983: @item C-x ^
5984: Make the selected window taller, at the expense of the other(s)
5985: (@code{enlarge-window}).
5986: @item C-x @}
5987: Make the selected window wider (@code{enlarge-window-horizontally}).
5988: @end table
5989:
5990: @kindex C-x 0
5991: @findex delete-window
5992: To delete a window, type @kbd{C-x 0} (@code{delete-window}). (That is a
5993: zero.) The space occupied by the deleted window is distributed among the
5994: other active windows (but not the minibuffer window, even if that is active
5995: at the time). Once a window is deleted, its attributes are forgotten;
5996: there is no automatic way to make another window of the same shape or
5997: showing the same buffer. But the buffer continues to exist, and you can
5998: select it in any window with @kbd{C-x b}.
5999:
6000: @kindex C-x 1
6001: @findex delete-other-windows
6002: @kbd{C-x 1} (@code{delete-other-windows}) is more powerful than @kbd{C-x 0};
6003: it deletes all the windows except the selected one (and the minibuffer);
6004: the selected window expands to use the whole screen except for the echo
6005: area.
6006:
6007: @kindex C-x ^
6008: @findex enlarge-window
6009: @kindex C-x @}
6010: @findex enlarge-window-horizontally
6011: @vindex window-min-height
6012: @vindex window-min-width
6013: To readjust the division of space among existing windows, use @kbd{C-x ^}
6014: (@code{enlarge-window}). It makes the currently selected window get one
6015: line bigger, or as many lines as is specified with a numeric argument.
6016: With a negative argument, it makes the selected window smaller. @kbd{C-x
6017: @}} (@code{enlarge-window-horizontally}) makes the selected window wider
6018: by the specified number of columns. The extra screen space given to a
6019: window comes from one of its neighbors, if that is possible; otherwise, all
6020: the competing windows are shrunk in the same proportion. If this makes any
6021: windows too small, those windows are deleted and their space is divided up.
6022: The minimum size is specified by the variables @code{window-min-height} and
6023: @code{window-min-width}.
6024:
6025: @node Major Modes, Indentation, Windows, Top
6026: @chapter Major Modes
6027: @cindex major modes
6028: @kindex TAB
6029: @kindex DEL
6030: @kindex LFD
6031:
6032: Emacs has many different @dfn{major modes}, each of which customizes
6033: Emacs for editing text of a particular sort. The major modes are mutually
6034: exclusive, and each buffer has one major mode at any time. The mode line
6035: normally contains the name of the current major mode, in parentheses.
6036: @xref{Mode Line}.
6037:
6038: The least specialized major mode is called @dfn{Fundamental mode}. This
6039: mode has no mode-specific redefinitions or variable settings, so that each
6040: Emacs command behaves in its most general manner, and each option is in its
6041: default state. For editing any specific type of text, such as Lisp code or
6042: English text, you should switch to the appropriate major mode, such as Lisp
6043: mode or Text mode.
6044:
6045: Selecting a major mode changes the meanings of a few keys to become more
6046: specifically adapted to the language being edited. The ones which are
6047: changed frequently are @key{TAB}, @key{DEL}, and @key{LFD}. In addition,
6048: the commands which handle comments use the mode to determine how comments
6049: are to be delimited. Many major modes redefine the syntactical properties
6050: of characters appearing in the buffer. @xref{Syntax}.
6051:
6052: The major modes fall into three major groups. Lisp mode (which has
6053: several variants), C mode and Muddle mode are for specific programming
6054: languages. Text mode, Nroff mode, @TeX{} mode and Outline mode are for
6055: editing English text. The remaining major modes are not intended for use
6056: on users' files; they are used in buffers created for specific purposes by
6057: Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), and
6058: Mail mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), and Shell
6059: mode for buffers used for communicating with an inferior shell process
6060: (@pxref{Interactive Shell}).
6061:
6062: Most programming language major modes specify that only blank lines
6063: separate paragraphs. This is so that the paragraph commands remain useful.
6064: @xref{Paragraphs}. They also cause Auto Fill mode to use the definition of
6065: @key{TAB} to indent the new lines it creates. This is because most lines
6066: in a program are usually indented. @xref{Indentation}.
6067:
6068: @menu
6069: * Choosing Modes:: How major modes are specified or chosen.
6070: @end menu
6071:
6072: @node Choosing Modes,,Major Modes,Major Modes
6073: @section How Major Modes are Chosen
6074:
6075: You can select a major mode explicitly for the current buffer, but
6076: most of the time Emacs determines which mode to use based on the file
6077: name or some text in the file.
6078:
6079: Explicit selection of a new major mode is done with a @kbd{M-x} command.
6080: From the name of a major mode, add @code{-mode} to get the name of a
6081: command to select that mode. Thus, you can enter Lisp mode by executing
6082: @kbd{M-x lisp-mode}.
6083:
6084: @vindex auto-mode-alist
6085: When you visit a file, Emacs usually chooses the right major mode based
6086: on the file's name. For example, files whose names end in @code{.c} are
6087: edited in C mode. The correspondence between file names and major mode is
6088: controlled by the variable @code{auto-mode-alist}. Its value is a list in
6089: which each element has the form
6090:
6091: @example
6092: (@var{regexp} . @var{mode-function})
6093: @end example
6094:
6095: @noindent
6096: For example, one element normally found in the list has the form
6097: @code{(@t{"\\.c$"} . c-mode)}, and it is responsible for selecting C mode
6098: for files whose names end in @file{.c}. (Note that @samp{\\} is needed in
6099: Lisp syntax to include a @samp{\} in the string, which is needed to
6100: suppress the special meaning of @samp{.} in regexps.) The only practical
6101: way to change this variable is with Lisp code.
6102:
6103: You can specify which major mode should be used for editing a certain
6104: file by a special sort of text in the first nonblank line of the file. The
6105: mode name should appear in this line both preceded and followed by
6106: @samp{-*-}. Other text may appear on the line as well. For example,
6107:
6108: @example
6109: ;-*-Lisp-*-
6110: @end example
6111:
6112: @noindent
6113: tells Emacs to use Lisp mode. Note how the semicolon is used to make Lisp
6114: treat this line as a comment. Such an explicit specification overrides any
6115: defaulting based on the file name.
6116:
6117: Another format of mode specification is
6118:
6119: @example
6120: -*-Mode: @var{modename};-*-
6121: @end example
6122:
6123: @noindent
6124: which allows other things besides the major mode name to be specified.
6125: However, Emacs does not look for anything except the mode name.
6126:
6127: The major mode can also be specified in a local variables list.
6128: @xref{File Variables}.
6129:
6130: @vindex default-major-mode
6131: When a file is visited that does not specify a major mode to use, or when
6132: a new buffer is created with @kbd{C-x b}, the major mode used is that
6133: specified by the variable @code{default-major-mode}. Normally this value
6134: is the symbol @code{fundamental-mode}, which specifies Fundamental mode.
6135: If @code{default-major-mode} is @code{nil}, the major mode is taken from
6136: the previously selected buffer.
6137:
6138: @node Indentation, Text, Major Modes, Top
6139: @chapter Indentation
6140: @cindex indentation
6141:
6142: @c WideCommands
6143: @table @kbd
6144: @item @key{TAB}
6145: Indent current line ``appropriately'' in a mode-dependent fashion.
6146: @item @key{LFD}
6147: Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
6148: @item M-^
6149: Merge two lines (@code{delete-indentation}). This would cancel out
6150: the effect of @key{LFD}.
6151: @item C-M-o
6152: Split line at point; text on the line after point becomes a new line
6153: indented to the same column that it now starts in (@code{split-line}).
6154: @item M-m
6155: Move (forward or back) to the first nonblank character on the current
6156: line (@code{back-to-indentation}).
6157: @item C-M-\
6158: Indent several lines to same column (@code{indent-region}).
6159: @item C-x @key{TAB}
6160: Shift block of lines rigidly right or left (@code{indent-rigidly}).
6161: @item M-i
6162: Indent from point to the next prespecified tab stop column
6163: (@code{tab-to-tab-stop}).
6164: @item M-x indent-relative
6165: Indent from point to under an indentation point in the previous line.
6166: @end table
6167:
6168: @kindex TAB
6169: @cindex indentation
6170: Most programming languages have some indentation convention. For Lisp
6171: code, lines are indented according to their nesting in parentheses. The
6172: same general idea is used for C code, though many details are different.
6173:
6174: Whatever the language, to indent a line, use the @key{TAB} command. Each
6175: major mode defines this command to perform the sort of indentation
6176: appropriate for the particular language. In Lisp mode, @key{TAB} aligns
6177: the line according to its depth in parentheses. No matter where in the
6178: line you are when you type @key{TAB}, it aligns the line as a whole. In C
6179: mode, @key{TAB} implements a subtle and sophisticated indentation style that
6180: knows about many aspects of C syntax.
6181:
6182: @kindex TAB
6183: In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
6184: indents to the next tab stop column. You can set the tab stops with
6185: @kbd{M-x edit-tab-stops}.
6186:
6187: @menu
6188: * Indentation Commands:: Various commands and techniques for indentation.
6189: * Tab Stops:: You can set arbitrary "tab stops" and then
6190: indent to the next tab stop when you want to.
6191: * Just Spaces:: You can request indentation using just spaces.
6192: @end menu
6193:
6194: @node Indentation Commands, Tab Stops, Indentation, Indentation
6195: @section Indentation Commands and Techniques
6196: @c ??? Explain what Emacs has instead of space-indent-flag.
6197:
6198: If you just want to insert a tab character in the buffer, you can type
6199: @kbd{C-q @key{TAB}}.
6200:
6201: @kindex M-m
6202: @findex back-to-indentation
6203: To move over the indentation on a line, do @kbd{Meta-m}
6204: (@code{back-to-indentation}). This command, given anywhere on a line,
6205: positions point at the first nonblank character on the line.
6206:
6207: To insert an indented line before the current line, do @kbd{C-a C-o
6208: @key{TAB}}. To make an indented line after the current line, use @kbd{C-e
6209: @key{LFD}}.
6210:
6211: @kindex C-M-o
6212: @findex split-line
6213: @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
6214: the line vertically down, so that the current line becomes two lines.
6215: @kbd{C-M-o} first moves point forward over any spaces and tabs. Then it
6216: inserts after point a newline and enough indentation to reach the same
6217: column point is on. Point remains before the inserted newline; in this
6218: regard, @kbd{C-M-o} resembles @kbd{C-o}.
6219:
6220: @kindex M-\
6221: @kindex M-^
6222: @findex delete-horizontal-space
6223: @findex delete-indentation
6224: To join two lines cleanly, use the @kbd{Meta-^} (@code{delete-indentation})
6225: command to delete the indentation at the front of the current line, and the
6226: line boundary as well. They are replaced by a single space, or by no space
6227: if at the beginning of a line or before a @samp{)} or after a @samp{(}. To
6228: delete just the indentation of a line, go to the beginning of the line and
6229: use @kbd{Meta-\} (@code{delete-horizontal-space}), which deletes all spaces
6230: and tabs around the cursor.
6231:
6232: @kindex C-M-\
6233: @kindex C-x TAB
6234: @findex indent-region
6235: @findex indent-rigidly
6236: There are also commands for changing the indentation of several lines at
6237: once. @kbd{Control-Meta-\} (@code{indent-region}) gives each line which
6238: begins in the region the ``usual'' indentation by invoking @key{TAB} at the
6239: beginning of the line. A numeric argument specifies the column to indent
6240: to, and each line is shifted left or right so that its first nonblank
6241: character appears in that column. @kbd{C-x @key{TAB}}
6242: (@code{indent-rigidly}) moves all of the lines in the region right by its
6243: argument (left, for negative arguments). The whole group of lines moves
6244: rigidly sideways, which is how the command gets its name.@refill
6245:
6246: @findex indent-relative
6247: @kbd{M-x indent-relative} indents at point based on the previous line
6248: (actually, the last nonempty line.) It inserts whitespace at point, moving
6249: point, until it is underneath an indentation point in the previous line.
6250: An indentation point is the end of a sequence of whitespace or the end of
6251: the line. If point is farther right than any indentation point in the
6252: previous line, the whitespace before point is deleted and the first
6253: indentation point then applicable is used. If no indentation point is
6254: applicable even then, @code{tab-to-tab-stop} is run (see next section).
6255:
6256: @code{indent-relative} is the definition of @key{TAB} in Indented Text
6257: mode. @xref{Text}.
6258:
6259: @node Tab Stops, Just Spaces, Indentation Commands, Indentation
6260: @section Tab Stops
6261:
6262: @kindex M-i
6263: @findex tab-to-tab-stop
6264: For typing in tables, you can use Text mode's definition of @key{TAB},
6265: @code{tab-to-tab-stop}. This command inserts indentation before point,
6266: enough to reach the next tab stop column. If you are not in Text mode,
6267: this function can be found on @kbd{M-i} anyway.
6268:
6269: @findex edit-tab-stops
6270: @findex edit-tab-stops-note-changes
6271: @kindex C-c C-c (Edit Tab Stops)
6272: @vindex tab-stop-list
6273: The tab stops used by @kbd{M-i} can be set arbitrarily by the user.
6274: They are stored in a variable called @code{tab-stop-list}, as a list of
6275: column-numbers in increasing order.
6276:
6277: The convenient way to set the tab stops is using @kbd{M-x edit-tab-stops},
6278: which creates and selects a buffer containing a description of the tab stop
6279: settings. You can edit this buffer to specify different tab stops, and
6280: then type @kbd{C-c C-c} to make those new tab stops take effect. In the
6281: tab stop buffer, @kbd{C-c C-c} runs the function
6282: @code{edit-tab-stops-note-changes} rather than its usual definition
6283: @code{save-buffer}. @code{edit-tab-stops} records which buffer was current
6284: when you invoked it, and stores the tab stops back in that buffer; normally
6285: all buffers share the same tab stops and changing them in one buffer
6286: affects all, but if you happen to make @code{tab-stop-list} local in one
6287: buffer then @code{edit-tab-stops} in that buffer will edit the local
6288: settings.
6289:
6290: Here is what the text representing the tab stops looks like for ordinary
6291: tab stops every eight columns.
6292:
6293: @example
6294: : : : : : :
6295: 0 1 2 3 4
6296: 0123456789012345678901234567890123456789012345678
6297: To install changes, type C-c C-c
6298: @end example
6299:
6300: The first line contains a colon at each tab stop. The remaining lines
6301: are present just to help you see where the colons are and know what to do.
6302:
6303: Note that the tab stops that control @code{tab-to-tab-stop} have nothing
6304: to do with displaying tab characters in the buffer. @xref{Display Vars},
6305: for more information on that.
6306:
6307: @node Just Spaces,, Tab Stops, Indentation
6308: @section Tabs vs. Spaces
6309:
6310: @vindex indent-tabs-mode
6311: Emacs normally uses both tabs and spaces to indent lines. If you prefer,
6312: all indentation can be made from spaces only. To request this, set
6313: @code{indent-tabs-mode} to @code{nil}. This is a per-buffer variable;
6314: altering the variable affects only the current buffer, but there is a
6315: default value which you can change as well. @xref{Locals}.
6316:
6317: @findex tabify
6318: @findex untabify
6319: There are also commands to convert tabs to spaces or vice versa, always
6320: preserving the columns of all nonblank text. @kbd{M-x tabify} scans the
6321: region for sequences of spaces, and converts sequences of at least three
6322: spaces to tabs if that can be done without changing indentation. @kbd{M-x
6323: untabify} changes all tabs in the region to appropriate numbers of spaces.
6324:
6325: @node Text, Programs, Indentation, Top
6326: @chapter Commands for Human Languages
6327: @cindex text
6328:
6329: The term @dfn{text} has two widespread meanings in our area of the
6330: computer field. One is data that is a sequence of characters. Any file
6331: that you edit with Emacs is text, in this sense of the word. The other
6332: meaning is more restrictive: a sequence of characters in a human language
6333: for humans to read (possibly after processing by a text formatter), as
6334: opposed to a program or commands for a program.
6335:
6336: Human languages have syntactic/stylistic conventions that can be
6337: supported or used to advantage by editor commands: conventions involving
6338: words, sentences, paragraphs, and capital letters. This chapter describes
6339: Emacs commands for all of these things. There are also commands for
6340: @dfn{filling}, or rearranging paragraphs into lines of approximately equal
6341: length. The commands for moving over and killing words, sentences
6342: and paragraphs, while intended primarily for editing text, are also often
6343: useful for editing programs.
6344:
6345: Emacs has several major modes for editing human language text.
6346: If the file contains text pure and simple, use Text mode, which customizes
6347: Emacs in small ways for the syntactic conventions of text. For text which
6348: contains embedded commands for text formatters, Emacs has other major modes,
6349: each for a particular text formatter. Thus, for input to @TeX{}, you would
6350: use @TeX{} mode; for input to nroff, Nroff mode.
6351:
6352: @menu
6353: * Text Mode:: The major modes for editing text files.
6354: * Nroff Mode:: The major mode for editing input to the formatter nroff.
6355: * TeX Mode:: The major modes for editing input to the formatter TeX.
6356: * Outline Mode::The major mode for editing outlines.
6357: * Words:: Moving over and killing words.
6358: * Sentences:: Moving over and killing sentences.
6359: * Paragraphs:: Moving over paragraphs.
6360: * Pages:: Moving over pages.
6361: * Filling:: Filling or justifying text
6362: * Case:: Changing the case of text
6363: @end menu
6364:
6365: @node Text Mode, Words, Text, Text
6366: @section Text Mode
6367:
6368: @findex tab-to-tab-stop
6369: @findex edit-tab-stops
6370: @cindex Text mode
6371: @kindex TAB
6372: @findex text-mode
6373: Editing files of text in a human language ought to be done using Text
6374: mode rather than Lisp or Fundamental mode. Invoke @kbd{M-x text-mode} to
6375: enter Text mode. In Text mode, @key{TAB} runs the function
6376: @code{tab-to-tab-stop}, which allows you to use arbitrary tab stops set
6377: with @kbd{M-x edit-tab-stops} (@pxref{Tab Stops}). Features concerned with
6378: comments in programs are turned off except when explicitly invoked. The
6379: syntax table is changed so that periods are not considered part of a word,
6380: while apostrophes, backspaces and underlines are.
6381:
6382: @findex indented-text-mode
6383: A similar variant mode is Indented Text mode, intended for editing text
6384: in which most lines are indented. This mode defines @key{TAB} to run
6385: @code{indent-relative} (@pxref{Indentation}), and makes Auto Fill indent
6386: the lines it creates. The result is that normally a line made by Auto
6387: Filling, or by @key{LFD}, is indented just like the previous line. Use
6388: @kbd{M-x indented-text-mode} to select this mode.
6389:
6390: @vindex text-mode-hook
6391: Entering Text mode or Indented Text mode calls with no arguments the
6392: value of the variable @code{text-mode-hook}, if that value exists and is
6393: not @code{nil}. This value is also called when modes related to Text mode
6394: are entered; this includes Nroff mode, @TeX{} mode, Outline mode and Mail
6395: mode. Your hook can look at the value of @code{major-mode} to see which of
6396: these modes is actually being entered.
6397:
6398: @menu
6399: Two modes similar to Text mode are of use for editing text that is to
6400: be passed through a text formatter before achieving the form in which
6401: humans are to read it.
6402:
6403: * Nroff Mode:: The major mode for editing input to the formatter nroff.
6404: * TeX Mode:: The major modes for editing input to the formatter TeX.
6405:
6406: Another similar mode is used for editing outlines. It allows you
6407: to view the text at various levels of detail. You can view either
6408: the outline headings alone or both headings and text; you can also
6409: hide some of the headings at lower levels from view to make the high
6410: level structure more visible.
6411:
6412: * Outline Mode::The major mode for editing outlines.
6413: @end menu
6414:
6415: @node Nroff Mode, TeX Mode, Text Mode, Text Mode
6416: @subsection Nroff Mode
6417:
6418: @cindex nroff
6419: @findex nroff-mode
6420: Nroff mode is a mode like Text mode but modified to handle nroff commands
6421: present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It
6422: differs from Text mode in only a few ways. All nroff command lines are
6423: considered paragraph separators, so that filling will never garble the
6424: nroff commands. Pages are separated by @samp{.bp} commands. Comments
6425: start with backslash-doublequote. Also, three special commands are
6426: provided that are not in Text mode:
6427:
6428: @findex forward-text-line
6429: @findex backward-text-line
6430: @findex count-text-lines
6431: @kindex M-n
6432: @kindex M-p
6433: @kindex M-?
6434: @table @kbd
6435: @item M-n
6436: Move to the beginning of the next line that isn't an nroff command
6437: (@code{forward-text-line}). An argument is a repeat count.
6438: @item M-p
6439: Like @kbd{M-n} but move up (@code{backward-text-line}).
6440: @item M-?
6441: Prints in the echo area the number of text lines (lines that are not
6442: nroff commands) in the region (@code{count-text-lines}).
6443: @end table
6444:
6445: @findex electric-nroff-mode
6446: The other feature of Nroff mode is that you can turn on Electric
6447: Nroff newline mode. This is a minor mode that you can turn on or off
6448: with @kbd{M-x electric-nroff-mode} (@pxref{Minor Modes}). When the
6449: mode is on, each time you use @key{RET} to end a line that contains
6450: an nroff command that opens a kind of grouping, the matching
6451: nroff command to close that grouping is automatically inserted on
6452: the following line. For example, if you are at the beginning of
6453: a line and type @kbd{.@: ( b @key{RET}}, the matching command
6454: @samp{.)b} will be inserted on a new line following point.
6455:
6456: @vindex nroff-mode-hook
6457: Entering Nroff mode calls with no arguments the value of the variable
6458: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
6459: does the same with the variable @code{nroff-mode-hook}.
6460:
6461: @node TeX Mode, Outline Mode, Nroff Mode, Text Mode
6462: @subsection @TeX{} Mode
6463: @cindex TeX
6464: @cindex LaTeX
6465: @findex TeX-mode
6466: @findex tex-mode
6467: @findex plain-tex-mode
6468: @findex LaTeX-mode
6469: @findex plain-TeX-mode
6470: @findex latex-mode
6471:
6472: @TeX{} is a powerful text formatter written by Donald Knuth; it is also
6473: free, like GNU Emacs. La@TeX{} is a simplified input format for @TeX{},
6474: implemented by @TeX{} macros. It comes with @TeX{}.@refill
6475:
6476: Emacs has a special @TeX{} mode for editing @TeX{} input files.
6477: It provides facilities for checking the balance of delimiters and for
6478: invoking @TeX{} on all or part of the file.
6479:
6480: @TeX{} mode has two variants, Plain @TeX{} mode and La@TeX{} mode
6481: (actually two distinct major modes which differ only slightly). They are
6482: designed for editing the two different input formats. The command @kbd{M-x
6483: tex-mode} looks at the contents of the buffer to determine whether the
6484: contents appear to be La@TeX{} input or not; it then selects the
6485: appropriate mode. If it can't tell which is right (e.g., the buffer is
6486: empty), the variable @code{TeX-default-mode} controls which mode is used.
6487:
6488: The commands @kbd{M-x plain-tex-mode} and @kbd{M-x latex-mode} explicitly
6489: select the two variants of @TeX{} mode. Use these commands when @kbd{M-x
6490: tex-mode} does not guess right.@refill
6491:
6492: @menu
6493: * Editing: TeX Editing. Special commands for editing in TeX mode.
6494: * Printing: TeX Print. Commands for printing part of a file with TeX.
6495: @end menu
6496:
6497: @TeX{} for Unix systems can be obtained from the University of Washington
6498: for a distribution fee.
6499:
6500: To order a full distribution, send $140.00 for a 1/2 inch
6501: 9-track tape, $165.00 for two 4-track 1/4 inch cartridge tapes
6502: (foreign sites $150.00, for 1/2 inch, $175.00 for 1/4 inch, to cover
6503: the extra postage) payable to the University of Washington to:
6504:
6505: @display
6506: The Director
6507: Northwest Computer Support Group, DW-10
6508: University of Washington
6509: Seattle, Washington 98195
6510: @end display
6511:
6512: @noindent
6513: Purchase orders are acceptable, but there is an extra charge of
6514: $10.00, to pay for processing charges. (Total of $150 for domestic
6515: sites, $175 for foreign sites).
6516:
6517: The normal distribution is a tar tape, blocked 20, 1600 bpi, on an
6518: industry standard 2400 foot half-inch reel. The physical format for
6519: the 1/4 inch streamer cartridges uses QIC-11, 8000 bpi, 4-track
6520: serpentine recording for the SUN. Also, SystemV tapes can be written
6521: in cpio format, blocked 5120 bytes, ASCII headers.
6522:
6523: @node TeX Editing,TeX Print,TeX Mode,TeX Mode
6524: @subsubsection @TeX{} Editing Commands
6525:
6526: Here are the special commands provided in @TeX{} mode for editing the
6527: text of the file.
6528:
6529: @table @kbd
6530: @item "
6531: Insert, according to context, either @samp{@`@`} or @samp{"} or
6532: @samp{@'@'} (@code{TeX-insert-quote}).
6533: @item @key{LFD}
6534: Insert a paragraph break (two newlines) and check the previous
6535: paragraph for unbalanced braces or dollar signs
6536: (@code{TeX-terminate-paragraph}).
6537: @item M-x validate-TeX-buffer
6538: Check each paragraph in the buffer for unbalanced braces or dollar signs.
6539: @item M-@{
6540: Insert @samp{@{@}} and position point between them (@code{TeX-insert-braces}).
6541: @item M-@}
6542: Move forward past the next unmatched close brace (@code{up-list}).
6543: @item C-c C-f
6544: Close a block for La@TeX{} (@code{TeX-close-LaTeX-block}).
6545: @end table
6546:
6547: @findex TeX-insert-quote
6548: @kindex " (TeX mode)
6549: In @TeX{}, the character @samp{"} is not normally used; one uses @samp{``}
6550: to start a quotation and @samp{''} to end one. @TeX{} mode defines the key
6551: @kbd{"} to insert @samp{``} after whitespace or an open brace, @samp{"}
6552: after a backslash, or @samp{''} otherwise. This is done by the command
6553: @code{TeX-insert-quote}. If you need the character @samp{"} itself in
6554: unusual contexts, use @kbd{C-q} to insert it. Also, @kbd{"} with a
6555: numeric argument always inserts that number of @samp{"} characters.
6556:
6557: In @TeX{} mode, @samp{$} has a special syntax code which attempts to
6558: understand the way @TeX{} math mode delimiters match. When you insert a
6559: @samp{$} that is meant to exit math mode, the position of the matching
6560: @samp{$} that entered math mode is displayed for a second. This is the
6561: same feature that displays the open brace that matches a close brace that
6562: is inserted. However, there is no way to tell whether a @samp{$} enters
6563: math mode or leaves it; so when you insert a @samp{$} that enters math
6564: mode, the previous @samp{$} position is shown as if it were a match, even
6565: though they are actually unrelated.
6566:
6567: @findex TeX-insert-braces
6568: @kindex M-@{ (TeX mode)
6569: @findex up-list
6570: @kindex M-@} (TeX mode)
6571: If you prefer to keep braces balanced at all times, you can use @kbd{M-@{}
6572: (@code{TeX-insert-braces}) to insert a pair of braces. It leaves point
6573: between the two braces so you can insert the text that belongs inside.
6574: Afterward, use the command @kbd{M-@}} (@code{up-list}) to move forward
6575: past the close brace.
6576:
6577: @findex validate-TeX-buffer
6578: @findex TeX-terminate-paragraph
6579: @kindex LFD (TeX mode)
6580: There are two commands for checking the matching of braces. @key{LFD}
6581: (@code{TeX-terminate-paragraph}) checks the paragraph before point, and
6582: inserts two newlines to start a new paragraph. It prints a message in the
6583: echo area if any mismatch is found. @kbd{M-x validate-TeX-buffer} checks
6584: the entire buffer, paragraph by paragraph. When it finds a paragraph that
6585: contains a mismatch, it displays point at the beginning of the paragraph
6586: for a few seconds and pushes a mark at that spot. Scanning continues
6587: until the whole buffer has been checked or until you type another key.
6588: The positions of the last several paragraphs with mismatches can be
6589: found in the mark ring (@pxref{Mark Ring}).
6590:
6591: Note that square brackets and parentheses are matched in @TeX{} mode, not
6592: just braces. This is wrong for the purpose of checking @TeX{} syntax.
6593: However, parentheses and square brackets are likely to be used in text as
6594: matching delimiters and it is useful for the various motion commands and
6595: automatic match display to work with them.
6596:
6597: @findex TeX-close-LaTeX-block
6598: @kindex C-c C-f (LaTeX mode)
6599: In La@TeX{} input, @samp{\begin} and @samp{\end} commands must balance.
6600: After you insert a @samp{\begin}, use @kbd{C-c C-f}
6601: (@code{TeX-close-LaTeX-block}) to insert automatically a matching
6602: @samp{\end} (on a new line following the @samp{\begin}). A blank line is
6603: inserted between the two, and point is left there.@refill
6604:
6605: @node TeX Print,,TeX Editing,TeX Mode
6606: @subsubsection @TeX{} Printing Commands
6607:
6608: You can invoke @TeX{} as an inferior of Emacs on either the entire
6609: contents of the buffer or just a region at a time. Running @TeX{} in
6610: this way on just one chapter is a good way to see what your changes
6611: look like without taking the time to format the entire file.
6612:
6613: @table @kbd
6614: @item C-c C-r
6615: Invoke @TeX{} on the current region, plus the buffer's header
6616: (@code{TeX-region}).
6617: @item C-c C-b
6618: Invoke @TeX{} on the entire current buffer (@code{TeX-buffer}).
6619: @item C-c C-l
6620: Recenter the window showing output from the inferior @TeX{} so that
6621: the last line can be seen (@code{TeX-recenter-output-buffer}).
6622: @item C-c C-k
6623: Kill the inferior @TeX{} (@code{TeX-kill-job}).
6624: @item C-c C-p
6625: Print the output from the last @kbd{C-c C-r} or @kbd{C-c C-b} command
6626: (@code{TeX-print}).
6627: @item C-c C-q
6628: Show the printer queue (@code{TeX-show-print-queue}).
6629: @end table
6630:
6631: @findex TeX-buffer
6632: @kindex C-c C-b (TeX mode)
6633: @findex TeX-print
6634: @kindex C-c C-p (TeX mode)
6635: @findex TeX-show-print-queue
6636: @kindex C-c C-q (TeX mode)
6637: You can pass the current buffer through an inferior @TeX{} by means of
6638: @kbd{C-c C-b} (@code{TeX-buffer}). The formatted output appears in a file
6639: in @file{/tmp}; to print it, type @kbd{C-c C-p} (@code{TeX-print}).
6640: Afterward use @kbd{C-c C-q} (@code{TeX-show-print-queue}) to view the
6641: progress of your output towards being printed.
6642:
6643: @findex TeX-kill-job
6644: @kindex C-c C-k (TeX mode)
6645: @findex TeX-recenter-output-buffer
6646: @kindex C-c C-l (TeX mode)
6647: The console output from @TeX{}, including any error messages, appear in a
6648: buffer called @samp{*TeX-shell*}. If @TeX{} gets an error, you can switch
6649: to this buffer and feed it input (this works as in Shell mode;
6650: @pxref{Interactive Shell}). Without switching to this buffer you can scroll
6651: it so that its last line is visible by typing @kbd{C-c C-l}.
6652:
6653: Type @kbd{C-c C-k} (@code{TeX-kill-job}) to kill the @TeX{} process if
6654: you see that its output is no longer useful. Using @kbd{C-c C-b} or
6655: @kbd{C-c C-r} also kills any @TeX{} process still running.@refill
6656:
6657: @findex TeX-region
6658: @kindex C-c C-r (TeX mode)
6659: You can also pass an arbitrary region through an inferior @TeX{} by typing
6660: @kbd{C-c C-r} (@code{TeX-region}). This is tricky, however, because most files
6661: of @TeX{} input contain commands at the beginning to set parameters and
6662: define macros, without which no later part of the file will format
6663: correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a
6664: part of the file as containing essential commands; it is included before
6665: the specified region as part of the input to @TeX{}. The designated part
6666: of the file is called the @dfn{header}.
6667:
6668: @cindex header (TeX mode)
6669: To indicate the bounds of the header in Plain @TeX{} mode, you insert two
6670: special strings in the file. Insert @samp{%**start of header} before the
6671: header, and @samp{%**end of header} after it. Each string must appear
6672: entirely on one line, but there may be other text on the line before or
6673: after. The lines containing the two strings are included in the header.
6674: If @samp{%**start of header} does not appear within the first 100 lines of
6675: the buffer, @kbd{C-c C-r} assumes that there is no header.
6676:
6677: In La@TeX{} mode, the header begins with @samp{\documentstyle} and ends
6678: with @samp{\begin@{document@}}. These are commands that La@TeX{} requires
6679: you to use in any case, so nothing special needs to be done to identify the
6680: header.
6681:
6682: @vindex TeX-mode-hook
6683: @vindex LaTeX-mode-hook
6684: @vindex plain-TeX-mode-hook
6685: Entering either kind of @TeX{} mode calls with no arguments the value of
6686: the variable @code{text-mode-hook}, if that value exists and is not
6687: @code{nil}; then it does the same with the variable @code{TeX-mode-hook}.
6688: Finally it does the same with either @code{plain-TeX-mode-hook} or
6689: @code{LaTeX-mode-hook}.
6690:
6691: @node Outline Mode,, TeX Mode, Text Mode
6692: @subsection Outline Mode
6693: @cindex outlines
6694: @cindex selective display
6695: @cindex invisible lines
6696:
6697: Outline mode is a major mode much like Text mode but intended for editing
6698: outlines. It allows you to make parts of the text temporarily invisible
6699: so that you can see just the overall structure of the outline. Type
6700: @kbd{M-x outline-mode} to turn on Outline mode in the current buffer.
6701:
6702: @vindex outline-mode-hook
6703: Entering Outline mode calls with no arguments the value of the variable
6704: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
6705: does the same with the variable @code{outline-mode-hook}.
6706:
6707: When a line is invisible in outline mode, it does not appear on the
6708: screen. The screen appears exactly as if the invisible line
6709: were deleted, except that an ellipsis (three periods in a row) appears
6710: at the end of the previous visible line (only one ellipsis no matter
6711: how many invisible lines follow).
6712:
6713: All editing commands treat the text of the invisible line as part of the
6714: previous visible line. For example, @kbd{C-n} moves onto the next visible
6715: line. Killing an entire visible line, including its terminating newline,
6716: really kills all the following invisible lines along with it; yanking it
6717: all back yanks the invisible lines and they remain invisible.
6718:
6719: @menu
6720: * Format: Outline Format. What the text of an outline looks like.
6721: * Motion: Outline Motion. Special commands for moving through outlines.
6722: * Visibility: Outline Visibility. Commands to control what is visible.
6723: @end menu
6724:
6725: @node Outline Format,Outline Motion,Outline Mode, Outline Mode
6726: @subsubsection Format of Outlines
6727:
6728: @cindex heading lines (Outline mode)
6729: @cindex body lines (Outline mode)
6730: Outline mode assumes that the lines in the buffer are of two types:
6731: @dfn{heading lines} and @dfn{body lines}. A heading line represents a topic in the
6732: outline. Heading lines start with one or more stars; the number of stars
6733: determines the depth of the heading in the outline structure. Thus, a
6734: heading line with one star is a major topic; all the heading lines with
6735: two stars between it and the next one-star heading are its subtopics; and
6736: so on. Any line that is not a heading line is a body line. Body lines
6737: belong to the preceding heading line. Here is an example:
6738:
6739: @example
6740: * Food
6741:
6742: This is the body,
6743: which says something about the topic of food.
6744:
6745: ** Delicious Food
6746:
6747: This is the body of the second-level header.
6748:
6749: ** Distasteful Food
6750:
6751: This could have
6752: a body too, with
6753: several lines.
6754:
6755: *** Dormitory Food
6756:
6757: * Shelter
6758:
6759: A second first-level topic with its header line.
6760: @end example
6761:
6762: A heading line together with all following body lines is called
6763: collectively an @dfn{entry}. A heading line together with all following
6764: deeper heading lines and their body lines is called a @dfn{subtree}.
6765:
6766: @vindex outline-regexp
6767: You can customize the criterion for distinguishing heading lines
6768: by setting the variable @code{outline-regexp}. Any line whose
6769: beginning has a match for this regexp is considered a heading line.
6770: Matches that start within a line (not at the beginning) do not count.
6771: The length of the matching text determines the level of the heading;
6772: longer matches make a more deeply nested level. Thus, for example,
6773: if a text formatter has commands @samp{@@chapter}, @samp{@@section}
6774: and @samp{@@subsection} to divide the document into chapters and
6775: sections, you could make those lines count as heading lines by
6776: setting @code{outline-regexp} to @samp{"@@chap\\|@@\$sub\$*section"}.
6777: Note the trick: the two words @samp{chapter} and @samp{section} are equally
6778: long, but by defining the regexp to match only @samp{chap} we ensure
6779: that the length of the text matched on a chapter heading is shorter,
6780: so that Outline mode will know that sections are contained in chapters.
6781: This works as long as no other command starts with @samp{@@chap}.
6782:
6783: Outline mode makes a line invisible by changing the newline before it
6784: into an ASCII Control-M (code 015). Most editing commands that work on
6785: lines treat an invisible line as part of the previous line because,
6786: strictly speaking, it @i{is} part of that line, since there is no longer a
6787: newline in between. When you save the file in Outline mode, Control-M
6788: characters are saved as newlines, so the invisible lines become ordinary
6789: lines in the file. But saving does not change the visibility status of a
6790: line inside Emacs.
6791:
6792: @node Outline Motion,Outline Visibility,Outline Format,Outline Mode
6793: @subsubsection Outline Motion Commands
6794:
6795: There are some special motion commands in Outline mode that move
6796: backward and forward to heading lines.
6797:
6798: @table @kbd
6799: @item C-c C-n
6800: Move point to the next visible heading line
6801: (@code{outline-next-visible-heading}).
6802: @item C-c C-p
6803: Move point to the previous visible heading line @*
6804: (@code{outline-previous-visible-heading}).
6805: @item C-c C-f
6806: Move point to the next visible heading line at the same level
6807: as the one point is on (@code{outline-forward-same-level}).
6808: @item C-c C-b
6809: Move point to the previous visible heading line at the same level
6810: (@code{outline-backward-same-level}).
6811: @item C-c C-u
6812: Move point up to a lower-level (more inclusive) visible heading line
6813: (@code{outline-up-heading}).
6814: @end table
6815:
6816: @findex outline-next-visible-heading
6817: @findex outline-previous-visible-heading
6818: @kindex C-c C-n (Outline mode)
6819: @kindex C-c C-p (Outline mode)
6820: @kbd{C-c C-n} (@code{next-visible-heading}) moves down to the next
6821: heading line. @kbd{C-c C-p} (@code{previous-visible-heading}) moves
6822: similarly backward. Both accept numeric arguments as repeat counts. The
6823: names emphasize that invisible headings are skipped, but this is not really
6824: a special feature. All editing commands that look for lines ignore the
6825: invisible lines automatically.@refill
6826:
6827: @findex outline-up-heading
6828: @findex outline-forward-same-level
6829: @findex outline-backward-same-level
6830: @kindex C-c C-f (Outline mode)
6831: @kindex C-c C-b (Outline mode)
6832: @kindex C-c C-u (Outline mode)
6833: More advanced motion commands understand the levels of headings.
6834: @kbd{C-c C-f} (@code{outline-forward-same-level}) and
6835: @kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
6836: heading line to another visible heading at the same depth in
6837: the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves
6838: backward to another heading that is less deeply nested.
6839:
6840: @node Outline Visibility,,Outline Motion,Outline Mode
6841: @subsubsection Outline Visibility Commands
6842:
6843: The other special commands of outline mode are used to make lines visible
6844: or invisible. Their names all start with @code{hide} or @code{show}.
6845: Most of them fall into pairs of opposites. They are not undoable; instead,
6846: you can undo right past them. Making lines visible or invisible is simply
6847: not recorded by the undo mechanism.
6848:
6849: @table @kbd
6850: @item M-x hide-body
6851: Make all body lines in the buffer invisible.
6852: @item M-x show-all
6853: Make all lines in the buffer visible.
6854: @item C-c C-h
6855: Make everything under this heading invisible, not including this
6856: heading itself@* (@code{hide-subtree}).
6857: @item C-c C-s
6858: Make everything under this heading visible, including body,
6859: subheadings, and their bodies (@code{show-subtree}).
6860: @item M-x hide-leaves
6861: Make the body of this heading line, and of all its subheadings,
6862: invisible.
6863: @item M-x show-branches
6864: Make all subheadings of this heading line, at all levels, visible.
6865: @item C-c C-i
6866: Make immediate subheadings (one level down) of this heading line
6867: visible (@code{show-children}).
6868: @item M-x hide-entry
6869: Make this heading line's body invisible.
6870: @item M-x show-entry
6871: Make this heading line's body visible.
6872: @end table
6873:
6874: @findex hide-entry
6875: @findex show-entry
6876: Two commands that are exact opposites are @kbd{M-x hide-entry} and
6877: @kbd{M-x show-entry}. They are used with point on a heading line, and
6878: apply only to the body lines of that heading. The subtopics and their
6879: bodies are not affected.
6880:
6881: @findex hide-subtree
6882: @findex show-subtree
6883: @kindex C-c C-s (Outline mode)
6884: @kindex C-c C-h (Outline mode)
6885: @cindex subtree (Outline mode)
6886: Two more powerful opposites are @kbd{C-c C-h} (@code{hide-subtree}) and
6887: @kbd{C-c C-s} (@code{show-subtree}). Both expect to be used when point is
6888: on a heading line, and both apply to all the lines of that heading's
6889: @dfn{subtree}: its body, all its subheadings, both direct and indirect, and
6890: all of their bodies. In other words, the subtree contains everything
6891: following this heading line, up to and not including the next heading of
6892: the same or higher rank.@refill
6893:
6894: @findex hide-leaves
6895: @findex show-branches
6896: Intermediate between a visible subtree and an invisible one is having
6897: all the subheadings visible but none of the body. There are two commands
6898: for doing this, depending on whether you want to hide the bodies or
6899: make the subheadings visible. They are @kbd{M-x hide-leaves} and
6900: @kbd{M-x show-branches}.
6901:
6902: @kindex C-c C-i (Outline mode)
6903: @findex show-children
6904: A little weaker than @code{show-branches} is @kbd{C-c C-i}
6905: (@code{show-children}). It makes just the direct subheadings
6906: visible---those one level down. Deeper subheadings remain invisible, if
6907: they were invisible.@refill
6908:
6909: @findex hide-body
6910: @findex show-all
6911: Two commands have a blanket effect on the whole file. @kbd{M-x hide-body}
6912: makes all body lines invisible, so that you see just the outline structure.
6913: @kbd{M-x show-all} makes all lines visible. These commands can be thought
6914: of as a pair of opposites even though @kbd{M-x show-all} applies to more
6915: than just body lines.
6916:
6917: @vindex selective-display-ellipses
6918: The use of ellipses at the ends of visible lines can be turned off
6919: by setting @code{selective-display-ellipses} to @code{nil}. Then there
6920: is no visible indication of the presence of invisible lines.
6921:
6922: @node Words, Sentences, Text Mode, Text
6923: @section Words
6924: @cindex words
6925: @cindex Meta
6926:
6927: Emacs has commands for moving over or operating on words. By convention,
6928: the keys for them are all @kbd{Meta-} characters.
6929:
6930: @c widecommands
6931: @table @kbd
6932: @item M-f
6933: Move forward over a word (@code{forward-word}).
6934: @item M-b
6935: Move backward over a word (@code{backward-word}).
6936: @item M-d
6937: Kill up to the end of a word (@code{kill-word}).
6938: @item M-@key{DEL}
6939: Kill back to the beginning of a word (@code{backward-kill-word}).
6940: @item M-@@
6941: Mark the end of the next word (@code{mark-word}).
6942: @item M-t
6943: Transpose two words; drag a word forward
6944: or backward across other words (@code{transpose-words}).
6945: @end table
6946:
6947: Notice how these keys form a series that parallels the
6948: character-based @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @kbd{C-t} and
6949: @key{DEL}. @kbd{M-@@} is related to @kbd{C-@@}, which is an alias for
6950: @kbd{C-@key{SPC}}.@refill
6951:
6952: @kindex M-f
6953: @kindex M-b
6954: @findex forward-word
6955: @findex backward-word
6956: The commands @kbd{Meta-f} (@code{forward-word}) and @kbd{Meta-b}
6957: (@code{backward-word}) move forward and backward over words. They are thus
6958: analogous to @kbd{Control-f} and @kbd{Control-b}, which move over single
6959: characters. Like their @kbd{Control-} analogues, @kbd{Meta-f} and
6960: @kbd{Meta-b} move several words if given an argument. @kbd{Meta-f} with a
6961: negative argument moves backward, and @kbd{Meta-b} with a negative argument
6962: moves forward. Forward motion stops right after the last letter of the
6963: word, while backward motion stops right before the first letter.@refill
6964:
6965: @kindex M-d
6966: @findex kill-word
6967: @kbd{Meta-d} (@code{kill-word}) kills the word after point. To be
6968: precise, it kills everything from point to the place @kbd{Meta-f} would
6969: move to. Thus, if point is in the middle of a word, @kbd{Meta-d} kills
6970: just the part after point. If some punctuation comes between point and the
6971: next word, it is killed along with the word. (If you wish to kill only the
6972: next word but not the punctuation before it, simply do @kbd{Meta-f} to get
6973: the end, and kill the word backwards with @kbd{Meta-@key{DEL}}.)
6974: @kbd{Meta-d} takes arguments just like @kbd{Meta-f}.
6975:
6976: @findex backward-kill-word
6977: @kindex M-DEL
6978: @kbd{Meta-@key{DEL}} (@code{backward-kill-word}) kills the word before
6979: point. It kills everything from point back to where @kbd{Meta-b} would
6980: move to. If point is after the space in @w{@samp{FOO, BAR}}, then
6981: @w{@samp{FOO, }} is killed. (If you wish to kill just @samp{FOO}, do
6982: @kbd{Meta-b Meta-d} instead of @kbd{Meta-@key{DEL}}.)
6983:
6984: @cindex transposition
6985: @kindex M-t
6986: @findex transpose-words
6987: @kbd{Meta-t} (@code{transpose-words}) exchanges the word before or
6988: containing point with the following word. The delimiter characters between
6989: the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
6990: @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
6991: more on transposition and on arguments to transposition commands.
6992:
6993: @kindex M-@@
6994: @findex mark-word
6995: To operate on the next @var{n} words with an operation which applies
6996: between point and mark, you can either set the mark at point and then move
6997: over the words, or you can use the command @kbd{Meta-@@} (@code{mark-word})
6998: which does not move point, but sets the mark where @kbd{Meta-f} would move
6999: to. It can be given arguments just like @kbd{Meta-f}.
7000:
7001: @cindex syntax table
7002: The word commands' understanding of syntax is completely controlled by
7003: the syntax table. Any character can, for example, be declared to be a word
7004: delimiter. @xref{Syntax}.
7005:
7006: @node Sentences, Paragraphs, Words, Text
7007: @section Sentences
7008: @cindex sentences
7009:
7010: The Emacs commands for manipulating sentences and paragraphs are mostly
7011: on @kbd{Meta-} keys, so as to be like the word-handling commands.
7012:
7013: @table @kbd
7014: @item M-a
7015: Move back to the beginning of the sentence (@code{backward-sentence}).
7016: @item M-e
7017: Move forward to the end of the sentence (@code{forward-sentence}).
7018: @item M-k
7019: Kill forward to the end of the sentence (@code{kill-sentence}).
7020: @item C-x @key{DEL}
7021: Kill back to the beginning of the sentence @*(@code{backward-kill-sentence}).
7022: @end table
7023:
7024: @kindex M-a
7025: @kindex M-e
7026: @findex backward-sentence
7027: @findex forward-sentence
7028: The commands @kbd{Meta-a} and @kbd{Meta-e} (@code{backward-sentence} and
7029: @code{forward-sentence}) move to the beginning and end of the current
7030: sentence, respectively. They were chosen to resemble @kbd{Control-a} and
7031: @kbd{Control-e}, which move to the beginning and end of a line. Unlike
7032: them, @kbd{Meta-a} and @kbd{Meta-e} if repeated or given numeric arguments
7033: move over successive sentences. Emacs assumes that the typist's convention
7034: is followed, and thus considers a sentence to end wherever there is a
7035: @samp{.}, @samp{?} or @samp{!} followed by the end of a line or two spaces,
7036: with any number of @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters
7037: allowed in between. A sentence also begins or ends wherever a paragraph
7038: begins or ends.@refill
7039:
7040: Neither @kbd{M-a} nor @kbd{M-e} moves past the newline or spaces beyond
7041: the sentence edge at which it is stopping.
7042:
7043: @kindex M-k
7044: @kindex C-x DEL
7045: @findex kill-sentence
7046: @findex backward-kill-sentence
7047: Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
7048: with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
7049: @kbd{M-k} (@code{kill-sentence}) which kills from point to the end of the
7050: sentence. With minus one as an argument it kills back to the beginning of
7051: the sentence. Larger arguments serve as a repeat count.@refill
7052:
7053: There is a special command, @kbd{C-x @key{DEL}}
7054: (@code{backward-kill-sentence}) for killing back to the beginning of a
7055: sentence, because this is useful when you change your mind in the middle of
7056: composing text.@refill
7057:
7058: @vindex sentence-end
7059: The variable @code{sentence-end} controls recognition of the end of a
7060: sentence. It is a regexp that matches the last few characters of a
7061: sentence, together with the whitespace following the sentence. Its
7062: normal value is
7063:
7064: @example
7065: "[.?!][]\"')]*\$$\\|\t\\| \$[ \t\n]*"
7066: @end example
7067:
7068: @noindent
7069: This example is explained in the section on regexps. @xref{Regexps}.
7070:
7071: @node Paragraphs, Pages, Sentences, Text
7072: @section Paragraphs
7073: @cindex paragraphs
7074: @kindex M-[
7075: @kindex M-]
7076: @findex backward-paragraph
7077: @findex forward-paragraph
7078:
7079: The Emacs commands for manipulating paragraphs are also @kbd{Meta-}
7080: keys.
7081:
7082: @table @kbd
7083: @item M-[
7084: Move back to previous paragraph beginning @*(@code{backward-paragraph}).
7085: @item M-]
7086: Move forward to next paragraph end (@code{forward-paragraph}).
7087: @item M-h
7088: Put point and mark around this or next paragraph (@code{mark-paragraph}).
7089: @end table
7090:
7091: @kbd{Meta-[} moves to the beginning of the current or previous paragraph,
7092: while @kbd{Meta-]} moves to the end of the current or next paragraph.
7093: Blank lines and text formatter command lines separate paragraphs and are
7094: not part of any paragraph. Also, an indented line starts a new
7095: paragraph.
7096:
7097: In major modes for programs (as opposed to Text mode), paragraphs begin
7098: and end only at blank lines. This makes the paragraph commands continue to
7099: be useful even though there are no paragraphs per se.
7100:
7101: When there is a fill prefix, then paragraphs are delimited by all lines
7102: which don't start with the fill prefix. @xref{Filling}.
7103:
7104: @kindex M-h
7105: @findex mark-paragraph
7106: When you wish to operate on a paragraph, you can use the command
7107: @kbd{Meta-h} (@code{mark-paragraph}) to set the region around it. This
7108: command puts point at the beginning and mark at the end of the paragraph
7109: point was in. If point is between paragraphs (in a run of blank lines, or
7110: at a boundary), the paragraph following point is surrounded by point and
7111: mark. If there are blank lines preceding the first line of the paragraph,
7112: one of these blank lines is included in the region. Thus, for example,
7113: @kbd{M-h C-w} kills the paragraph around or after point.
7114:
7115: @vindex paragraph-start
7116: @vindex paragraph-separate
7117: The precise definition of a paragraph boundary is controlled by the
7118: variables @code{paragraph-separate} and @code{paragraph-start}. The value
7119: of @code{paragraph-start} is a regexp that should match any line that
7120: either starts or separates paragraphs. The value of
7121: @code{paragraph-separate} is another regexp that should match only lines
7122: that separate paragraphs without being part of any paragraph. Lines that
7123: start a new paragraph and are contained in it must match both regexps. For
7124: example, normally @code{paragraph-start} is @code{"^[ @t{\}t@t{\}n@t{\}f]"}
7125: and @code{paragraph-separate} is @code{"^[ @t{\}t@t{\}f]*$"}.@refill
7126:
7127: Normally it is desirable for page boundaries to separate paragraphs.
7128: The default values of these variables recognize the usual separator for
7129: pages.
7130:
7131: @node Pages, Filling, Paragraphs, Text
7132: @section Pages
7133:
7134: @cindex pages
7135: @cindex formfeed
7136: Files are often thought of as divided into @dfn{pages} by the
7137: @dfn{formfeed} character (ASCII Control-L, octal code 014). For example,
7138: if a file is printed on a line printer, each page of the file, in this
7139: sense, will start on a new page of paper. Emacs treats a page-separator
7140: character just like any other character. It can be inserted with @kbd{C-q
7141: C-l}, or deleted with @key{DEL}. Thus, you are free to paginate your file
7142: or not. However, since pages are often meaningful divisions of the file,
7143: commands are provided to move over them and operate on them.
7144:
7145: @c WideCommands
7146: @table @kbd
7147: @item C-x [
7148: Move point to previous page boundary (@code{backward-page}).
7149: @item C-x ]
7150: Move point to next page boundary (@code{forward-page}).
7151: @item C-x C-p
7152: Put point and mark around this page (or another page) (@code{mark-page}).
7153: @item C-x l
7154: Count the lines in this page (@code{count-lines-page}).
7155: @end table
7156:
7157: @kindex C-x [
7158: @kindex C-x ]
7159: @findex forward-page
7160: @findex backward-page
7161: The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
7162: after the previous page delimiter. If point is already right after a page
7163: delimiter, it skips that one and stops at the previous one. A numeric
7164: argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
7165: command moves forward past the next page delimiter.
7166:
7167: @kindex C-x C-p
7168: @findex mark-page
7169: The @kbd{C-x C-p} command (@code{mark-page}) puts point at the beginning
7170: of the current page and the mark at the end. The page delimiter at the end
7171: is included (the mark follows it). The page delimiter at the front is
7172: excluded (point follows it). This command can be followed by @kbd{C-w} to
7173: kill a page which is to be moved elsewhere. If it is inserted after a page
7174: delimiter, at a place where @kbd{C-x ]} or @kbd{C-x [} would take you, then
7175: the page will be properly delimited before and after once again.
7176:
7177: A numeric argument to @kbd{C-x C-p} is used to specify which page to go
7178: to, relative to the current one. Zero means the current page. One means
7179: the next page, and @minus{}1 means the previous one.
7180:
7181: @kindex C-x l
7182: @findex count-lines-page
7183: The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
7184: where to break a page in two. It prints in the echo area the total number
7185: of lines in the current page, and then divides it up into those preceding
7186: the current line and those following, as in
7187:
7188: @example
7189: Page has 96 (72+25) lines
7190: @end example
7191:
7192: @noindent
7193: Notice that the sum is off by one; this is correct if point is not at the
7194: beginning of a line.
7195:
7196: @vindex page-delimiter
7197: The variable @code{page-delimiter} should have as its value a regexp that
7198: matches the beginning of a line that separates pages. This is what defines
7199: where pages begin. The normal value of this variable is @code{"^@t{\}f"},
7200: which matches a formfeed character at the beginning of a line.
7201:
7202: @node Filling, Case, Pages, Text
7203: @section Filling Text
7204: @cindex filling
7205:
7206: With Auto Fill mode, text can be @dfn{filled} (broken up into lines that
7207: fit in a specified width) as you insert it. If you alter existing text it
7208: may no longer be properly filled; then explicit commands for filling can be
7209: used.
7210:
7211: @menu
7212: * Auto Fill:: Auto Fill mode breaks long lines automatically.
7213: * Fill Commands:: Commands to refill paragraphs and center lines.
7214: * Fill Prefix:: Filling when every line is indented or in a comment, etc.
7215: @end menu
7216:
7217: @node Auto Fill, Fill Commands, Filling, Filling
7218: @subsection Auto Fill Mode
7219:
7220: @cindex Auto Fill mode
7221:
7222: @dfn{Auto Fill} mode is a minor mode in which lines are broken
7223: automatically when they become too wide. Breaking happens only when
7224: you type a @key{SPC} or @key{RET}.
7225:
7226: @table @kbd
7227: @item M-x auto-fill-mode
7228: Enable or disable Auto Fill mode.
7229: @item @key{SPC}
7230: @itemx @key{RET}
7231: In Auto Fill mode, break lines when appropriate.
7232: @end table
7233:
7234: @findex auto-fill-mode
7235: @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off if
7236: it was on. With a positive numeric argument it always turns Auto Fill mode
7237: on, and with a negative argument always turns it off. You can see when
7238: Auto Fill mode is in effect by the presence of the word @samp{Fill} in the
7239: mode line, inside the parentheses. Auto Fill mode is a minor mode, turned
7240: on or off for each buffer individually. @xref{Minor Modes}.
7241:
7242: In Auto Fill mode, lines are broken automatically at spaces when they get
7243: longer than the desired width. Line breaking and rearrangement takes place
7244: only when you type @key{SPC} or @key{RET}. If you wish to insert a space
7245: or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} or
7246: @kbd{C-q @key{LFD}} (recall that a newline is really a linefeed). Also,
7247: @kbd{C-o} inserts a newline without line breaking.
7248:
7249: Auto Fill mode works well with Lisp mode, because when it makes a new
7250: line in Lisp mode it indents that line with @key{TAB}. If a line ending in
7251: a comment gets too long, the text of the comment is split into two
7252: comment lines. Optionally new comment delimiters are inserted at the end of
7253: the first line and the beginning of the second so that each line is
7254: a separate comment; the variable @code{comment-multi-line} controls the
7255: choice (@pxref{Comments}).
7256:
7257: Auto Fill mode does not refill entire paragraphs. It can break lines but
7258: cannot merge lines. So editing in the middle of a paragraph can result in
7259: a paragraph that is not correctly filled. The easiest way to make the
7260: paragraph properly filled again is usually with the explicit fill commands.
7261:
7262: Many users like Auto Fill mode and want to use it in all text files.
7263: The section on init files says how to arrange this permanently for yourself.
7264: @xref{Init File}.
7265:
7266: @node Fill Commands, Fill Prefix, Auto Fill, Filling
7267: @subsection Explicit Fill Commands
7268:
7269: @table @kbd
7270: @item M-q
7271: Fill current paragraph (@code{fill-paragraph}).
7272: @item M-g
7273: Fill each paragraph in the region (@code{fill-region}).
7274: @item C-x f
7275: Set the fill column (@code{set-fill-column}).
7276: @item M-x fill-region-as-paragraph.
7277: Fill the region, considering it as one paragraph.
7278: @item M-s
7279: Center a line.
7280: @end table
7281:
7282: @kindex M-q
7283: @findex fill-paragraph
7284: To refill a paragraph, use the command @kbd{Meta-q}
7285: (@code{fill-paragraph}). It causes the paragraph that point is inside, or
7286: the one after point if point is between paragraphs, to be refilled. All
7287: the line-breaks are removed, and then new ones are inserted where
7288: necessary. @kbd{M-q} can be undone with @kbd{C-_}. @xref{Undo}.@refill
7289:
7290: @kindex M-g
7291: @findex fill-region
7292: To refill many paragraphs, use @kbd{M-g} (@code{fill-region}), which
7293: divides the region into paragraphs and fills each of them.
7294:
7295: @findex fill-region-as-paragraph
7296: @kbd{Meta-q} and @kbd{Meta-g} use the same criteria as @kbd{Meta-h} for
7297: finding paragraph boundaries (@pxref{Paragraphs}). For more control, you
7298: can use @kbd{M-x fill-region-as-paragraph}, which refills everything
7299: between point and mark. This command recognizes only blank lines as
7300: paragraph separators.@refill
7301:
7302: @cindex justification
7303: A numeric argument to @kbd{M-g} or @kbd{M-q} causes it to @dfn{justify}
7304: the text as well as filling it. This means that extra spaces are inserted
7305: to make the right margin line up exactly at the fill column. To remove the
7306: extra spaces, use @kbd{M-q} or @kbd{M-g} with no argument.@refill
7307:
7308: @kindex M-s
7309: @cindex centering
7310: @findex center-line
7311: The command @kbd{Meta-s} (@code{center-line}) centers the current line
7312: within the current fill column. With an argument, it centers several lines
7313: individually and moves past them.
7314:
7315: @vindex fill-column
7316: The maximum line width for filling is in the variable @code{fill-column}.
7317: Altering the value of @code{fill-column} makes it local to the current
7318: buffer; until that time, the default value is in effect. The default is
7319: initially 70. @xref{Locals}.
7320:
7321: @kindex C-x f
7322: @findex set-fill-column
7323: The easiest way to set @code{fill-column} is to use the command @kbd{C-x
7324: f} (@code{set-fill-column}). With no argument, it sets @code{fill-column}
7325: to the current horizontal position of point. With a numeric argument, it
7326: uses that as the new fill column.
7327:
7328: @node Fill Prefix,, Fill Commands, Filling
7329: @subsection The Fill Prefix
7330:
7331: @cindex fill prefix
7332: To fill a paragraph in which each line starts with a special marker
7333: (which might be a few spaces, giving an indented paragraph), use the
7334: @dfn{fill prefix} feature. The fill prefix is a string which Emacs expects
7335: every line to start with, and which is not included in filling.
7336:
7337: @table @kbd
7338: @item C-x .
7339: Set the fill prefix (@code{set-fill-prefix}).
7340: @item M-q
7341: Fill a paragraph using current fill prefix (@code{fill-paragraph}).
7342: @item M-x fill-individual-paragraphs
7343: Fill the region, considering each change of indentation as starting a
7344: new paragraph.
7345: @end table
7346:
7347: @kindex C-x .
7348: @findex set-fill-prefix
7349: To specify a fill prefix, move to a line that starts with the desired
7350: prefix, put point at the end of the prefix, and give the command
7351: @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). That's a period after the
7352: @kbd{C-x}. To turn off the fill prefix, specify an empty prefix: type
7353: @w{@kbd{C-x .}}@: with point at the beginning of a line.@refill
7354:
7355: When a fill prefix is in effect, the fill commands remove the fill prefix
7356: from each line before filling and insert it on each line after filling.
7357: The fill prefix is also inserted on new lines made automatically by Auto
7358: Fill mode. Lines that do not start with the fill prefix are considered to
7359: start paragraphs, both in @kbd{M-q} and the paragraph commands; this is
7360: just right if you are using paragraphs with hanging indentation (every line
7361: indented except the first one). Lines which are blank or indented once the
7362: prefix is removed also separate or start paragraphs; this is what you want
7363: if you are writing multi-paragraph comments with a comment delimiter on
7364: each line.
7365:
7366: @vindex fill-prefix
7367: The fill prefix is stored in the variable @code{fill-prefix}. Its value
7368: is a string, or @code{nil} when there is no fill prefix. This is a
7369: per-buffer variable; altering the variable affects only the current buffer,
7370: but there is a default value which you can change as well. @xref{Locals}.
7371:
7372: @findex fill-individual-paragraphs
7373: Another way to use fill prefixes is through @kbd{M-x
7374: fill-individual-paragraphs}. This function divides the region into groups
7375: of consecutive lines with the same amount and kind of indentation and fills
7376: each group as a paragraph using its indentation as a fill prefix.
7377:
7378: @node Case,, Filling, Text
7379: @section Case Conversion Commands
7380: @cindex case conversion
7381:
7382: Emacs has commands for converting either a single word or any arbitrary
7383: range of text to upper case or to lower case.
7384:
7385: @c WideCommands
7386: @table @kbd
7387: @item M-l
7388: Convert following word to lower case (@code{downcase-word}).
7389: @item M-u
7390: Convert following word to upper case (@code{upcase-word}).
7391: @item M-c
7392: Capitalize the following word (@code{capitalize-word}).
7393: @item C-x C-l
7394: Convert region to lower case (@code{downcase-region}).
7395: @item C-x C-u
7396: Convert region to upper case (@code{upcase-region}).
7397: @end table
7398:
7399: @kindex M-l
7400: @kindex M-u
7401: @kindex M-c
7402: @cindex words
7403: @findex downcase-word
7404: @findex upcase-word
7405: @findex capitalize-word
7406: The word conversion commands are the most useful. @kbd{Meta-l}
7407: (@code{downcase-word}) converts the word after point to lower case, moving
7408: past it. Thus, repeating @kbd{Meta-l} converts successive words.
7409: @kbd{Meta-u} (@code{upcase-word}) converts to all capitals instead, while
7410: @kbd{Meta-c} (@code{capitalize-word}) puts the first letter of the word
7411: into upper case and the rest into lower case. All these commands convert
7412: several words at once if given an argument. They are especially convenient
7413: for converting a large amount of text from all upper case to mixed case,
7414: because you can move through the text using @kbd{M-l}, @kbd{M-u} or
7415: @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
7416: to skip a word.
7417:
7418: When given a negative argument, the word case conversion commands apply
7419: to the appropriate number of words before point, but do not move point.
7420: This is convenient when you have just typed a word in the wrong case: you
7421: can give the case conversion command and continue typing.
7422:
7423: If a word case conversion command is given in the middle of a word, it
7424: applies only to the part of the word which follows point. This is just
7425: like what @kbd{Meta-d} (@code{kill-word}) does. With a negative argument,
7426: case conversion applies only to the part of the word before point.
7427:
7428: @kindex C-x C-l
7429: @kindex C-x C-u
7430: @cindex region
7431: @findex downcase-region
7432: @findex upcase-region
7433: The other case conversion commands are @kbd{C-x C-u}
7434: (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
7435: convert everything between point and mark to the specified case. Point and
7436: mark do not move.@refill
7437:
7438: @node Programs, Running, Text, Top
7439: @chapter Editing Programs
7440: @cindex Lisp
7441: @cindex C
7442:
7443: Emacs has many commands designed to understand the syntax of programming
7444: languages such as Lisp and C. These commands can
7445:
7446: @itemize @bullet
7447: @item
7448: Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
7449: @item
7450: Move over or mark top-level balanced expressions (@dfn{defuns}, in Lisp;
7451: functions, in C).
7452: @item
7453: Show how parentheses balance (@pxref{Matching}).
7454: @item
7455: Insert, kill or align comments (@pxref{Comments}).
7456: @item
7457: Follow the usual indentation conventions of the language
7458: (@pxref{Grinding}).
7459: @end itemize
7460:
7461: The commands for words, sentences and paragraphs are very useful in
7462: editing code even though their canonical application is for editing human
7463: language text. Most symbols contain words (@pxref{Words}); sentences can
7464: be found in strings and comments (@pxref{Sentences}). Paragraphs per se
7465: are not present in code, but the paragraph commands are useful anyway,
7466: because Lisp mode and C mode define paragraphs to begin and end at blank
7467: lines (@pxref{Paragraphs}). Judicious use of blank lines to make the
7468: program clearer will also provide interesting chunks of text for the
7469: paragraph commands to work on.
7470:
7471: The selective display feature is useful for looking at the overall
7472: structure of a function (@pxref{Selective Display}). This feature causes
7473: only the lines that are indented less than a specified amount to appear
7474: on the screen.
7475:
7476: @menu
7477: * Program Modes:: Major modes for editing programs.
7478: * Lists:: Expressions with balanced parentheses.
7479: There are editing commands to operate on them.
7480: * Defuns:: Each program is made up of separate functions.
7481: There are editing commands to operate on them.
7482: * Grinding:: Adjusting indentation to show the nesting.
7483: * Matching:: Insertion of a close-delimiter flashes matching open.
7484: * Comments:: Inserting, illing and aligning comments.
7485: * Balanced Editing:: Inserting two matching parentheses at once, etc.
7486: * Lisp Completion:: Completion on symbol names in Lisp code.
7487: * Documentation:: Getting documentation of functions you plan to call.
7488: * Change Log:: Maintaining a change history for your program.
7489: * Tags:: Go direct to any function in your program in one
7490: command. Tags remembers which file it is in.
7491: * Fortran:: Fortran mode and its special features.
7492: @end menu
7493:
7494: @node Program Modes, Lists, Programs, Programs
7495: @section Major Modes for Programming Languages
7496:
7497: @cindex Lisp mode
7498: @cindex C mode
7499: @cindex Scheme mode
7500: Emacs also has major modes for the programming languages Lisp, Scheme (a
7501: variant of Lisp), C, Fortran and Muddle. Ideally, a major mode should be
7502: implemented for each programming language that you might want to edit with
7503: Emacs; but often the mode for one language can serve for other
7504: syntactically similar languages. The language modes that exist are those
7505: that someone decided to take the trouble to write.
7506:
7507: There are several forms of Lisp mode, which differ in the way they
7508: interface to Lisp execution. @xref{Lisp Modes}.
7509:
7510: Each of the programming language modes defines the @key{TAB} key to run
7511: an indentation function that knows the indentation conventions of that
7512: language and updates the current line's indentation accordingly. For
7513: example, in C mode @key{TAB} is bound to @code{c-indent-line}. @key{LFD}
7514: is normally defined to do @key{RET} followed by @key{TAB}; thus, it too
7515: indents in a mode-specific fashion.
7516:
7517: @kindex DEL
7518: @findex backward-delete-char-untabify
7519: In most programming languages, indentation is likely to vary from line to
7520: line. So the major modes for those languages rebind @key{DEL} to treat a
7521: tab as if it were the equivalent number of spaces (using the command
7522: @code{backward-delete-char-untabify}). This makes it possible to rub out
7523: indentation one column at a time without worrying whether it is made up of
7524: spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point,
7525: in these modes.
7526:
7527: Programming language modes define paragraphs to be separated only by
7528: blank lines, so that the paragraph commands remain useful. Auto Fill mode,
7529: if enabled in a programming language major mode, indents the new lines
7530: which it creates.
7531:
7532: @cindex mode hook
7533: @vindex c-mode-hook
7534: @vindex lisp-mode-hook
7535: @vindex emacs-lisp-mode-hook
7536: @vindex lisp-interaction-mode-hook
7537: @vindex scheme-mode-hook
7538: @vindex muddle-mode-hook
7539: Turning on a major mode calls a user-supplied function called the
7540: @dfn{mode hook}, which is the value of a Lisp variable. For example,
7541: turning on C mode calls the value of the variable @code{c-mode-hook} if
7542: that value exists and is non-@code{nil}. Mode hook variables for other
7543: programming language modes include @code{lisp-mode-hook},
7544: @code{emacs-lisp-mode-hook}, @code{lisp-interaction-mode-hook},
7545: @code{scheme-mode-hook} and @code{muddle-mode-hook}. The mode hook
7546: function receives no arguments.@refill
7547:
7548: @node Lists, Defuns, Program Modes, Programs
7549: @section Lists and Sexps
7550:
7551: @cindex Control-Meta
7552: By convention, Emacs keys for dealing with balanced expressions are
7553: usually @kbd{Control-Meta-} characters. They tend to be analogous in
7554: function to their @kbd{Control-} and @kbd{Meta-} equivalents. These commands
7555: are usually thought of as pertaining to expressions in programming
7556: languages, but can be useful with any language in which some sort of
7557: parentheses exist (including English).
7558:
7559: @cindex list
7560: @cindex sexp
7561: @cindex expression
7562: These commands fall into two classes. Some deal only with @dfn{lists}
7563: (parenthetical groupings). They see nothing except parentheses, brackets,
7564: braces (whichever ones must balance in the language you are working with),
7565: and escape characters that might be used to quote those.
7566:
7567: The other commands deal with expressions or @dfn{sexps}. The word `sexp'
7568: is derived from @dfn{s-expression}, the ancient term for an expression in
7569: Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It
7570: refers to an expression in whatever language your program is written in.
7571: Each programming language has its own major mode, which customizes the
7572: syntax tables so that expressions in that language count as sexps.
7573:
7574: Sexps typically include symbols, numbers, and string constants, as well
7575: as anything contained in parentheses, brackets or braces.
7576:
7577: In languages that use prefix and infix operators, such as C, it is not
7578: possible for all expressions to be sexps. For example, C mode does not
7579: recognize @samp{foo + bar} as a sexp, even though it @i{is} a C expression;
7580: it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
7581: @samp{+} as punctuation between them. This is a fundamental ambiguity:
7582: both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
7583: move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a
7584: sexp in C mode.
7585:
7586: Some languages have obscure forms of syntax for expressions that nobody
7587: has bothered to make Emacs understand properly.
7588:
7589: @c doublewidecommands
7590: @table @kbd
7591: @item C-M-f
7592: Move forward over a sexp (@code{forward-sexp}).
7593: @item C-M-b
7594: Move backward over a sexp (@code{backward-sexp}).
7595: @item C-M-k
7596: Kill sexp forward (@code{kill-sexp}).
7597: @item C-M-u
7598: Move up and backward in list structure (@code{backward-up-list}).
7599: @item C-M-d
7600: Move down and forward in list structure (@code{down-list}).
7601: @item C-M-n
7602: Move forward over a list (@code{forward-list}).
7603: @item C-M-p
7604: Move backward over a list (@code{backward-list}).
7605: @item C-M-t
7606: Transpose expressions (@code{transpose-sexps}).
7607: @item C-M-@@
7608: Put mark after following expression (@code{mark-sexp}).
7609: @end table
7610:
7611: @kindex C-M-f
7612: @kindex C-M-b
7613: @findex forward-sexp
7614: @findex backward-sexp
7615: To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If
7616: the first significant character after point is an opening delimiter
7617: (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
7618: moves past the matching closing delimiter. If the character begins a
7619: symbol, string, or number, @kbd{C-M-f} moves over that. If the character
7620: after point is a closing delimiter, @kbd{C-M-f} just moves past it. (This
7621: last is not really moving across a sexp; it is an exception which is
7622: included in the definition of @kbd{C-M-f} because it is as useful a
7623: behavior as anyone can think of for that situation.)@refill
7624:
7625: The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
7626: sexp. The detailed rules are like those above for @kbd{C-M-f}, but with
7627: directions reversed. If there are any prefix characters (singlequote,
7628: backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
7629: over them as well.
7630:
7631: @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
7632: specified number of times; with a negative argument, it moves in the
7633: opposite direction.
7634:
7635: The sexp commands move across comments as if they were whitespace, in
7636: languages such as C where the comment-terminator can be recognized. In
7637: Lisp, and other languages where comments run until the end of a line, it is
7638: very difficult to ignore comments when parsing backwards; therefore, in
7639: such languages the sexp commands treat the text of comments as if it were
7640: code.
7641:
7642: @kindex C-M-k
7643: @findex kill-sexp
7644: Killing a sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}).
7645: @kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over.
7646:
7647: @kindex C-M-n
7648: @kindex C-M-p
7649: @findex forward-list
7650: @findex backward-list
7651: The @dfn{list commands} move over lists like the sexp commands but skip
7652: blithely over any number of other kinds of sexps (symbols, strings, etc).
7653: They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
7654: (@code{backward-list}). The main reason they are useful is that they
7655: usually ignore comments (since the comments usually do not contain any
7656: lists).@refill
7657:
7658: @kindex C-M-u
7659: @kindex C-M-d
7660: @findex backward-up-list
7661: @findex down-list
7662: @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
7663: that's possible. To move @i{up} one (or @var{n}) levels, use @kbd{C-M-u}
7664: (@code{backward-up-list}).
7665: @kbd{C-M-u} moves backward up past one unmatched opening delimiter. A
7666: positive argument serves as a repeat count; a negative argument reverses
7667: direction of motion and also requests repetition, so it moves forward and
7668: up one or more levels.@refill
7669:
7670: To move @i{down} in list structure, use @kbd{C-M-d} (@code{down-list}). In Lisp mode,
7671: where @samp{(} is the only opening delimiter, this is nearly the same as
7672: searching for a @samp{(}. An argument specifies the number of levels
7673: of parentheses to go down.
7674:
7675: @cindex transposition
7676: @kindex C-M-t
7677: @findex transpose-sexps
7678: A somewhat random-sounding command which is nevertheless easy to use is
7679: @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp across
7680: the next one. An argument serves as a repeat count, and a negative
7681: argument drags backwards (thus canceling out the effect of @kbd{C-M-t} with
7682: a positive argument). An argument of zero, rather than doing nothing,
7683: transposes the sexps ending after point and the mark.
7684:
7685: @kindex C-M-@@
7686: @findex mark-sexp
7687: To make the region be the next sexp in the buffer, use @kbd{C-M-@@}
7688: (@code{mark-sexp}) which sets mark at the same place that @kbd{C-M-f} would
7689: move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In particular, a
7690: negative argument is useful for putting the mark at the beginning of the
7691: previous sexp.
7692:
7693: The list and sexp commands' understanding of syntax is completely
7694: controlled by the syntax table. Any character can, for example, be
7695: declared to be an opening delimiter and act like an open parenthesis.
7696: @xref{Syntax}.
7697:
7698: @node Defuns, Grinding, Lists, Programs
7699: @section Defuns
7700: @cindex defuns
7701:
7702: In Emacs, a parenthetical grouping at the top level in the buffer is
7703: called a @dfn{defun}. The name derives from the fact that most top-level
7704: lists in a Lisp file are instances of the special form @code{defun}, but
7705: any top-level parenthetical grouping counts as a defun in Emacs parlance
7706: regardless of what its contents are, and regardless of the programming
7707: language in use. For example, in C, the body of a function definition is a
7708: defun.
7709:
7710: @c doublewidecommands
7711: @table @kbd
7712: @item C-M-a
7713: Move to beginning of current or preceding defun
7714: (@code{beginning-of-defun}).
7715: @item C-M-e
7716: Move to end of current or following defun (@code{end-of-defun}).
7717: @item C-M-h
7718: Put region around whole current or following defun (@code{mark-defun}).
7719: @end table
7720:
7721: @kindex C-M-a
7722: @kindex C-M-e
7723: @kindex C-M-h
7724: @findex beginning-of-defun
7725: @findex end-of-defun
7726: @findex mark-defun
7727: The commands to move to the beginning and end of the current defun are
7728: @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
7729:
7730: If you wish to operate on the current defun, use @kbd{C-M-h}
7731: (@code{mark-defun}) which puts point at the beginning and mark at the end
7732: of the current or next defun. For example, this is the easiest way to get
7733: ready to move the defun to a different place in the text. In C mode,
7734: @kbd{C-M-h} runs the function @code{mark-c-function}, which is almost the
7735: same as @code{mark-defun}; the difference is that it backs up over the
7736: argument declarations, function name and returned data type so that the
7737: entire C function is inside the region.
7738:
7739: Emacs assumes that any open-parenthesis found in the leftmost column is
7740: the start of a defun. Therefore, @b{never put an open-parenthesis at the
7741: left margin in a Lisp file unless it is the start of a top level list.
7742: Never put an open-brace or other opening delimiter at the beginning of a
7743: line of C code unless it starts the body of a function.} The most likely
7744: problem case is when you want an opening delimiter at the start of a line
7745: inside a string. To avoid trouble, put an escape character (@samp{\}, in C
7746: and Emacs Lisp, @samp{/} in some other Lisp dialects) before the opening
7747: delimiter. It will not affect the contents of the string.
7748:
7749: In the remotest past, the original Emacs found defuns by moving upward a
7750: level of parentheses until there were no more levels to go up. This always
7751: required scanning all the way back to the beginning of the buffer, even for
7752: a small function. To speed up the operation, Emacs was changed to assume
7753: that any @samp{(} (or other character assigned the syntactic class of
7754: opening-delimiter) at the left margin is the start of a defun. This
7755: heuristic was nearly always right and avoided the costly scan; however,
7756: it mandated the convention described above.
7757:
7758: @node Grinding, Matching, Defuns, Programs
7759: @section Indentation for Programs
7760: @cindex indentation
7761: @cindex grinding
7762:
7763: The best way to keep a program properly indented (``ground'') is to use
7764: Emacs to re-indent it as you change it. Emacs has commands to indent
7765: properly either a single line, a specified number of lines, or all of the
7766: lines inside a single parenthetical grouping.
7767:
7768: @menu
7769: * Basic Indent::
7770: * Multi-line Indent:: Commands to reindent many lines at once.
7771: * Lisp Indent:: Specifying how each Lisp function should be indented.
7772: * C Indent:: Choosing an indentation style for C code.
7773: @end menu
7774:
7775: @node Basic Indent, Multi-line Indent, Grinding, Grinding
7776: @subsection Basic Program Indentation Commands
7777:
7778: @c WideCommands
7779: @table @kbd
7780: @item @key{TAB}
7781: Adjust indentation of current line.
7782: @item @key{LFD}
7783: Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
7784: @end table
7785:
7786: @kindex TAB
7787: @findex c-indent-line
7788: @findex lisp-indent-line
7789: The basic indentation command is @key{TAB}, which gives the current line
7790: the correct indentation as determined from the previous lines. The
7791: function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
7792: in Lisp mode, @code{c-indent-line} in C mode, etc. These functions
7793: understand different syntaxes for different languages, but they all do
7794: about the same thing. @key{TAB} in any programming language major mode
7795: inserts or deletes whitespace at the beginning of the current line,
7796: independent of where point is in the line. If point is inside the
7797: whitespace at the beginning of the line, @key{TAB} leaves it at the end of
7798: that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
7799: the characters around it.
7800:
7801: Use @kbd{C-q @key{TAB}} to insert a tab at point.
7802:
7803: @kindex LFD
7804: @findex newline-and-indent
7805: When entering a large amount of new code, use @key{LFD} (@code{newline-and-indent}),
7806: which is equivalent to a @key{RET} followed by a @key{TAB}. @key{LFD} creates
7807: a blank line, and then gives it the appropriate indentation.
7808:
7809: @key{TAB} indents the second and following lines of the body of an
7810: parenthetical grouping each under the preceding one; therefore, if you
7811: alter one line's indentation to be nonstandard, the lines below will tend
7812: to follow it. This is the right behavior in cases where the standard
7813: result of @key{TAB} is unaesthetic.
7814:
7815: Remember that an open-parenthesis, open-brace or other opening delimiter
7816: at the left margin is assumed by Emacs (including the indentation routines)
7817: to be the start of a function. Therefore, you must never have an opening
7818: delimiter in column zero that is not the beginning of a function, not even
7819: inside a string. This restriction is vital for making the indentation
7820: commands fast; you must simply accept it. @xref{Defuns}, for more
7821: information on this.
7822:
7823: @node Multi-line Indent, Lisp Indent, Basic Indent, Grinding
7824: @subsection Indenting Several Lines
7825:
7826: When you wish to re-indent several lines of code which have been altered
7827: or moved to a different level in the list structure, you have several
7828: commands available.
7829:
7830: @table @kbd
7831: @item C-M-q
7832: Re-indent all the lines within one list (@code{indent-sexp}).
7833: @item C-u @key{TAB}
7834: Shift an entire list rigidly sideways so that its first line
7835: is properly indented.
7836: @item C-M-\
7837: Re-indent all lines in the region (@code{indent-region}).
7838: @end table
7839:
7840: @kindex C-M-q
7841: @findex indent-sexp
7842: @findex indent-c-exp
7843: You can re-indent the contents of a single list by positioning point
7844: before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
7845: Lisp mode, @code{indent-c-exp} in C mode; also bound to other suitable
7846: functions in other modes). The indentation of the line the sexp starts on
7847: is not changed; therefore, only the relative indentation within the list,
7848: and not its position, is changed. To correct the position as well, type a
7849: @key{TAB} before the @kbd{C-M-q}.
7850:
7851: @kindex C-u TAB
7852: If the relative indentation within a list is correct but the indentation
7853: of its beginning is not, go to the line the list begins on and type
7854: @kbd{C-u @key{TAB}}. When @key{TAB} is given a numeric argument, it moves all the
7855: lines in the grouping starting on the current line sideways the same amount
7856: that the current line moves. It is clever, though, and does not move lines
7857: that start inside strings, or C preprocessor lines when in C mode.
7858:
7859: @kindex C-M-\
7860: @findex indent-region
7861: Another way to specify the range to be re-indented is with point and
7862: mark. The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to every line
7863: whose first character is between point and mark.
7864:
7865: @node Lisp Indent, C Indent, Multi-line Indent, Grinding
7866: @subsection Customizing Lisp Indentation
7867: @cindex customization
7868:
7869: The indentation pattern for a Lisp expression can depend on the function
7870: called by the expression. For each Lisp function, you can choose among
7871: several predefined patterns of indentation, or define an arbitrary one with
7872: a Lisp program.
7873:
7874: The standard pattern of indentation is as follows: the second line of the
7875: expression is indented under the first argument, if that is on the same
7876: line as the beginning of the expression; otherwise, the second line is
7877: indented underneath the function name. Each following line is indented
7878: under the previous line whose nesting depth is the same.
7879:
7880: @vindex lisp-indent-offset
7881: If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
7882: the usual indentation pattern for the second line of an expression, so that
7883: such lines are always indented @code{lisp-indent-offset} more columns than
7884: the containing list.
7885:
7886: @vindex lisp-body-indention
7887: The standard pattern is overridded for certain functions. Functions
7888: whose names start with @code{def} always indent the second line by
7889: @code{lisp-body-indention} extra columns beyond the open-parenthesis
7890: starting the expression.
7891:
7892: The standard pattern can be overridden in various ways for individual
7893: functions, according to the @code{lisp-indent-hook} property of the
7894: function name. There are four possibilities for this property:
7895:
7896: @table @asis
7897: @item @code{nil}
7898: This is the same as no property; the standard indentation pattern is used.
7899: @item @code{defun}
7900: The pattern used for function names that start with @code{def} is used for
7901: this function also.
7902: @item a number, @var{number}
7903: The first @var{number} arguments of the function are
7904: @dfn{distinguished} arguments; the rest are considered the @dfn{body}
7905: of the expression. A line in the expression is indented according to
7906: whether the first argument on it is distinguished or not. If the
7907: argument is part of the body, the line is indented @code{lisp-body-indent}
7908: more columns than the open-parenthesis starting the containing
7909: expression. If the argument is distinguished and is either the first
7910: or second argument, it is indented @i{twice} that many extra columns.
7911: If the argument is distinguished and not the first or second argument,
7912: the standard pattern is followed for that line.
7913: @item a symbol, @var{symbol}
7914: @var{symbol} should be a function name; that function is called to
7915: calculate the indentation of a line within this expression. The
7916: function receives two arguments:
7917: @table @asis
7918: @item @var{state}
7919: The value returned by @code{parse-partial-sexp} (a Lisp primitive for
7920: indentation and nesting computation) when it parses up to the
7921: beginning of this line.
7922: @item @var{pos}
7923: The position at which the line being indented begins.
7924: @end table
7925: @noindent
7926: It should return either a number, which is the number of columns of
7927: indentation for that line, or a list whose car is such a number. The
7928: difference between returning a number and returning a list is that a
7929: number says that all following lines at the same nesting level should
7930: be indented just like this one; a list says that following lines might
7931: call for different indentations. This makes a difference when the
7932: indentation is being computed by @kbd{C-M-q}; if the value is a
7933: number, @kbd{C-M-q} need not recalculate indentation for the following
7934: lines until the end of the list.
7935: @end table
7936:
7937: @node C Indent,, Lisp Indent, Grinding
7938: @subsection Customizing C Indentation
7939:
7940: Two variables control which commands perform C indentation and when.
7941:
7942: @vindex c-auto-newline
7943: If @code{c-auto-newline} is non-@code{nil}, newlines are inserted both
7944: before and after braces that you insert, and after colons and semicolons.
7945: Correct C indentation is done on all the lines that are made this way.
7946:
7947: @vindex c-tab-always-indent
7948: If @code{c-tab-always-indent} is non-@code{nil}, the @key{TAB} command
7949: in C mode does indentation only if point is at the left margin or within
7950: the line's indentation. If there is non-whitespace to the left of point,
7951: then @key{TAB} just inserts a tab character in the buffer. Normally,
7952: this variable is @code{nil}, and @key{TAB} always reindents the current line.
7953:
7954: C does not have anything analogous to particular function names for which
7955: special forms of indentation are desirable. However, it has a different
7956: need for customization facilities: many different styles of C indentation
7957: are in common use.
7958:
7959: There are six variables you can set to control the style that Emacs C
7960: mode will use.
7961:
7962: @table @code
7963: @item c-indent-level
7964: Indentation of C statements within surrounding block. The surrounding
7965: block's indentation is the indentation of the line on which the
7966: open-brace appears.
7967: @item c-continued-statement-offset
7968: Extra indentation given to a substatement, such as the then-clause of
7969: an if or body of a while.
7970: @item c-brace-offset
7971: Extra indentation for line if it starts with an open brace.
7972: @item c-brace-imaginary-offset
7973: An open brace following other text is treated as if it were this far
7974: to the right of the start of its line.
7975: @item c-argdecl-indent
7976: Indentation level of declarations of C function arguments.
7977: @item c-label-offset
7978: Extra indentation for line that is a label, or case or default.
7979: @end table
7980:
7981: @vindex c-indent-level
7982: The variable @code{c-indent-level} controls the indentation for C
7983: statements with respect to the surrounding block. In the example
7984:
7985: @example
7986: @{
7987: foo ();
7988: @end example
7989:
7990: @noindent
7991: the difference in indentation between the lines is @code{c-indent-level}.
7992: Its standard value is 2.
7993:
7994: If the open-brace beginning the compound statement is not at the beginning
7995: of its line, the @code{c-indent-level} is added to the indentation of the
7996: line, not the column of the open-brace. For example,
7997:
7998: @example
7999: if (losing) @{
8000: do_this ();
8001: @end example
8002:
8003: @noindent
8004: One popular indentation style is that which results from setting
8005: @code{c-indent-level} to 8 and putting open-braces at the end of a line in
8006: this way. I prefer to put the open-brace on a separate line.
8007:
8008: @vindex c-brace-imaginary-offset
8009: In fact, the value of the variable @code{c-brace-imaginary-offset} is
8010: also added to the indentation of such a statement. Normally this variable
8011: is zero. Think of this variable as the imaginary position of the open
8012: brace, relative to the first nonblank character on the line. By setting
8013: this variable to 4 and @code{c-indent-level} to 0, you can get this style:
8014:
8015: @example
8016: if (x == y) @{
8017: do_it ();
8018: @}
8019: @end example
8020:
8021: When @code{c-indent-level} is zero, the statements inside most braces
8022: will line up right under the open brace. But there is an exception made
8023: for braces in column zero, such as surrounding a function's body. The
8024: statements just inside it do not go at column zero. Instead,
8025: @code{c-brace-offset} and @code{c-continued-statement-offset} (see below)
8026: are added to produce a typical offset between brace levels, and the
8027: statements are indented that far.
8028:
8029: @vindex c-continued-statement-offset
8030: @code{c-continued-statement-offset} controls the extra indentation for a
8031: line that starts within a statement (but not within parentheses or
8032: brackets). These lines are usually statements that are within other
8033: statements, such as the then-clauses of @code{if} statements and the bodies
8034: of @code{while} statements. This parameter is the difference in
8035: indentation between the two lines in
8036:
8037: @example
8038: if (x == y)
8039: do_it ();
8040: @end example
8041:
8042: @noindent
8043: Its standard value is 2. Some popular indentation styles correspond to a
8044: value of zero for @code{c-continued-statement-offset}.
8045:
8046: @vindex c-brace-offset
8047: @code{c-brace-offset} is the extra indentation given to a line that
8048: starts with an open-brace. Its standard value is zero;
8049: compare
8050:
8051: @example
8052: if (x == y)
8053: @{
8054: @end example
8055:
8056: @noindent
8057: with
8058:
8059: @example
8060: if (x == y)
8061: do_it ();
8062: @end example
8063:
8064: @noindent
8065: if @code{c-brace-offset} were set to 4, the first example would become
8066:
8067: @example
8068: if (x == y)
8069: @{
8070: @end example
8071:
8072: @vindex c-argdecl-indent
8073: @code{c-argdecl-indent} controls the indentation of declarations of the
8074: arguments of a C function. It is absolute: argument declarations receive
8075: exactly @code{c-argdecl-indent} spaces. The standard value is 5, resulting
8076: in code like this:
8077:
8078: @example
8079: char *
8080: index (string, char)
8081: char *string;
8082: int char;
8083: @end example
8084:
8085: @vindex c-label-offset
8086: @code{c-label-offset} is the extra indentation given to a line that
8087: contains a label, a case statement, or a @code{default:} statement. Its
8088: standard value is @minus{}2, resulting in code like this
8089:
8090: @example
8091: switch (c)
8092: @{
8093: case 'x':
8094: @end example
8095:
8096: @noindent
8097: If @code{c-label-offset} were zero, the same code would be indented as
8098:
8099: @example
8100: switch (c)
8101: @{
8102: case 'x':
8103: @end example
8104:
8105: @noindent
8106: This example assumes that the other variables above also have their
8107: standard values.
8108:
8109: I strongly recommend that you try out the indentation style produced by
8110: the standard settings of these variables, together with putting open braces
8111: on separate lines. You can see how it looks in all the C source files of
8112: GNU Emacs.
8113:
8114: @node Matching, Comments, Grinding, Programs
8115: @section Automatic Display Of Matching Parentheses
8116: @cindex matching parentheses
8117: @cindex parentheses
8118:
8119: The Emacs parenthesis-matching feature is designed to show automatically
8120: how parentheses match in the text. Whenever a self-inserting character
8121: that is a closing delimiter is typed, the cursor moves momentarily to the
8122: location of the matching opening delimiter, provided that is on the screen.
8123: If it is not on the screen, some text starting with that opening delimiter
8124: is displayed in the echo area. Either way, you can tell what grouping is
8125: being closed off.
8126:
8127: In Lisp, automatic matching applies only to parentheses. In C, it
8128: applies to braces and brackets too. Emacs knows which characters to regard
8129: as matching delimiters based on the syntax table, which is set by the major
8130: mode. @xref{Syntax}.
8131:
8132: If the opening delimiter and closing delimiter are mismatched---such as
8133: in @samp{[x)}---a warning message is displayed in the echo area. The
8134: correct matches are specified in the syntax table.
8135:
8136: @vindex blink-matching-paren
8137: @vindex blink-matching-paren-distance
8138: Two variables control parenthesis match display. @code{blink-matching-paren}
8139: turns the feature on or off; @code{nil} turns it off, but the default is
8140: @code{t} to turn match display on. @code{blink-matching-paren-distance}
8141: specifies how many characters back to search to find the matching opening
8142: delimiter. If the match is not found in that far, scanning stops, and
8143: nothing is displayed. This is to prevent scanning for the matching
8144: delimiter from wasting lots of time when there is no match. The default
8145: is 4000.
8146:
8147: @node Comments, Balanced Editing, Matching, Programs
8148: @section Manipulating Comments
8149: @cindex comments
8150: @kindex M-;
8151: @cindex indentation
8152: @findex indent-for-comment
8153:
8154: The comment commands insert, kill and align comments.
8155:
8156: @c WideCommands
8157: @table @kbd
8158: @item M-;
8159: Insert or align comment (@code{indent-for-comment}).
8160: @item C-x ;
8161: Set comment column (@code{set-comment-column}).
8162: @item C-u - C-x ;
8163: Kill comment on current line (@code{kill-comment}).
8164: @item M-@key{LFD}
8165: Like @key{RET} followed by inserting and aligning a comment
8166: (@code{indent-new-comment-line}).
8167: @end table
8168:
8169: The command that creates a comment is @kbd{Meta-;} (@code{indent-for-comment}).
8170: If there is no comment already on the line, a new comment is created,
8171: aligned at a specific column called the @dfn{comment column}. The comment
8172: is created by inserting the string Emacs thinks comments should start with
8173: (the value of @code{comment-start}; see below). Point is left after that
8174: string. If the text of the line extends past the comment column, then the
8175: indentation is done to a suitable boundary (usually, at least one space is
8176: inserted). If the major mode has specified a string to terminate comments,
8177: that is inserted after point, to keep the syntax valid.
8178:
8179: @kbd{Meta-;} can also be used to align an existing comment. If a line
8180: already contains the string that starts comments, then @kbd{M-;} just moves
8181: point after it and re-indents it to the conventional place. Exception:
8182: comments starting in column 0 are not moved.
8183:
8184: Some major modes have special rules for indenting certain kinds of
8185: comments in certain contexts. For example, in Lisp code, comments which
8186: start with two semicolons are indented as if they were lines of code,
8187: instead of at the comment column. Comments which start with three
8188: semicolons are supposed to start at the left margin. Emacs understands
8189: these conventions by indenting a double-semicolon comment using @key{TAB},
8190: and by not changing the indentation of a triple-semicolon comment at all.
8191:
8192: @example
8193: ;; This function is just an example
8194: ;;; Here either two or three semicolons are appropriate.
8195: (defun foo (x)
8196: ;;; And now, the first part of the function:
8197: ;; The following line adds one.
8198: (1+ x)) ; This line adds one.
8199: @end example
8200:
8201: In C code, a comment preceded on its line by nothing but whitespace
8202: is indented like a line of code.
8203:
8204: Even when an existing comment is properly aligned, @kbd{M-;} is still
8205: useful for moving directly to the start of the comment.
8206:
8207: @kindex C-u - C-x ;
8208: @findex kill-comment
8209: @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line,
8210: if there is one. The indentation before the start of the comment is killed
8211: as well. If there does not appear to be a comment in the line, nothing is
8212: done. To reinsert the comment on another line, move to the end of that
8213: line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that
8214: @kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
8215: with a negative argument. That command is programmed so that when it
8216: receives a negative argument it calls @code{kill-comment}. However,
8217: @code{kill-comment} is a valid command which you could bind directly to a
8218: key if you wanted to.
8219:
8220: @subsection Multiple Lines of Comments
8221:
8222: @kindex M-LFD
8223: @cindex blank lines
8224: @cindex Auto Fill mode
8225: @findex indent-new-comment-line
8226: If you are typing a comment and find that you wish to continue it on
8227: another line, you can use the command @kbd{Meta-@key{LFD}} (@code{indent-new-comment-line}),
8228: which terminates the comment you are typing, creates a new blank line
8229: afterward, and begins a new comment indented under the old one. When Auto
8230: Fill mode is on, going past the fill column while typing a comment causes
8231: the comment to be continued in just this fashion. If point is not at the
8232: end of the line when @kbd{M-@key{LFD}} is typed, the text on the rest of
8233: the line becomes part of the new comment line.
8234:
8235: @subsection Options Controlling Comments
8236:
8237: @vindex comment-column
8238: @kindex C-x ;
8239: @findex set-comment-column
8240: The comment column is stored in the variable @code{comment-column}. You
8241: can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
8242: (@code{set-comment-column}) sets the comment column to the column point is
8243: at. @kbd{C-u C-x ;} sets the comment column to match the last comment
8244: before point in the buffer, and then does a @kbd{Meta-;} to align the
8245: current line's comment under the previous one. Note that @kbd{C-u - C-x ;}
8246: runs the function @code{kill-comment} as described above.
8247:
8248: @code{comment-column} is a per-buffer variable; altering the variable
8249: affects only the current buffer, but there is a default value which you can
8250: change as well. @xref{Locals}. Many major modes initialize this variable
8251: for the current buffer.
8252:
8253: @vindex comment-start-skip
8254: The comment commands recognize comments based on the regular expression
8255: that is the value of the variable @code{comment-start-skip}. This regexp
8256: should not match the null string. It may match more than the comment
8257: starting delimiter in the strictest sense of the word; for example, in C
8258: mode the value of the variable is @code{@t{"/\\*+ *"}}, which matches extra
8259: stars and spaces after the @samp{/*} itself. (Note that @samp{\\} is
8260: needed in Lisp syntax to include a @samp{\} in the string, which is needed
8261: to deny the first star its special meaning in regexp syntax. @xref{Regexps}.)
8262:
8263: @vindex comment-start
8264: @vindex comment-end
8265: When a comment command makes a new comment, it inserts the value of
8266: @code{comment-start} to begin it. The value of @code{comment-end} is
8267: inserted after point, so that it will follow the text that you will insert
8268: into the comment. In C mode, @code{comment-start} has the value
8269: @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
8270:
8271: @vindex comment-multi-line
8272: @code{comment-multi-line} controls how @kbd{M-@key{LFD}} (@code{indent-new-comment-line})
8273: behaves when used inside a comment. If @code{comment-multi-line} is
8274: @code{nil}, as it normally is, then the comment on the starting line is
8275: terminated and a new comment is started on the new following line. If
8276: @code{comment-multi-line} is not @code{nil}, then the new following line is
8277: set up as part of the same comment that was found on the starting line.
8278: This is done by not inserting a terminator on the old line, and not
8279: inserting a starter on the new line. In languages where multi-line comments
8280: work, the choice of value for this variable is a matter of taste.
8281:
8282: @vindex comment-indent-hook
8283: The variable @code{comment-indent-hook} should contain a function that
8284: will be called to compute the indentation for a newly inserted comment or
8285: for aligning an existing comment. It is set differently by various major
8286: modes. The function is called with no arguments, but with point at the
8287: beginning of the comment, or at the end of a line if a new comment is to be
8288: inserted. It should return the column in which the comment ought to start.
8289: For example, in Lisp mode, the indent hook function bases its decision
8290: on how many semicolons begin an existing comment, and on the code in the
8291: preceding lines.
8292:
8293: @node Balanced Editing, Lisp Completion, Comments, Programs
8294: @section Editing Without Unbalanced Parentheses
8295:
8296: @table @kbd
8297: @item M-(
8298: Put parentheses around next sexp(s) (@code{insert-parentheses}).
8299: @item M-)
8300: Move past next close parenthesis and re-indent
8301: (@code{move-over-close-and-reindent}).
8302: @end table
8303:
8304: @kindex M-(
8305: @kindex M-)
8306: @findex insert-parentheses
8307: @findex move-over-close-and-reindent
8308: The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
8309: (@code{move-over-close-and-reindent}) are designed to facilitate a style of
8310: editing which keeps parentheses balanced at all times. @kbd{M-(} inserts a
8311: pair of parentheses, either together as in @samp{()}, or, if given an
8312: argument, around the next several sexps, and leaves point after the open
8313: parenthesis. Instead of typing @kbd{( F O O )}, you can type @kbd{M-( F O
8314: O}, which has the same effect except for leaving the cursor before the
8315: close parenthesis. Then you would type @kbd{M-)}, which moves past the
8316: close parenthesis, deleting any indentation preceding it (in this example
8317: there is none), and indenting with @key{LFD} after it.
8318:
8319: @node Lisp Completion, Documentation, Balanced Editing, Programs
8320: @section Completion for Lisp Symbols
8321: @cindex completion (symbol names)
8322:
8323: Usually completion happens in the minibuffer. But one kind of completion
8324: is available in all buffers: completion for Lisp symbol names.
8325:
8326: @kindex M-TAB
8327: @findex lisp-complete-symbol
8328: The command @kbd{M-@key{TAB}} (@code{lisp-complete-symbol}) takes the
8329: partial Lisp symbol before point to be an abbreviation, and compares it
8330: against all nontrivial Lisp symbols currently known to Emacs. Any
8331: additional characters that they all have in common are inserted at point.
8332: Nontrivial symbols are those that have function definitions, values or
8333: properties.
8334:
8335: If there is an open-parenthesis immediately before the beginning of
8336: the partial symbol, only symbols with function definitions are considered
8337: as completions.
8338:
8339: If the partial name in the buffer has more than one possible completion
8340: and they have no additional characters in common, a list of all possible
8341: completions is displayed in another window.
8342:
8343: @node Documentation, Change Log, Lisp Completion, Programs
8344: @section Documentation Commands
8345:
8346: @kindex C-h f
8347: @findex describe-function
8348: @kindex C-h v
8349: @findex describe-variable
8350: As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
8351: (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
8352: be used to print documentation of functions and variables that you want to
8353: call. These commands use the minibuffer to read the name of a function or
8354: variable to document, and display the documentation in a window.
8355:
8356: For extra convenience, these commands provide default arguments based on
8357: the code in the neighborhood of point. @kbd{C-h f} sets the default to the
8358: function called in the innermost list containing point. @kbd{C-h v} uses
8359: the symbol name around or adjacent to point as its default.
8360:
8361: @findex manual-entry
8362: Documentation on Unix commands, system calls and libraries can be
8363: obtained with the @kbd{M-x manual-entry} command. This reads a topic as an
8364: argument, and displays the text on that topic from the Unix manual.
8365: @code{manual-entry} always searches all 8 sections of the manual, and
8366: concatenates all the entries that are found. For example, the topic
8367: @samp{termcap} finds the description of the termcap library from section 3,
8368: followed by the description of the termcap data base from section 5.
8369:
8370: @node Change Log, Tags, Documentation, Programs
8371: @section Change Logs
8372:
8373: @cindex change log
8374: @findex add-change-log-entry
8375: The Emacs command @kbd{M-x add-change-log-entry} helps you keep a record
8376: of when and why you have changed a program. It assumes that you have a
8377: file in which you write a chronological sequence of entries describing
8378: individual changes. The default is to store the change entries in a file
8379: called @file{ChangeLog} in the same directory as the file you are editing.
8380: The same @file{ChangeLog} file therefore records changes for all the files
8381: in the directory.
8382:
8383: A change log entry starts with a header line that contains your name and
8384: the current date. Aside from these header lines, every line in the change
8385: log starts with a tab. One entry can describe several changes; each change
8386: starts with a line starting with a tab and a star. @kbd{M-x add-change-log-entry}
8387: visits the change log file and creates a new entry unless the most recent
8388: entry is for today's date and your name. In either case, it adds a new
8389: line to start the description of another change just after the header line
8390: of the entry. When @kbd{M-x add-change-log-entry} is finished, all is
8391: prepared for you to edit in the description of what you changed and how.
8392: You must then save the change log file yourself.
8393:
8394: The change log file is always visited in Indented Text mode, which means
8395: that @key{LFD} and auto-filling indent each new line like the previous
8396: line. This is convenient for entering the contents of an entry, which must
8397: all be indented. @xref{Text Mode}.
8398:
8399: Here is an example of the formatting conventions used in the change log
8400: for Emacs:
8401:
8402: @smallexample
8403: Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep)
8404:
8405: * xdisp.c (try_window_id):
8406: If C-k is done at end of next-to-last line,
8407: this fn updates window_end_vpos and cannot leave
8408: window_end_pos nonnegative (it is zero, in fact).
8409: If display is preempted before lines are output,
8410: this is inconsistent. Fix by setting
8411: blank_end_of_window to nonzero.
8412:
8413: Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep)
8414:
8415: * cmds.c (Fnewline):
8416: Call the auto fill hook if appropriate.
8417:
8418: * xdisp.c (try_window_id):
8419: If point is found by compute_motion after xp, record that
8420: permanently. If display_text_line sets point position wrong
8421: (case where line is killed, point is at eob and that line is
8422: not displayed), set it again in final compute_motion.
8423: @end smallexample
8424:
8425: @node Tags, Fortran, Change Log, Programs
8426: @section Tag Tables
8427: @cindex tag table
8428:
8429: A @dfn{tag table} is a description of how a multi-file program is broken
8430: up into files. It lists the names of the component files and the names and
8431: positions of the functions in each file. Grouping the related files makes
8432: it possible to search or replace through all the files with one command.
8433: Recording the function names and positions makes possible the @kbd{Meta-.}
8434: command which you can use to find the definition of a function without
8435: having to know which of the files it is in.
8436:
8437: Tag tables are stored in files called @dfn{tag table files}. The
8438: conventional name for a tag table file is @file{TAGS}.
8439:
8440: Each entry in the tag table records the name of one tag, the name of the
8441: file that the tag is defined in (implicitly), and the position in that file
8442: of the tag's definition.
8443:
8444: Just what names from the described files are recorded in the tag table
8445: depends on the programming language of the described file. They normally
8446: include all functions and subroutines, and may also include global
8447: variables, data types, and anything else convenient. In any case, each
8448: name recorded is called a @dfn{tag}.
8449:
8450: @menu
8451: * Tag Syntax::
8452: * Create Tag Table::
8453: * Select Tag Table::
8454: * Find Tag::
8455: * Tags Search::
8456: * Tags Stepping::
8457: * List Tags::
8458: @end menu
8459:
8460: @node Tag Syntax, Create Tag Table, Tags, Tags
8461: @subsection Source File Tag Syntax
8462:
8463: In Lisp code, any function defined with @code{defun}, any variable
8464: defined with @code{defvar} or @code{defconst}, and in general the first
8465: argument of any expression that starts with @samp{(def} in column zero, is
8466: a tag.
8467:
8468: In C code, any C function is a tag, and so is any typedef if @code{-t} is
8469: specified when the tag table is constructed.
8470:
8471: In Fortran code, functions and subroutines are tags.
8472:
8473: In La@TeX{} text, the argument of any of the commands @code{\chapter},
8474: @code{\section}, @code{\subsection}, @code{\subsubsection}, @code{\eqno},
8475: @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem} and
8476: @code{\typeout} is a tag.@refill
8477:
8478: @node Create Tag Table, Select Tag Table, Tag Syntax, Tags
8479: @subsection Creating Tag Tables
8480: @cindex etags program
8481:
8482: The @code{etags} program is used to create a tag table file. It knows
8483: the syntax of C, Fortran, La@TeX{}, Scheme and Emacs Lisp/Common Lisp. To
8484: use @code{etags}, type
8485:
8486: @example
8487: etags @var{inputfiles}@dots{}
8488: @end example
8489:
8490: @noindent
8491: as a shell command. It reads the specified files and writes a tag table
8492: named @file{TAGS} in the current working directory. @code{etags}
8493: recognizes the language used in an input file based on its file name and
8494: contents; there are no switches for specifying the language. The @code{-t}
8495: switch tells @code{etags} to record typedefs in C code as tags.
8496:
8497: If the tag table data become outdated due to changes in the files
8498: described in the table, the way to update the tag table is the same way it
8499: was made in the first place. It is not necessary to do this often.
8500:
8501: If the tag table fails to record a tag, or records it for the wrong file,
8502: then Emacs cannot possibly find its definition. However, if the position
8503: recorded in the tag table becomes a little bit wrong (due to some editing
8504: in the file that the tag definition is in), the only consequence is to slow
8505: down finding the tag slightly. Even if the stored position is very wrong,
8506: Emacs will still find the tag, but it must search the entire file for it.
8507:
8508: So you should update a tag table when you define new tags that you want
8509: to have listed, or when you move tag definitions from one file to another,
8510: or when changes become substantial. Normally there is no need to update
8511: the tag table after each edit, or even every day.
8512:
8513: @node Select Tag Table, Find Tag, Create Tag Table, Tags
8514: @subsection Selecting a Tag Table
8515:
8516: @vindex tags-file-name
8517: @findex visit-tags-table
8518: Emacs has at any time one @dfn{selected} tag table, and all the commands
8519: for working with tag tables use the selected one. To select a tag table,
8520: type @kbd{M-x visit-tags-table}, which reads the tag table file name as an
8521: argument. The name @file{TAGS} in the default directory is used as the
8522: default file name.
8523:
8524: All this command does is store the file name in the variable
8525: @code{tags-file-name}. Emacs does not actually read in the tag table
8526: contents until you try to use them. Setting this variable yourself is just
8527: as good as using @code{visit-tags-table}. The variable's initial value is
8528: @code{nil}; this value tells all the commands for working with tag tables
8529: that they must ask for a tag table file name to use.
8530:
8531: @node Find Tag, Tags Search, Select Tag Table, Tags
8532: @subsection Finding a Tag
8533:
8534: The most important thing that a tag table enables you to do is to find
8535: the definition of a specific tag.
8536:
8537: @table @kbd
8538: @item M-.@: @var{tag}
8539: Find first definition of @var{tag} (@code{find-tag}).
8540: @item C-u M-.
8541: Find next alternate definition of last tag specified.
8542: @item C-x 4 .@: @var{tag}
8543: Find first definition of @var{tag}, but display it in another window
8544: (@code{find-tag-other-window}).
8545: @end table
8546:
8547: @kindex M-.
8548: @findex find-tag
8549: @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of a
8550: specified tag. It searches through the tag table for that tag, as a
8551: string, and then uses the tag table info to determine the file that the
8552: definition is in and the approximate character position in the file of the
8553: definition. Then @code{find-tag} visits that file, moves point to the
8554: approximate character position, and starts searching ever-increasing
8555: distances away for the the text that should appear at the beginning of the
8556: definition.
8557:
8558: If an empty argument is given (just type @key{RET}), the sexp in the
8559: buffer before or around point is used as the name of the tag to find.
8560: @xref{Lists}, for info on sexps.
8561:
8562: The argument to @code{find-tag} need not be the whole tag name; it can be
8563: a substring of a tag name. However, there can be many tag names containing
8564: the substring you specify. Since @code{find-tag} works by searching the
8565: text of the tag table, it finds the first tag in the table that the
8566: specified substring appears in. The way to find other tags that match the
8567: substring is to give @code{find-tag} a numeric argument, as in @kbd{C-u
8568: M-.}; this does not read a tag name, but continues searching the tag
8569: table's text for another tag containing the same substring last used. If
8570: you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier alternative
8571: to @kbd{C-u M-.}.
8572:
8573: @kindex C-x 4 .
8574: @findex find-tag-other-window
8575: Like most commands that can switch buffers, @code{find-tag} has another
8576: similar command that displays the new buffer in another window. @kbd{C-x 4
8577: .}@: invokes the function @code{find-tag-other-window}. (This key sequence
8578: ends with a period.)
8579:
8580: Emacs comes with a tag table file @file{TAGS}, in the directory
8581: containing Lisp libraries, which includes all the Lisp libraries and all
8582: the C sources of Emacs. By specifying this file with @code{visit-tags-table}
8583: and then using @kbd{M-.}@: you can quickly look at the source of any Emacs
8584: function.
8585:
8586: @node Tags Search, Tags Stepping, Find Tag, Tags
8587: @subsection Searching and Replacing with Tag Tables
8588:
8589: The commands in this section visit and search all the files listed in the
8590: selected tag table, one by one. For these commands, the tag table serves
8591: only to specify a sequence of files to search. A related command is
8592: @kbd{M-x grep} (@pxref{Compilation}).
8593:
8594: @table @kbd
8595: @item M-x tags-search
8596: Search for the specified regexp through the files in the selected tag
8597: table.
8598: @item M-x tags-query-replace
8599: Perform a @code{query-replace} on each file in the selected tag table.
8600: @item M-,
8601: Restart one of the commands above, from the current location of point
8602: (@code{tags-loop-continue}).
8603: @end table
8604:
8605: @findex tags-search
8606: @kbd{M-x tags-search} reads a regexp using the minibuffer, then visits
8607: the files of the selected tag table one by one, and searches through each
8608: one for that regexp. It displays the name of the file being searched so
8609: you can follow its progress. As soon as an occurrence is found,
8610: @code{tags-search} returns.
8611:
8612: @kindex M-,
8613: @findex tags-loop-continue
8614: Having found one match, you probably want to find all the rest. To find
8615: one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
8616: @code{tags-search}. This searches the rest of the current buffer, followed
8617: by the remaining files of the tag table.
8618:
8619: @findex tags-query-replace
8620: @kbd{M-x tags-query-replace} performs a single @code{query-replace}
8621: through all the files in the tag table. It reads a string to search for
8622: and a string to replace with, just like ordinary @kbd{M-x query-replace}.
8623: It searches much like @kbd{M-x tags-search} but repeatedly, processing
8624: matches according to your input. @xref{Replace}, for more information on
8625: @code{query-replace}.@refill
8626:
8627: It is possible to get through all the files in the tag table with a
8628: single invocation of @kbd{M-x tags-query-replace}. But since any
8629: unrecognized character causes the command to exit, you may need to continue
8630: where you left off. @kbd{M-,} can be used for this. It resumes the last
8631: tags search or replace command that you did.
8632:
8633: It may have struck you that @code{tags-search} is a lot like @code{grep}.
8634: You can also run @code{grep} itself as an inferior of Emacs and have Emacs
8635: show you the matching lines one by one. This works mostly the same as
8636: running a compilation and having Emacs show you where the errors were.
8637: @xref{Compilation}.
8638:
8639: @node Tags Stepping, List Tags, Tags Search, Tags
8640: @subsection Stepping Through a Tag Table
8641: @findex next-file
8642:
8643: If you wish to process all the files in the selected tag table, but
8644: @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} in particular are not what
8645: you want, you can use @kbd{M-x next-file}.
8646:
8647: @table @kbd
8648: @item C-u M-x next-file
8649: With a numeric argument, regardless of its value, visit the first
8650: file in the tag table, and prepare to advance sequentially by files.
8651: @item M-x next-file
8652: Visit the next file in the selected tag table.
8653: @end table
8654:
8655: @node List Tags,, Tags Stepping, Tags
8656: @subsection Tag Table Inquiries
8657:
8658: @table @kbd
8659: @item M-x list-tags
8660: Display a list of the tags defined in a specific program file.
8661: @item M-x tags-apropos
8662: Display a list of all tags matching a specified regexp.
8663: @end table
8664:
8665: @findex list-tags
8666: @kbd{M-x list-tags} reads the name of one of the files described by the
8667: selected tag table, and displays a list of all the tags defined in that
8668: file. The ``file name'' argument is really just a string to compare
8669: against the names recorded in the tag table; it is read as a string rather
8670: than as a file name. Therefore, completion and defaulting are not
8671: available, and you must enter the string the same way it appears in the tag
8672: table. Do not include a directory as part of the file name unless the file
8673: name recorded in the tag table includes a directory.
8674:
8675: @findex tags-apropos
8676: @kbd{M-x tags-apropos} is like @code{apropos} for tags. It reads a regexp,
8677: then finds all the tags in the selected tag table whose entries match that
8678: regexp, and displays the tag names found.
8679:
8680: @node Fortran,, Tags, Programs
8681: @section Fortran Mode
8682: @cindex Fortran mode
8683:
8684: Fortran mode provides special motion commands for Fortran statements and
8685: subprograms, and indentation commands that understand Fortran conventions
8686: of nesting, line numbers and continuation statements.
8687:
8688: Special commands for comments are provided because Fortran comments are
8689: unlike those of other languages.
8690:
8691: Built-in abbrevs optionally save typing when you insert Fortran keywords.
8692:
8693: @findex fortran-mode
8694: Use @kbd{M-x fortran-mode} to switch to this major mode. Doing so calls
8695: the value of @code{fortran-mode-hook} as a function of no arguments if
8696: that variable has a value that is not @code{nil}.
8697:
8698: @menu
8699: * Motion: Fortran Motion. Moving point by statements or subprograms.
8700: * Indent: Fortran Indent. Indentation commands for Fortran.
8701: * Comments: Fortran Comments. Inserting and aligning comments.
8702: * Columns: Fortran Columns. Measuring columns for valid Fortran.
8703: * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
8704: @end menu
8705:
8706: Fortran mode was contributed by Michael Prange.
8707:
8708: @node Fortran Motion, Fortran Indent, Fortran, Fortran
8709: @subsection Motion Commands
8710:
8711: Fortran mode provides special commands to move by subprograms (functions
8712: and subroutines) and by statements. There is also a command to put the
8713: region around one subprogram, convenient for killing it or moving it.
8714:
8715: @kindex C-M-a (Fortran mode)
8716: @kindex C-M-e (Fortran mode)
8717: @kindex C-M-h (Fortran mode)
8718: @kindex C-c C-p (Fortran mode)
8719: @kindex C-c C-n (Fortran mode)
8720: @findex beginning-of-fortran-subprogram
8721: @findex end-of-fortran-subprogram
8722: @findex mark-fortran-subprogram
8723: @findex fortran-previous-statement
8724: @findex fortran-next-statement
8725:
8726: @table @kbd
8727: @item C-M-a
8728: Move to beginning of subprogram@*
8729: (@code{beginning-of-fortran-subprogram}).
8730: @item C-M-e
8731: Move to end of subprogram (@code{end-of-fortran-subprogram}).
8732: @item C-M-h
8733: Put point at beginning of subprogram and mark at end
8734: (@code{mark-fortran-subprogram}).
8735: @item C-c C-n
8736: Move to beginning of current or next statement
8737: (@code{fortran-next-statement}).
8738: @item C-c C-p
8739: Move to beginning of current or previous statement
8740: (@code{fortran-previous-statement}).
8741: @end table
8742:
8743: @node Fortran Indent, Fortran Comments, Fortran Motion, Fortran
8744: @subsection Fortran Indentation
8745:
8746: Special commands and features are needed for indenting Fortran code in
8747: order to make sure various syntactic entities (line numbers, comment line
8748: indicators and continuation line flags) appear in the columns that are
8749: required for standard Fortran.
8750:
8751: @menu
8752: * Commands: ForIndent Commands. Commands for indenting Fortran.
8753: * Numbers: ForIndent Num. How line numbers auto-indent.
8754: * Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
8755: * Vars: ForIndent Vars. Variables controlling Fortran indent style.
8756: @end menu
8757:
8758: @node ForIndent Commands, ForIndent Num, Fortran Indent, Fortran Indent
8759: @subsubsection Fortran Indentation Commands
8760:
8761: @table @kbd
8762: @item @key{TAB}
8763: Indent the current line (@code{fortran-indent-line}).
8764: @item M-@key{LFD}
8765: Break the current line and set up a continuation line.
8766: @item C-M-q
8767: Indent all the lines of the subprogram point is in
8768: (@code{fortran-indent-subprogram}).
8769: @end table
8770:
8771: @findex fortran-indent-line
8772: @key{TAB} is redefined by Fortran mode to reindent the current line for
8773: Fortran (@code{fortran-indent-line}). Line numbers and continuation
8774: markers are indented to their required columns, and the body of the
8775: statement is independently indented based on its nesting in the program.
8776:
8777: @kindex C-M-q (Fortran mode)
8778: @findex fortran-indent-subprogram
8779: The key @kbd{C-M-q} is redefined as @code{fortran-indent-subprogram}, a
8780: command to reindent all the lines of the Fortran subprogram (function or
8781: subroutine) containing point.
8782:
8783: @kindex M-LFD (Fortran mode)
8784: @findex fortran-split-line
8785: The key @kbd{M-@key{LFD}} is redefined as @code{fortran-split-line}, a
8786: command to split a line in the appropriate fashion for Fortran. In a
8787: non-comment line, the second half becomes a continuation line and is
8788: indented accordingly. In a comment line, both halves become separate
8789: comment lines.
8790:
8791: @node ForIndent Num, ForIndent Conv, ForIndent Commands, Fortran Indent
8792: @subsubsection Line Numbers and Continuation
8793:
8794: If a number is the first non-whitespace in the line, it is assumed to be
8795: a line number and is moved to columns 0 through 4. (Columns are always
8796: counted from 0 in GNU Emacs.) If the text on the line starts with the
8797: conventional Fortran continuation marker @samp{$}, it is moved to column 5.
8798: If the text begins with any non whitespace character in column 5, it is
8799: assumed to be an unconventional continuation marker and remains in column
8800: 5.
8801:
8802: @vindex fortran-line-number-indent
8803: Line numbers of four digits or less are normally indented one space.
8804: This amount is controlled by the variable @code{fortran-line-number-indent}
8805: which is the maximum indentation a line number can have. Line numbers
8806: are indented to right-justify them to end in column 4 unless that would
8807: require more than this maximum indentation. The default value of the
8808: variable is 1.
8809:
8810: @vindex fortran-electric-line-number
8811: Simply inserting a line number is enough to indent it according to these
8812: rules. As each digit is inserted, the indentation is recomputed. To turn
8813: off this feature, set the variable @code{fortran-electric-line-number} to
8814: @code{nil}. Then inserting line numbers is like inserting anything else.
8815:
8816: @node ForIndent Conv, ForIndent Vars, ForIndent Num, Fortran Indent
8817: @subsubsection Syntactic Conventions
8818:
8819: Fortran mode assumes that you follow certain conventions that simplify
8820: the task of understanding a Fortran program well enough to indent it
8821: properly:
8822:
8823: @vindex fortran-continuation-char
8824: @itemize @bullet
8825: @item
8826: Two nested @samp{do} loops never share a @samp{continue} statement.
8827:
8828: @item
8829: The same character appears in column 5 of all continuation lines, and
8830: this character is the value of the variable @code{fortran-continuation-char}.
8831: By default, this character is @samp{$}.
8832: @end itemize
8833:
8834: @noindent
8835: If you fail to follow these conventions, the indentation commands may
8836: indent some lines unaesthetically. However, a correct Fortran program will
8837: retain its meaning when reindented even if the conventions are not
8838: followed.
8839:
8840: @node ForIndent Vars,, ForIndent Conv, Fortran Indent
8841: @subsubsection Variables for Fortran Indentation
8842:
8843: @vindex fortran-do-indent
8844: @vindex fortran-if-indent
8845: @vindex fortran-continuation-indent
8846: @vindex fortran-check-all-num-for-matching-do
8847: @vindex fortran-minimum-statement-indent
8848: Several additional variables control how Fortran indentation works.
8849:
8850: @table @code
8851: @item fortran-do-indent
8852: Extra indentation within each level of @samp{do} statement (default 3).
8853:
8854: @item fortran-if-indent
8855: Extra indentation within each level of @samp{if} statement (default 3).
8856:
8857: @item fortran-continuation-indent
8858: Extra indentation for bodies of continuation lines (default 5).
8859:
8860: @item fortran-check-all-num-for-matching-do
8861: If this is @code{nil}, indentation assumes that each @samp{do}
8862: statement ends on a @samp{continue} statement. Therefore, when
8863: computing indentation for a statement other than @samp{continue}, it
8864: can save time by not checking for a @samp{do} statement ending there.
8865: If this is non-@code{nil}, indenting any numbered statement must check
8866: for a @samp{do} that ends there. The default is @code{nil}.
8867:
8868: @item fortran-minimum-statement-indent
8869: Minimum indentation for fortran statements. For standard Fortran,
8870: this is 6. Statement bodies will never be indented less than this
8871: much.
8872: @end table
8873:
8874: @node Fortran Comments, Fortran Columns, Fortran Indent, Fortran
8875: @subsection Comments
8876:
8877: The usual Emacs comment commands assume that a comment can follow a line
8878: of code. In Fortran, the standard comment syntax requires an entire line
8879: to be just a comment. Therefore, Fortran mode replaces the standard Emacs
8880: comment commands and defines some new variables.
8881:
8882: Fortran mode can also handle a nonstandard comment syntax where comments
8883: start with @samp{!} and can follow other text. Because only some Fortran
8884: compilers accept this syntax, Fortran mode will not insert such comments
8885: unless you have said in advance to do so. To do this, set the variable
8886: @code{comment-start} to @samp{"!"} (@pxref{Variables}).
8887:
8888: @table @kbd
8889: @item M-;
8890: Align comment or insert new comment (@code{fortran-comment-indent}).
8891:
8892: @item C-x ;
8893: Applies to nonstandard @samp{!} comments only.
8894:
8895: @item C-c ;
8896: Turn all lines of the region into comments, or (with arg)
8897: turn them back into real code (@code{fortran-comment-region}).
8898: @end table
8899:
8900: @kbd{M-;} in Fortran mode is redefined as the command
8901: @code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this
8902: recognizes any kind of existing comment and aligns its text appropriately;
8903: if there is no existing comment, a comment is inserted and aligned. But
8904: inserting and aligning comments are not the same in Fortran mode as in
8905: other modes.
8906:
8907: When a new comment must be inserted, if the current line is blank, a
8908: full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
8909: comment is inserted if you have said you want to use them. Otherwise a
8910: full-line comment is inserted on a new line before the current line.
8911:
8912: Nonstandard @samp{!} comments are aligned like comments in other
8913: languages, but full-line comments are different. In a standard full-line
8914: comment, the comment delimiter itself must always appear in column zero.
8915: What can be aligned is the text within the comment. You can choose from
8916: three styles of alignment by setting the variable
8917: @code{fortran-comment-indent-style} to one of these values:
8918:
8919: @vindex fortran-comment-indent-style
8920: @vindex fortran-comment-line-column
8921: @table @code
8922: @item fixed
8923: The text is aligned at a fixed column, which is the value of
8924: @code{fortran-comment-line-column}. This is the default.
8925: @item relative
8926: The text is aligned as if it were a line of code, but with an
8927: additional @code{fortran-comment-line-column} columns of indentation.
8928: @item nil
8929: Text in full-line columns is not moved automatically.
8930: @end table
8931:
8932: @vindex fortran-comment-indent-char
8933: In addition, you can specify the character to be used to indent within
8934: full-line comments by setting the variable @code{fortran-comment-indent-char}
8935: to the character you want to use.
8936:
8937: @vindex comment-line-start
8938: @vindex comment-line-start-skip
8939: Fortran mode introduces two variables @code{comment-line-start} and
8940: @code{comment-line-start-skip} which play for full-line comments the same
8941: roles played by @code{comment-start} and @code{comment-start-skip} for
8942: ordinary text-following comments. Normally these are set properly by
8943: Fortran mode so you do not need to change them.
8944:
8945: The normal Emacs comment command @kbd{C-x ;} has not been redefined.
8946: If you use @samp{!} comments, this command can be used with them. Otherwise
8947: it is useless in Fortran mode.
8948:
8949: @kindex C-c ; (Fortran mode)
8950: @findex fortran-comment-region
8951: @vindex fortran-comment-region
8952: The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
8953: lines of the region into comments by inserting the string @samp{C$$$} at
8954: the front of each one. With a numeric arg, the region is turned back into
8955: live code by deleting @samp{C$$$} from the front of each line in it. The
8956: string used for these comments can be controlled by setting the variable
8957: @code{fortran-comment-region}. Note that here we have an example of a
8958: command and a variable with the same name; these two uses of the name never
8959: conflict because in Lisp and in Emacs it is always clear from the context
8960: which one is meant.
8961:
8962: @node Fortran Columns, Fortran Abbrev, Fortran Comments, Fortran
8963: @subsection Columns
8964:
8965: @table @kbd
8966: @item C-c C-r
8967: Displays a ``column ruler'' momentarily above the current line
8968: (@code{fortran-column-ruler}).
8969: @item C-c C-w
8970: Splits the current window horizontally so that it is 72 columns wide.
8971: This may help you avoid going over that limit (@code{fortran-window-create}).
8972: @end table
8973:
8974: @kindex C-c C-r (Fortran mode)
8975: @findex fortran-column-ruler
8976: @vindex fortran-column-ruler
8977: The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
8978: ruler momentarily above the current line. The comment ruler is two lines
8979: of text that show you the locations of columns with special significance
8980: in Fortran programs. Square brackets show the limits of the columns for
8981: line numbers, and curly brackets show the limits of the columns for the
8982: statement body. Column numbers appear above them.
8983:
8984: Note that the column numbers count from zero, as always in GNU Emacs. As
8985: a result, the numbers may not be those you are familiar with; but the
8986: actual positions in the line are standard Fortran.
8987:
8988: The text used to display the column ruler is the value of the variable
8989: @code{fortran-comment-ruler}. By changing this variable, you can change
8990: the display.
8991:
8992: @kindex C-c C-w (Fortran mode)
8993: @findex fortran-window-create
8994: For even more help, use @kbd{C-c C-w} (@code{fortran-window-create}), a
8995: command which splits the current window horizontally, making a window 72
8996: columns wide. By editing in this window you can immediately see when you
8997: make a line too wide to be correct Fortran.
8998:
8999: @node Fortran Abbrev,, Fortran Columns, Fortran
9000: @subsection Fortran Keyword Abbrevs
9001:
9002: Fortran mode provides many built-in abbrevs for common keywords and
9003: declarations. These are the same sort of abbrev that you can define
9004: yourself. To use them, you must turn on Abbrev mode. @pxref{Abbrevs}.
9005:
9006: The built-in abbrevs are unusual in one way: they all start with a
9007: semicolon. You cannot normally use semicolon in an abbrev, but Fortran
9008: mode makes this possible by changing the syntax of semicolon to ``word
9009: constituent''.
9010:
9011: For example, one built-in Fortran abbrev is @samp{;c} for
9012: @samp{continue}. If you insert @samp{;c} and then insert a punctuation
9013: character such as a space or a newline, the @samp{;c} will change
9014: automatically to @samp{continue}, provided Abbrev mode is enabled.@refill
9015:
9016: Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
9017: Fortran abbrevs and what they stand for.
9018:
9019: @node Running, Abbrevs, Programs, Top
9020: @chapter Compiling and Testing Programs
9021:
9022: The previous chapter discusses the Emacs commands that are useful for
9023: making changes in programs. This chapter deals with commands that assist
9024: in the larger process of developing and maintaining programs.
9025:
9026: @menu
9027: * Compilation:: Compiling programs in languages other than Lisp
9028: (C, Pascal, etc.)
9029: * Modes: Lisp Modes. Various modes for editing Lisp programs, with
9030: different facilities for running the Lisp programs.
9031: * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
9032: * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
9033: * Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
9034: * Debug: Lisp Debug. Debugging Lisp programs running in Emacs.
9035: * External Lisp:: Communicating through Emacs with a separate Lisp.
9036: @end menu
9037:
9038: @node Compilation, Lisp Modes, Running, Running
9039: @section Running `make', or Compilers Generally
9040: @cindex inferior process
9041: @cindex make
9042: @cindex compilation errors
9043: @cindex error log
9044:
9045: Emacs can run compilers for noninteractive languages such as C and
9046: Fortran as inferior processes, feeding the error log into an Emacs buffer.
9047: It can also parse the error messages and visit the files in which errors
9048: are found, moving point right to the line where the error occurred.
9049:
9050: @table @kbd
9051: @item M-x compile
9052: Run a compiler asynchronously under Emacs, with error messages to
9053: @samp{*compilation*} buffer.
9054: @item M-x grep
9055: Run @code{grep} asynchronously under Emacs, with matching lines
9056: listed in the buffer named @samp{*compilation*}.
9057: @item M-x kill-compiler
9058: @itemx M-x kill-grep
9059: Kill the running compilation or @code{grep} subprocess.
9060: @item C-x `
9061: Visit the locus of the next compiler error message or @code{grep} match.
9062: @end table
9063:
9064: @findex compile
9065: To run @code{make} or another compiler, do @kbd{M-x compile}. This command
9066: reads a shell command line using the minibuffer, and then executes the
9067: specified command line in an inferior shell with output going to the buffer
9068: named @samp{*compilation*}. The current buffer's default directory is used
9069: as the working directory for the execution of the command; normally,
9070: therefore, the makefile comes from this directory.
9071:
9072: @vindex compile-command
9073: When the shell command line is read, the minibuffer appears containing a
9074: default command line, which is the command you used the last time you did
9075: @kbd{M-x compile}. If you type just @key{RET}, the same command line is used
9076: again. The first @kbd{M-x compile} provides @code{make -k} as the default.
9077: The default is taken from the variable @code{compile-command}; if the
9078: appropriate compilation command for a file is something other than
9079: @code{make -k}, it can be useful to have the file specify a local value for
9080: @code{compile-command} (@pxref{File Variables}).
9081:
9082: Starting a compilation causes the buffer @samp{*compilation*} to be
9083: displayed in another window but not selected. Its mode line tells you
9084: whether compilation is finished, with the word @samp{run} or @samp{exit} inside
9085: the parentheses. You do not have to keep this buffer visible; compilation
9086: continues in any case.
9087:
9088: @findex kill-compilation
9089: To kill the compilation process, do @kbd{M-x kill-compilation}. You will
9090: see that the mode line of the @samp{*compilation*} buffer changes to say
9091: @samp{signal} instead of @samp{run}. Starting a new compilation also kills
9092: any running compilation, as only one can exist at any time. However, this
9093: requires confirmation before actually killing a compilation that is
9094: running.@refill
9095:
9096: @kindex C-x `
9097: @findex next-error
9098: To parse the compiler error messages, type @kbd{C-x `} (@code{next-error}). The
9099: character following the @kbd{C-x} is the grave accent, not the single
9100: quote. This command displays the buffer @samp{*compilation*} in one window
9101: and the buffer in which the next error occurred in another window. Point
9102: in that buffer is moved to the line where the error was found. The
9103: corresponding error message is scrolled to the top of the window in which
9104: @samp{*compilation*} is displayed.
9105:
9106: The first time @kbd{C-x `} is used after the start of a compilation, it
9107: parses all the error messages, visits all the files that have error
9108: messages, and makes markers pointing at the lines that the error messages
9109: refer to. Then it moves to the first error message location. Subsequent
9110: uses of @kbd{C-x `} advance down the data set up by the first use. When
9111: the preparsed error messages are exhausted, the next @kbd{C-x `} checks for
9112: any more error messages that have come in; this is useful if you start
9113: editing the compiler errors while the compilation is still going on. If no
9114: more error messages have come in, @kbd{C-x `} reports an error.
9115:
9116: @kbd{C-u C-x `} discards the preparsed error message data and parses the
9117: @samp{*compilation*} buffer over again, then displaying the first error.
9118: This way, you can process the same set of errors again.
9119:
9120: Instead of running a compiler, you can run @code{grep} and see the lines
9121: on which matches were found. To do this, type @kbd{M-x grep} with an argument
9122: line that contains the same arguments you would give @code{grep} when running
9123: it normally: a @code{grep}-style regexp (usually in singlequotes to quote
9124: the shell's special characters) followed by filenames which may use wildcards.
9125: The output from @code{grep} goes in the @samp{*compilation*} buffer and the
9126: lines that matched can be found with @kbd{C-x `} as if they were compilation
9127: errors.
9128:
9129: Note: a shell is used to run the compile command, but the shell is told
9130: that it should be noninteractive. This means in particular that the shell
9131: starts up with no prompt. If you find your usual shell prompt making an
9132: unsightly appearance in the @samp{*compilation*} buffer, it means you have
9133: made a mistake in your shell's init file (@file{.cshrc} or @file{.shrc} or
9134: @dots{}) by setting the prompt unconditionally. The shell init file should
9135: set the prompt only if there already is a prompt. In @code{csh}, here is
9136: how to do it:
9137:
9138: @example
9139: if ($?prompt) set prompt = ...
9140: @end example
9141:
9142: @node Lisp Modes, Lisp Libraries, Compilation, Running
9143: @section Major Modes for Lisp
9144:
9145: Emacs has four different major modes for Lisp. They are the same in
9146: terms of editing commands, but differ in the commands for executing Lisp
9147: expressions.
9148:
9149: @table @asis
9150: @item Emacs-Lisp mode
9151: The mode for editing source files of programs to run in Emacs Lisp.
9152: This mode defines @kbd{C-M-x} to evaluate the current defun.
9153: @xref{Lisp Libraries}.
9154: @item Lisp Interaction mode
9155: The mode for an interactive session with Emacs Lisp. It defines
9156: @key{LFD} to evaluate the sexp before point and insert its value in the
9157: buffer. @xref{Lisp Interaction}.
9158: @item Lisp mode
9159: The mode for editing source files of programs that run in Lisps other
9160: than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
9161: to an inferior Lisp process. @xref{External Lisp}.
9162: @item Inferior Lisp mode
9163: The mode for an interactive session with an inferior Lisp process.
9164: This mode combines the special features of Lisp mode and Shell mode
9165: (@pxref{Shell Mode}).
9166: @item Scheme mode
9167: Like Lisp mode but for Scheme programs.
9168: @item Inferior Scheme mode
9169: The mode for an interactive session with an inferior Scheme process.
9170: @end table
9171:
9172: @node Lisp Libraries, Lisp Eval, Lisp Modes, Running
9173: @section Libraries of Lisp Code for Emacs
9174: @cindex libraries
9175: @cindex loading Lisp code
9176:
9177: Lisp code for Emacs editing commands is stored in files whose names
9178: conventionally end in @file{.el}. This ending tells Emacs to edit them in
9179: Emacs-Lisp mode (@pxref{Lisp Modes}).
9180:
9181: @menu
9182: * Loading:: Loading libraries of Lisp code into Emacs for use.
9183: * Compiling Libraries:: Compiling a library makes it load and run faster.
9184: * Mocklisp:: Converting Mocklisp to Lisp so GNU Emacs can run it.
9185: @end menu
9186:
9187: @node Loading, Compiling Libraries, Lisp Libraries, Lisp Libraries
9188: @subsection Loading Libraries
9189:
9190: @findex load-file
9191: To execute a file of Emacs Lisp, use @kbd{M-x load-file}. This command
9192: reads a file name using the minibuffer and then executes the contents of
9193: that file as Lisp code. It is not necessary to visit the file first;
9194: in any case, this command reads the file as found on disk, not text in
9195: an Emacs buffer.
9196:
9197: @findex load
9198: @findex load-library
9199: Once a file of Lisp code is installed in the Emacs Lisp library
9200: directories, users can load it using @kbd{M-x load-library}. Programs can
9201: load it by calling @code{load-library}, or with @code{load}, a more primitive
9202: function that is similar but accepts some additional arguments.
9203:
9204: @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
9205: searches a sequence of directories and tries three file names in each
9206: directory. The three names are, first, the specified name with @file{.elc}
9207: appended; second, with @file{.el} appended; third, the specified
9208: name alone. A @file{.elc} file would be the result of compiling the Lisp
9209: file into byte code; it is loaded if possible in preference to the Lisp
9210: file itself because the compiled file will load and run faster.
9211:
9212: Because the argument to @code{load-library} is usually not in itself
9213: a valid file name, file name completion is not available. Indeed, when
9214: using this command, you usually do not know exactly what file name
9215: will be used.
9216:
9217: @vindex load-path
9218: The sequence of directories searched by @kbd{M-x load-library} is
9219: specified by the variable @code{load-path}, a list of strings that are
9220: directory names. The default value of the list contains the directory where
9221: the Lisp code for Emacs itself is stored. If you have libraries of
9222: your own, put them in a single directory and add that directory
9223: to @code{load-path}. @code{nil} in this list stands for the current default
9224: directory, but it is probably not a good idea to put @code{nil} in the
9225: list. If you find yourself wishing that @code{nil} were in the list,
9226: most likely what you really want to do is use @kbd{M-x load-file}
9227: this once.
9228:
9229: @cindex autoload
9230: Often you do not have to give any command to load a library, because the
9231: commands defined in the library are set up to @dfn{autoload} that library.
9232: Running any of those commands causes @code{load} to be called to load the
9233: library; this replaces the autoload definitions with the real ones from the
9234: library.
9235:
9236: If autoloading a file does not finish, either because of an error or
9237: because of a @kbd{C-g} quit, all function definitions made by the file are
9238: undone automatically. So are any calls to @code{provide}. As a consequence,
9239: if you use one of the autoloadable commands again, the entire file will be
9240: loaded a second time. This prevents problems where the command is no
9241: longer autoloading but it works wrong because not all the file was loaded.
9242: Function definitions are undone only for autoloading; explicit calls to
9243: @code{load} do not undo anything if loading is not completed.
9244:
9245: @node Compiling Libraries, Mocklisp, Loading, Lisp Libraries
9246: @subsection Compiling Libraries
9247:
9248: @cindex byte code
9249: Emacs Lisp code can be compiled into byte-code which loads faster,
9250: takes up less space when loaded, and executes faster.
9251:
9252: @findex byte-compile-file
9253: The way to make a byte-code compiled file from an Emacs-Lisp source file
9254: is with @kbd{M-x byte-compile-file}. The default argument for this
9255: function is the file visited in the current buffer. It reads the specified
9256: file, compiles it into byte code, and writes an output file whose name is
9257: made by appending @file{c} to the input file name. Thus, the file
9258: @file{rmail.el} would be compiled into @file{rmail.elc}.
9259:
9260: @findex byte-recompile-directory
9261: To recompile the changed Lisp files in a directory, use @kbd{M-x
9262: byte-recompile-directory}. Specify just the directory name as an argument.
9263: Each @file{.el} file that has been byte-compiled before is byte-compiled
9264: again if it has changed since the previous compilation. A numeric argument
9265: to this command tells it to offer to compile each @file{.el} file that has
9266: not already been compiled. You must answer @kbd{y} or @kbd{n} to each
9267: offer.
9268:
9269: @findex batch-byte-compile
9270: Emacs can be invoked noninteractively from the shell to do byte compilation
9271: with the aid of the function @code{batch-byte-compile}. In this case,
9272: the files to be compiled are specified with command-line arguments.
9273: Use a shell command of the form
9274:
9275: @example
9276: emacs -batch -f batch-byte-compile @var{files}...
9277: @end example
9278:
9279: Directory names may also be given as arguments;
9280: @code{byte-recompile-directory} is invoked (in effect) on each such directory.
9281: @code{batch-byte-compile} uses all the remaining command-line arguments as
9282: file or directory names, then kills the Emacs process.
9283:
9284: @findex disassemble
9285: @kbd{M-x disassemble} explains the result of byte compilation. Its
9286: argument is a function name. It displays the byte-compiled code in a help
9287: window in symbolic form, one instruction per line. If the instruction
9288: refers to a variable or constant, that is shown too.
9289:
9290: @node Mocklisp,,Compiling Libraries,Lisp Libraries
9291: @subsection Converting Mocklisp to Lisp
9292:
9293: @cindex mocklisp
9294: @findex convert-mocklisp-buffer
9295: GNU Emacs can run Mocklisp files by converting them to Emacs Lisp first.
9296: To convert a Mocklisp file, visit it and then type @kbd{M-x
9297: convert-mocklisp-buffer}. Then save the resulting buffer of Lisp file in a
9298: file whose name ends in @file{.el} and use the new file as a Lisp library.
9299:
9300: It does not currently work to byte-compile converted Mocklisp code.
9301: This is because converted Mocklisp code uses some special Lisp features
9302: to deal with Mocklisp's incompatible ideas of how arguments are evaluated
9303: and which values signify ``true'' or ``false''.
9304:
9305: @node Lisp Eval, Lisp Debug, Lisp Libraries, Running
9306: @section Evaluating Emacs-Lisp Expressions
9307: @cindex Emacs-Lisp mode
9308:
9309: @findex emacs-lisp-mode
9310: Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp
9311: mode; this will happen automatically for file names ending in @file{.el}.
9312: By contrast, Lisp mode itself is used for editing Lisp programs intended
9313: for other Lisp systems. Emacs-Lisp mode can be selected with the command
9314: @kbd{M-x emacs-lisp-mode}.
9315:
9316: For testing of Lisp programs to run in Emacs, it is useful to be able to
9317: evaluate part of the program as it is found in the Emacs buffer. For
9318: example, after changing the text of a Lisp function definition, evaluating
9319: the definition installs the change for future calls to the function.
9320: Evaluation of Lisp expressions is also useful in any kind of editing task
9321: for invoking noninteractive functions (functions that are not commands).
9322:
9323: @table @kbd
9324: @item M-@key{ESC}
9325: Read a Lisp expression in the minibuffer, evaluate it, and print the
9326: value in the minibuffer (@code{eval-expression}).
9327: @item C-x C-e
9328: Evaluate the Lisp expression before point, and print the value in the
9329: minibuffer (@code{eval-last-sexp}).
9330: @item C-M-x
9331: Evaluate the defun containing or after point, and print the value in
9332: the minibuffer (@code{eval-defun}).
9333: @item M-x eval-region
9334: Evaluate all the Lisp expressions in the region.
9335: @item M-x eval-current-buffer
9336: Evaluate all the Lisp expressions in the buffer.
9337: @end table
9338:
9339: @kindex M-ESC
9340: @findex eval-expression
9341: @kbd{M-@key{ESC}} (@code{eval-expression}) is the most basic command for evaluating
9342: a Lisp expression interactively. It reads the expression using the
9343: minibuffer, so you can execute any expression on a buffer regardless of
9344: what the buffer contains. When the expression is evaluated, the current
9345: buffer is once again the buffer that was current when @kbd{M-@key{ESC}} was
9346: typed.
9347:
9348: @kbd{M-@key{ESC}} can easily confuse users who do not understand it,
9349: especially on keyboards with autorepeat where it can result from holding
9350: down the @key{ESC} key for too long. Therefore, @code{eval-expression} is
9351: normally a disabled command. Attempting to use this command asks for
9352: confirmation and gives you the option of enabling it; once you enable the
9353: command, confirmation will no longer be required for it.
9354: @xref{Disabling}.@refill
9355:
9356: @kindex C-M-x
9357: @findex eval-defun
9358: In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the function @code{eval-defun},
9359: which parses the defun containing or following point as a Lisp expression
9360: and evaluates it. The value is printed in the echo area. This command is
9361: convenient for installing in the Lisp environment changes that you have
9362: just made in the text of a function definition.
9363:
9364: @kindex C-x C-e
9365: @findex eval-last-sexp
9366: The command @kbd{C-x C-e} (@code{eval-last-sexp}) performs a similar job
9367: but is available in all major modes, not just Emacs-Lisp mode. It finds
9368: the sexp before point, reads it as a Lisp expression, evaluates it, and
9369: prints the value in the echo area. It is sometimes useful to type in an
9370: expression and then, with point still after it, type @kbd{C-x C-e}.
9371:
9372: If @kbd{C-M-x} or @kbd{C-x C-e} is given a numeric argument, it prints the value
9373: by insertion into the current buffer at point, rather than in the echo
9374: area. The argument value does not matter.
9375:
9376: @findex eval-region
9377: @findex eval-current-buffer
9378: The most general command for evaluating Lisp expressions from a buffer is
9379: @code{eval-region}. @kbd{M-x eval-region} parses the text of the region as one or
9380: more Lisp expressions, evaluating them one by one. @kbd{M-x eval-current-buffer}
9381: is similar but evaluates the entire buffer. This is a reasonable way to
9382: install the contents of a file of Lisp code that you are just ready to
9383: test. After finding and fixing a bug, use @kbd{C-M-x} on each function
9384: that you change, to keep the Lisp world in step with the source file.
9385:
9386: @node Lisp Debug, Lisp Interaction, Lisp Eval, Running
9387: @section The Emacs-Lisp Debugger
9388: @cindex debugger
9389:
9390: @vindex debug-on-error
9391: @vindex debug-on-quit
9392: GNU Emacs contains a debugger for Lisp programs executing inside it.
9393: This debugger is normally not used; many commands frequently get Lisp
9394: errors when invoked in inappropriate contexts (such as @kbd{C-f} at the end
9395: of the buffer) and it would be very unpleasant for that to enter a special
9396: debugging mode. When you want to make Lisp errors invoke the debugger, you
9397: must set the variable @code{debug-on-error} to non-@code{nil}. Quitting
9398: with @kbd{C-g} is not considered an error, and @code{debug-on-error} has no
9399: effect on the handling of @kbd{C-g}. However, if you set
9400: @code{debug-on-quit} non-@code{nil}, @kbd{C-g} will invoke the debugger.
9401: This can be useful for debugging an infinite loop; type @kbd{C-g} once the
9402: loop has had time to reach its steady state. @code{debug-on-quit} has no
9403: effect on errors.@refill
9404:
9405: @findex debug-on-entry
9406: @findex cancel-debug-on-entry
9407: @findex debug
9408: You can also cause the debugger to be entered when a specified function
9409: is called, or at a particular place in Lisp code. Use @kbd{M-x
9410: debug-on-entry} with argument @var{fun-name} to cause function
9411: @var{fun-name} to enter the debugger as soon as it is called. Use
9412: @kbd{M-x cancel-debug-on-entry} to make the function stop entering the
9413: debugger when called. (Redefining the function also does this.) To enter
9414: the debugger from some other place in Lisp code, you must insert the
9415: expression @code{(debug)} there and install the changed code with
9416: @kbd{C-M-x}. @xref{Lisp Eval}.@refill
9417:
9418: When the debugger is entered, it displays the previously selected buffer
9419: in one window and a buffer named @samp{*Backtrace*} in another window. The
9420: backtrace buffer contains one line for each level of Lisp function
9421: execution currently going on. At the beginning of this buffer is a message
9422: describing the reason that the debugger was invoked (such as, what error
9423: message if it was invoked due to an error).
9424:
9425: The backtrace buffer is read-only, and is in a special major mode,
9426: Backtrace mode, in which letters are defined as debugger commands. The
9427: usual Emacs editing commands are available; you can switch windows to
9428: examine the buffer that was being edited at the time of the error, and you
9429: can also switch buffers, visit files, and do any other sort of editing.
9430: However, the debugger is a recursive editing level (@pxref{Recursive Edit})
9431: and it is wise to go back to the backtrace buffer and exit the debugger
9432: officially when you don't want to use it any more. Exiting the debugger
9433: kills the backtrace buffer.
9434:
9435: @cindex current stack frame
9436: The contents of the backtrace buffer show you the functions that are
9437: executing and the arguments that were given to them. It has the additional
9438: purpose of allowing you to specify a stack frame by moving point to the line
9439: describing that frame. The frame whose line point is on is considered the
9440: @dfn{current frame}. Some of the debugger commands operate on the current
9441: frame. Debugger commands are mainly used for stepping through code an
9442: expression at a time. Here is a list of them.
9443:
9444: @table @kbd
9445: @item c
9446: Exit the debugger and continue execution. In most cases, execution of
9447: the program continues as if the debugger had never been entered (aside
9448: from the effect of any variables or data structures you may have
9449: changed while inside the debugger). This includes entry to the
9450: debugger due to function entry or exit, explicit invocation, quitting
9451: or certain errors. Most errors cannot be continued; trying to
9452: continue one of them causes the same error to occur again.
9453: @item d
9454: Continue execution, but enter the debugger the next time a Lisp
9455: function is called. This allows you to step through the
9456: subexpressions of an expression, seeing what values the subexpressions
9457: compute and what else they do.
9458:
9459: The stack frame made for the function call which enters the debugger
9460: in this way will be flagged automatically for the debugger to be called
9461: when the frame is exited. You can use the @kbd{u} command to cancel
9462: this flag.
9463: @item b
9464: Set up to enter the debugger when the current frame is exited. Frames
9465: that will invoke the debugger on exit are flagged with stars.
9466: @item u
9467: Don't enter the debugger when the current frame is exited. This
9468: cancels a @kbd{b} command on that frame.
9469: @item e
9470: Read a Lisp expression in the minibuffer, evaluate it, and print the
9471: value in the echo area. This is the same as the command @kbd{M-@key{ESC}},
9472: except that @kbd{e} is not normally disabled like @kbd{M-@key{ESC}}.
9473: @item q
9474: Terminate the program being debugged; return to top-level Emacs
9475: command execution.
9476:
9477: If the debugger was entered due to a @kbd{C-g} but you really want
9478: to quit, not to debug, use the @kbd{q} command.
9479: @item r
9480: Return a value from the debugger. The value is computed by reading an
9481: expression with the minibuffer and evaluating it.
9482:
9483: The value returned by the debugger makes a difference when the debugger
9484: was invoked due to exit from a Lisp call frame (as requested with @kbd{b});
9485: then the value specified in the @kbd{r} command is used as the value of
9486: that frame.
9487:
9488: The debugger's return value also matters with many errors. For example,
9489: @code{wrong-type-argument} errors will use the debugger's return value
9490: instead of the invalid argument; @code{no-catch} errors will use the
9491: debugger value as a throw tag instead of the tag that was not found.
9492: If an error was signaled by calling the Lisp function @code{signal},
9493: the debugger's return value is returned as the value of @code{signal}.
9494: @end table
9495:
9496: @node Lisp Interaction, External Lisp, Lisp Debug, Running
9497: @section Lisp Interaction Buffers
9498:
9499: The buffer @samp{*scratch*} which is selected when Emacs starts up is
9500: provided for evaluating Lisp expressions interactively inside Emacs. Both
9501: the expressions you evaluate and their output goes in the buffer.
9502:
9503: The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
9504: is the same as Emacs-Lisp mode except for one command, @key{LFD}. In
9505: Emacs-Lisp mode, @key{LFD} is an indentation command, as usual. In Lisp
9506: Interaction mode, @key{LFD} is bound to @code{eval-print-last-sexp}. This
9507: function reads the Lisp expression before point, evaluates it, and inserts
9508: the value in printed representation before point.
9509:
9510: Thus, the way to use the @samp{*scratch*} buffer is to insert Lisp expressions
9511: at the end, ending each one with @key{LFD} so that it will be evaluated.
9512: The result is a complete typescript of the expressions you have evaluated
9513: and their values.
9514:
9515: @findex lisp-interaction-mode
9516: The rationale for this feature is that Emacs must have a buffer when it
9517: starts up, but that buffer is not useful for editing files since a new
9518: buffer is made for every file that you visit. The Lisp interpreter
9519: typescript is the most useful thing I can think of for the initial buffer
9520: to do. @kbd{M-x lisp-interaction-mode} will put any buffer in Lisp
9521: Interaction mode.
9522:
9523: @node External Lisp,, Lisp Interaction, Running
9524: @section Running an External Lisp
9525:
9526: Emacs has facilities for running programs in other Lisp systems. You can
9527: run a Lisp process as an inferior of Emacs, and pass expressions to it to
9528: be evaluated. You can also pass changed function definitions directly from
9529: the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
9530: process.
9531:
9532: @findex run-lisp
9533: To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs the
9534: program named @code{lisp}, the same program you would run by typing
9535: @code{lisp} as a shell command, with both input and output going through an
9536: Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal output''
9537: from Lisp will go into the buffer, advancing point, and any ``terminal
9538: input'' for Lisp comes from text in the buffer. To give input to Lisp, go
9539: to the end of the buffer and type the input, terminated by @key{RET}. The
9540: @samp{*lisp*} buffer is in Inferior Lisp mode, a mode which has all the
9541: special characteristics of Lisp mode and Shell mode (@pxref{Shell Mode}).
9542:
9543: @findex lisp-mode
9544: For the source files of programs to run in external Lisps, use Lisp mode.
9545: This mode can be selected with @kbd{M-x lisp-mode}, and is used automatically
9546: for files whose names end in @file{.l} or @file{.lisp}, as most Lisp
9547: systems usually expect.
9548:
9549: @kindex C-M-x
9550: @findex lisp-send-defun
9551: When you edit a function in a Lisp program you are running, the easiest
9552: way to send the changed definition to the inferior Lisp process is the key
9553: @kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-send-defun},
9554: which finds the defun around or following point and sends it as input to
9555: the Lisp process. (Emacs can send input to any inferior process regardless
9556: of what buffer is current.)
9557:
9558: Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs
9559: to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
9560: programs to be run in Emacs): in both modes it has the effect of installing
9561: the function definition that point is in, but the way of doing so is
9562: different according to where the relevant Lisp environment is found.
9563: @xref{Lisp Modes}.
9564:
9565: @node Abbrevs, Picture, Running, Top
9566: @chapter Abbrevs
9567: @cindex abbrevs
9568: @cindex expansion (of abbrevs)
9569:
9570: An @dfn{abbrev} is a word which @dfn{expands}, if you insert it, into some
9571: different text. Abbrevs are defined by the user to expand in specific
9572: ways. For example, you might define @samp{foo} as an abbrev expanding to
9573: @samp{find outer otter}. With this abbrev defined, you would be able to
9574: get @samp{find outer otter } into the buffer by typing @kbd{f o o @key{SPC}}.
9575:
9576: @findex abbrev-mode
9577: @vindex abbrev-mode
9578: Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
9579: Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
9580: but they do not expand until Abbrev mode is enabled again. The command
9581: @kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
9582: turns Abbrev mode on if the argument is positive, off otherwise.
9583: @xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is
9584: on when the variable is non-@code{nil}. The variable @code{abbrev-mode}
9585: automatically becomes local to the current buffer when it is set.
9586:
9587: Abbrev definitions can be @dfn{mode-specific}---active only in one major
9588: mode. Abbrevs can also have @dfn{global} definitions that are active in
9589: all major modes. The same abbrev can have a global definition and various
9590: mode-specific definitions for different major modes. A mode specific
9591: definition for the current major mode overrides a global definition.
9592:
9593: Abbrevs can be defined interactively during the editing session. Lists
9594: of abbrev definitions can also be saved in files and reloaded in later
9595: sessions. Some users keep extensive lists of abbrevs that they load in
9596: every session.
9597:
9598: A second kind of abbreviation facility is called the @dfn{dynamic
9599: expansion}. Dynamic abbrev expansion happens only when you give an
9600: explicit command and the result of the expansion depends only on the
9601: current contents of the buffer. @xref{Dynamic Abbrevs}.
9602:
9603: @menu
9604: * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
9605: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
9606: * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
9607: * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
9608: * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
9609: @end menu
9610:
9611: @node Defining Abbrevs, Expanding Abbrevs, Abbrevs, Abbrevs
9612: @section Defining Abbrevs
9613:
9614: @table @kbd
9615: @item C-x +
9616: Define an abbrev to expand into some text before point
9617: (@code{add-global-abbrev}).
9618: @item C-x C-a
9619: Similar, but define an abbrev available only in the current major mode
9620: (@code{add-mode-abbrev}).
9621: @item C-x -
9622: Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
9623: @item C-x C-h
9624: Define a word in the buffer as a mode-specific abbrev
9625: (@code{inverse-add-mode-abbrev}).
9626: @item M-x kill-all-abbrevs
9627: After this command, there are no abbrev definitions in effect.
9628: @end table
9629:
9630: @kindex C-x +
9631: @findex add-global-abbrev
9632: The usual way to define an abbrev is to enter the text you want the
9633: abbrev to expand to, position point after it, and type @kbd{C-x +}
9634: (@code{add-global-abbrev}). This reads the abbrev itself using the
9635: minibuffer, and then defines it as an abbrev for one or more words before
9636: point. Use a numeric argument to say how many words before point should be
9637: taken as the expansion. For example, to define the abbrev @samp{foo} as
9638: mentioned above, insert the text @samp{find outer otter} and then type
9639: @kbd{C-u 3 C-x + f o o @key{RET}}.
9640:
9641: An argument of zero to @kbd{C-x +} means to use the contents of the
9642: region as the expansion of the abbrev being defined.
9643:
9644: @kindex C-x C-a
9645: @findex add-mode-abbrev
9646: The command @kbd{C-x C-a} (@code{add-mode-abbrev}) is similar, but
9647: defines a mode-specific abbrev. Mode specific abbrevs are active only in a
9648: particular major mode. @kbd{C-x C-a} defines an abbrev for the major mode
9649: in effect at the time @kbd{C-x C-a} is typed. The arguments work the same
9650: as for @kbd{C-x +}.
9651:
9652: @kindex C-x -
9653: @findex inverse-add-global-abbrev
9654: @kindex C-x C-h
9655: @findex inverse-add-mode-abbrev
9656: If the text of the abbrev you want is already in the buffer instead of
9657: the expansion, use command @kbd{C-x -} (@code{inverse-add-global-abbrev})
9658: instead of @kbd{C-x +}, or use @kbd{C-x C-h}
9659: (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x C-a}. These commands
9660: are called ``inverse'' because they invert the meaning of the argument
9661: found in the buffer and the argument read using the minibuffer.@refill
9662:
9663: To change the definition of an abbrev, just add the new definition. You
9664: will be asked to confirm if the abbrev has a prior definition. To remove
9665: an abbrev definition, give a negative argument to @kbd{C-x +} or @kbd{C-x
9666: C-a}. You must choose the command to specify whether to kill a global
9667: definition or a mode-specific definition for the current mode, since those
9668: two definitions are independent for one abbrev.
9669:
9670: @findex kill-all-abbrevs
9671: @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there are.
9672:
9673: @node Expanding Abbrevs, Editing Abbrevs, Defining Abbrevs, Abbrevs
9674: @section Controlling Abbrev Expansion
9675:
9676: An abbrev expands whenever it is present in the buffer just before point
9677: and a self-inserting punctuation character (@key{SPC}, comma, etc.@:) is
9678: typed. Most often the way an abbrev is used is to insert the abbrev
9679: followed by punctuation.
9680:
9681: @vindex abbrev-all-caps
9682: Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
9683: outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
9684: @samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
9685: variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first
9686: of the two expansions).@refill
9687:
9688: These two commands are used to control abbrev expansion:
9689:
9690: @table @kbd
9691: @item M-'
9692: Separate a prefix from a following abbrev to be expanded
9693: (@code{abbrev-prefix-mark}).
9694: @item C-x '
9695: @findex expand-abbrev
9696: Expand the abbrev before point (@code{expand-abbrev}).
9697: This is effective even when Abbrev mode is not enabled.
9698: @item M-x unexpand-abbrev
9699: Undo last abbrev expansion.
9700: @item M-x expand-region-abbrevs
9701: Expand some or all abbrevs found in the region.
9702: @end table
9703:
9704: @kindex M-'
9705: @findex abbrev-prefix-mark
9706: You may wish to expand an abbrev with a prefix attached; for example, if
9707: @samp{cnst} expands into @samp{construction}, you might want to use it to
9708: enter @samp{reconstruction}. It does not work to type @kbd{recnst},
9709: because that is not necessarily a defined abbrev. What does work is to use
9710: the command @kbd{M-'} (@code{abbrev-prefix-mark}) in between the prefix
9711: @samp{re} and the abbrev @samp{cnst}. First, insert @samp{re}. Then type
9712: @kbd{M-'}; this inserts a minus sign in the buffer to indicate that it has
9713: done its work. Then insert the abbrev @samp{cnst}; the buffer now contains
9714: @samp{re-cnst}. Now insert a punctuation character to expand the abbrev
9715: @samp{cnst} into @samp{construction}. The minus sign is deleted at this
9716: point, because @kbd{M-'} left word for this to be done. The resulting text
9717: is the desired @samp{reconstruction}.@refill
9718:
9719: If you actually want the text of the abbrev in the buffer, rather than
9720: its expansion, you can accomplish this by inserting the following
9721: punctuation with @kbd{C-q}. Thus, @kbd{foo C-q -} leaves @samp{foo-} in the
9722: buffer.
9723:
9724: @findex unexpand-abbrev
9725: If you expand an abbrev by mistake, you can undo the expansion (replace
9726: the expansion by the original abbrev text) with @kbd{M-x unexpand-abbrev}.
9727: @kbd{C-_} (@code{undo}) can also be used to undo the expansion; but first
9728: it will undo the insertion of the following punctuation character!
9729:
9730: @findex expand-region-abbrevs
9731: @kbd{M-x expand-region-abbrevs} searches through the region for defined
9732: abbrevs, and for each one found offers to replace it with its expansion.
9733: This command is useful if you have typed in text using abbrevs but forgot
9734: to turn on Abbrev mode first. It may also be useful together with a
9735: special set of abbrev definitions for making several global replacements at
9736: once. This command is effective even if Abbrev mode is not enabled.
9737:
9738: @node Editing Abbrevs, Saving Abbrevs, Expanding Abbrevs, Abbrevs
9739: @section Examining and Editing Abbrevs
9740:
9741: @table @kbd
9742: @item M-x list-abbrevs
9743: Print a list of all abbrev definitions.
9744: @item M-x edit-abbrevs
9745: Edit a list of abbrevs; you can add, alter or remove definitions.
9746: @end table
9747:
9748: @findex list-abbrevs
9749: The output from @kbd{M-x list-abbrevs} looks like this:
9750:
9751: @example
9752: (lisp-mode-abbrev-table)
9753: "dk" 0 "define-key"
9754: (global-abbrev-table)
9755: "dfn" 0 "definition"
9756: @end example
9757:
9758: @noindent
9759: (Some blank lines of no semantic significance, and some other abbrev
9760: tables, have been omitted.)
9761:
9762: A line containing a name in parentheses is the header for abbrevs in a
9763: particular abbrev table; @code{global-abbrev-table} contains all the global
9764: abbrevs, and the other abbrev tables that are named after major modes
9765: contain the mode-specific abbrevs.
9766:
9767: Within each abbrev table, each nonblank line defines one abbrev. The
9768: word at the beginning is the abbrev. The number that appears is the number
9769: of times the abbrev has been expanded. Emacs keeps track of this to help
9770: you see which abbrevs you actually use, in case you decide to eliminate
9771: those that you don't use often. The string at the end of the line is the
9772: expansion.
9773:
9774: @findex edit-abbrevs
9775: @kindex C-c C-c (Edit Abbrevs)
9776: @findex edit-abbrevs-redefine
9777: @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
9778: definitions by editing a list of them in an Emacs buffer. The list has the
9779: same format described above. The buffer of abbrevs is called @samp{*Abbrevs*},
9780: and is in Edit-Abbrevs mode. This mode redefines the key @kbd{C-c C-c} to
9781: install the abbrev definitions as specified in the buffer. The command
9782: that does this is @code{edit-abbrevs-redefine}. Any abbrevs not described
9783: in the buffer are eliminated when this is done.
9784:
9785: @code{edit-abbrevs} is actually the same as @code{list-abbrevs} except
9786: that it selects the buffer @samp{*Abbrevs*} whereas @code{list-abbrevs}
9787: merely displays it in another window.
9788:
9789: @node Saving Abbrevs, Dynamic Abbrevs, Editing Abbrevs, Abbrevs
9790: @section Saving Abbrevs
9791:
9792: These commands allow you to keep abbrev definitions between editing
9793: sessions.
9794:
9795: @table @kbd
9796: @item M-x write-abbrev-file
9797: Write a file describing all defined abbrevs.
9798: @item M-x read-abbrev-file
9799: Read such a file and define abbrevs as specified there.
9800: @item M-x quietly-read-abbrev-file
9801: Similar but do not display a message about what is going on.
9802: @item M-x define-abbrevs
9803: Define abbrevs from buffer.
9804: @item M-x insert-abbrevs
9805: Insert all abbrevs and their expansions into the buffer.
9806: @end table
9807:
9808: @findex write-abbrev-file
9809: @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and
9810: writes a description of all current abbrev definitions into that file. The
9811: text stored in the file looks like the output of @kbd{M-x list-abbrevs}.
9812: This is used to save abbrev definitions for use in a later session.
9813:
9814: @findex read-abbrev-file
9815: @findex quietly-read-abbrev-file
9816: @vindex abbrev-file-name
9817: @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and
9818: reads the file, defining abbrevs according to the contents of the file.
9819: @kbd{M-x quietly-read-abbrev-file} is the same except that it does not
9820: display a message in the echo area saying that it is doing its work; it
9821: is actually useful primarily in the @file{.emacs} file. If an empty
9822: argument is given to either of these functions, the file name used is the
9823: value of the variable @code{abbrev-file-name}, which is by default
9824: @code{"~/.abbrev_defs"}.
9825:
9826: @vindex save-abbrevs
9827: Emacs will offer to save abbrevs automatically if you have changed any of
9828: them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
9829: C-c}). This feature can be inhibited by setting the variable
9830: @code{save-abbrevs} to @code{nil}.
9831:
9832: @findex insert-abbrevs
9833: @findex define-abbrevs
9834: The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
9835: similar to the previous commands but work on text in an Emacs buffer.
9836: @kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
9837: describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
9838: the entire current buffer and defines abbrevs accordingly.@refill
9839:
9840: @node Dynamic Abbrevs,, Saving Abbrevs, Abbrevs
9841: @section Dynamic Abbrev Expansion
9842:
9843: The abbrev facility described above operates automatically as you insert
9844: text, but all abbrevs must be defined explicitly. By contrast,
9845: @dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined
9846: automatically from the contents of the buffer, but dynamic abbrev expansion
9847: happens only when you request it explicitly.
9848:
9849: @kindex M-/
9850: @findex dabbrev-expand
9851: @table @kbd
9852: @item M-/
9853: Expand the word in the buffer before point as a @dfn{dynamic abbrev},
9854: by searching in the buffer for words starting with that abbreviation
9855: (@code{dabbrev-expand}).
9856: @end table
9857:
9858: For example, if the buffer contains @samp{does this follow } and you type
9859: @kbd{f o M-/}, the effect is to insert @samp{follow} because that is the
9860: last word in the buffer that starts with @samp{fo}. A numeric argument to
9861: @kbd{M-/} says to take the second, third, etc.@: distinct expansion found
9862: looking backward from point. Repeating @kbd{M-/} searches for an
9863: alternative expansion by looking farther back. After the entire buffer
9864: before point has been considered, the buffer after point is searched.
9865:
9866: Dynamic abbrev expansion is completely independent of Abbrev mode; the
9867: expansion of a word with @kbd{M-/} is completely independent of whether it
9868: has a definition as an ordinary abbrev.
9869:
9870: @node Picture, Sending Mail, Abbrevs, Top
9871: @chapter Editing Pictures
9872: @cindex pictures
9873: @findex edit-picture
9874:
9875: If you want to create a picture made out of text characters (for example,
9876: a picture of the division of a register into fields, as a comment in a
9877: program), use the command @code{edit-picture} to enter Picture mode.
9878:
9879: In Picture mode, editing is based on the @dfn{quarter-plane} model of
9880: text, according to which the text characters lie studded on an area that
9881: stretches infinitely far to the right and downward. The concept of the end
9882: of a line does not exist in this model; the most you can say is where the
9883: last nonblank character on the line is found.
9884:
9885: Of course, Emacs really always considers text as a sequence of
9886: characters, and lines really do have ends. But in Picture mode most
9887: frequently-used keys are rebound to commands that simulate the
9888: quarter-plane model of text. They do this by inserting spaces or by
9889: converting tabs to spaces.
9890:
9891: Most of the basic editing commands of Emacs are redefined by Picture mode
9892: to do essentially the same thing but in a quarter-plane way. In addition,
9893: Picture mode defines various keys starting with the @kbd{C-c} prefix to
9894: run special picture editing commands.
9895:
9896: One of these keys, @kbd{C-c C-c}, is pretty important. Often a picture
9897: is part of a larger file that is usually edited in some other major mode.
9898: @kbd{M-x edit-picture} records the name of the previous major mode, and
9899: then you can use the @kbd{C-c C-c} command (@code{picture-mode-exit}) to
9900: restore that mode. @kbd{C-c C-c} also deletes spaces from the ends of
9901: lines, unless given a numeric argument.
9902:
9903: The commands used in Picture mode all work in other modes (provided the
9904: @file{picture} library is loaded), but are not bound to keys except in
9905: Picture mode. Note that the descriptions below talk of moving ``one
9906: column'' and so on, but all the picture mode commands handle numeric
9907: arguments as their normal equivalents do.
9908:
9909: @vindex picture-mode-hook
9910: Turning on Picture mode calls the value of the variable @code{picture-mode-hook}
9911: as a function, with no arguments, if that value exists and is non-@code{nil}.
9912:
9913: @menu
9914: * Basic Picture:: Basic concepts and simple commands of Picture Mode.
9915: * Insert in Picture:: Controlling direction of cursor motion
9916: after "self-inserting" characters.
9917: * Tabs in Picture:: Various features for tab stops and indentation.
9918: * Rectangles in Picture:: Clearing and superimposing rectangles.
9919: @end menu
9920:
9921: @node Basic Picture, Insert in Picture, Picture, Picture
9922: @section Basic Editing in Picture Mode
9923:
9924: @findex picture-forward-column
9925: @findex picture-backward-column
9926: @findex picture-move-down
9927: @findex picture-move-up
9928: Most keys do the same thing in Picture mode that they usually do, but do
9929: it in a quarter-plane style. For example, @kbd{C-f} is rebound to run
9930: @code{picture-forward-column}, which is defined to move point one column to
9931: the right, by inserting a space if necessary, so that the actual end of the
9932: line makes no difference. @kbd{C-b} is rebound to run
9933: @code{picture-backward-column}, which always moves point left one column,
9934: converting a tab to multiple spaces if necessary. @kbd{C-n} and @kbd{C-p}
9935: are rebound to run @code{picture-move-down} and @code{picture-move-up},
9936: which can either insert spaces or convert tabs as necessary to make sure
9937: that point stays in exactly the same column. @kbd{C-e} runs
9938: @code{picture-end-of-line}, which moves to after the last nonblank
9939: character on the line. There is no need to change @kbd{C-a}, as the choice
9940: of screen model does not affect beginnings of lines.@refill
9941:
9942: @findex picture-newline
9943: Insertion of text is adapted to the quarter-plane screen model through
9944: the use of Overwrite mode (@pxref{Minor Modes}). Self-inserting characters
9945: replace existing text, column by column, rather than pushing existing text
9946: to the right. @key{RET} runs @code{picture-newline}, which just moves to
9947: the beginning of the following line so that new text will replace that
9948: line.
9949:
9950: @findex picture-backward-clear-column
9951: @findex picture-clear-column
9952: @findex picture-clear-line
9953: Deletion and killing of text are replaced with erasure. @key{DEL}
9954: (@code{picture-backward-clear-column}) replaces the preceding character
9955: with a space rather than removing it. @kbd{C-d}
9956: (@code{picture-clear-column}) does the same thing in a forward direction.
9957: @kbd{C-k} (@code{picture-clear-line}) really kills the contents of lines,
9958: but does not ever remove the newlines from the buffer.@refill
9959:
9960: @findex picture-open-line
9961: To do actual insertion, you must use special commands. @kbd{C-o}
9962: (@code{picture-open-line}) still creates a blank line, but does so after
9963: the current line; it never splits a line. @kbd{C-M-o}, @code{split-line},
9964: makes sense in Picture mode, so it is not changed. @key{LFD}
9965: (@code{picture-duplicate-line}) inserts below the current line another line
9966: with the same contents.@refill
9967:
9968: @kindex C-c C-d (Picture mode)
9969: @findex delete-char
9970: Real deletion can be done with @kbd{C-w}, or with @kbd{C-c C-d} (which is
9971: defined as @code{delete-char}, as @kbd{C-d} is in other modes), or with one
9972: of the picture rectangle commands (@pxref{Rectangles in Picture}).
9973:
9974: @node Insert in Picture, Tabs in Picture, Basic Picture, Picture
9975: @section Controlling Motion after Insert
9976:
9977: @findex picture-movement-up
9978: @findex picture-movement-down
9979: @findex picture-movement-left
9980: @findex picture-movement-right
9981: @findex picture-movement-nw
9982: @findex picture-movement-ne
9983: @findex picture-movement-sw
9984: @findex picture-movement-se
9985: @kindex C-c < (Picture mode)
9986: @kindex C-c > (Picture mode)
9987: @kindex C-c ^ (Picture mode)
9988: @kindex C-c . (Picture mode)
9989: @kindex C-c ` (Picture mode)
9990: @kindex C-c ' (Picture mode)
9991: @kindex C-c / (Picture mode)
9992: @kindex C-c \ (Picture mode)
9993: Since ``self-inserting'' characters in Picture mode just overwrite and
9994: move point, there is no essential restriction on how point should be moved.
9995: Normally point moves right, but you can specify any of the eight orthogonal
9996: or diagonal directions for motion after a ``self-inserting'' character.
9997: This is useful for drawing lines in the buffer.
9998:
9999: @table @kbd
10000: @item C-c <
10001: Move left after insertion (@code{picture-movement-left}).
10002: @item C-c >
10003: Move right after insertion (@code{picture-movement-right}).
10004: @item C-c ^
10005: Move up after insertion (@code{picture-movement-up}).
10006: @item C-c .
10007: Move down after insertion (@code{picture-movement-down}).
10008: @item C-c `
10009: Move up and left (``northwest'') after insertion @*(@code{picture-movement-nw}).
10010: @item C-c '
10011: Move up and right (``northeast'') after insertion @*
10012: (@code{picture-movement-ne}).
10013: @item C-c /
10014: Move down and left (``southwest'') after insertion
10015: @*(@code{picture-movement-sw}).
10016: @item C-c \
10017: Move down and right (``southeast'') after insertion
10018: @*(@code{picture-movement-se}).
10019: @end table
10020:
10021: @kindex C-c C-f (Picture mode)
10022: @kindex C-c C-b (Picture mode)
10023: @findex picture-motion
10024: @findex picture-motion-reverse
10025: Two motion commands move based on the current Picture insertion
10026: direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
10027: same direction as motion after ``insertion'' currently does, while @kbd{C-c
10028: C-b} (@code{picture-motion-reverse}) moves in the opposite direction.
10029:
10030: @node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
10031: @section Picture Mode Tabs
10032:
10033: @kindex M-TAB
10034: @findex picture-tab-search
10035: @vindex picture-tab-chars
10036: Two kinds of tab-like action are provided in Picture mode.
10037: Context-based tabbing is done with @kbd{M-@key{TAB}}
10038: (@code{picture-tab-search}). With no argument, it moves to a point
10039: underneath the next ``interesting'' character that follows whitespace in
10040: the previous nonblank line. ``Next'' here means ``appearing at a
10041: horizontal position greater than the one point starts out at''. With an
10042: argument, as in @kbd{C-u M-@key{TAB}}, this command moves to the next such
10043: interesting character in the current line. @kbd{M-@key{TAB}} does not
10044: change the text; it only moves point. ``Interesting'' characters are
10045: defined by the variable @code{picture-tab-chars}, which contains a string
10046: whose characters are all considered interesting. Its default value is
10047: @code{"!-~"}.@refill
10048:
10049: @findex picture-tab
10050: @key{TAB} itself runs @code{picture-tab}, which operates based on the
10051: current tab stop settings; it is the Picture mode equivalent of
10052: @code{tab-to-tab-stop}. Normally it just moves point, but with a numeric
10053: argument it clears the text that it moves over.
10054:
10055: @kindex C-c TAB (Picture mode)
10056: @findex picture-set-tab-stops
10057: The context-based and tab-stop-based forms of tabbing are brought
10058: together by the command @kbd{C-c @key{TAB}}, @code{picture-set-tab-stops}.
10059: This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
10060: would consider significant in the current line. The use of this command,
10061: together with @key{TAB}, can get the effect of context-based tabbing. But
10062: @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
10063:
10064: @node Rectangles in Picture,, Tabs in Picture, Picture
10065: @section Picture Mode Rectangle Commands
10066: @cindex rectangle
10067:
10068: Picture mode defines commands for working on rectangular pieces of the
10069: text in ways that fit with the quarter-plane model. The standard rectangle
10070: commands may also be useful (@pxref{Rectangles}).
10071:
10072: @table @kbd
10073: @item C-c C-k
10074: Clear out the region-rectangle (@code{picture-clear-rectangle}). With
10075: argument, kill it.
10076: @item C-c C-w @var{r}
10077: Similar but save rectangle contents in register @var{r} first
10078: (@code{picture-clear-rectangle-to-register}).
10079: @item C-c C-y
10080: Copy last killed rectangle into the buffer by overwriting, with upper
10081: left corner at point (@code{picture-yank-rectangle}). With argument,
10082: insert instead.
10083: @item C-c C-x @var{r}
10084: Similar, but use the rectangle in register @var{r}@*
10085: (@code{picture-yank-rectangle-from-register}).
10086: @end table
10087:
10088: @kindex C-c C-k (Picture mode)
10089: @kindex C-c C-w (Picture mode)
10090: @findex picture-clear-rectangle
10091: @findex picture-clear-rectangle-to-register
10092: The picture rectangle commands @kbd{C-c C-k}
10093: (@code{picture-clear-rectangle}) and @kbd{C-c C-w}
10094: (@code{picture-clear-rectangle-to-register}) differ from the standard
10095: rectangle commands in that they normally clear the rectangle instead of
10096: deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
10097: mode.@refill
10098:
10099: However, deletion of rectangles can be useful in Picture mode, so these
10100: commands delete the rectangle if given a numeric argument.
10101:
10102: @kindex C-c C-y (Picture mode)
10103: @kindex C-c C-x (Picture mode)
10104: @findex picture-yank-rectangle
10105: @findex picture-yank-rectangle-from-register
10106: The Picture mode commands for yanking rectangles differ from the standard
10107: ones in overwriting instead of inserting. This is the same way that
10108: Picture mode insertion of other text is different from other modes.
10109: @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts (by overwriting) the
10110: rectangle that was most recently killed, while @kbd{C-c C-x}
10111: (@code{picture-yank-rectangle-from-register}) does likewise for the
10112: rectangle found in a specified register.
10113:
10114: @node Sending Mail, Rmail, Picture, Top
10115: @chapter Sending Mail
10116: @cindex mail
10117: @cindex message
10118:
10119: To send a message in Emacs, you start by typing a command (@kbd{C-x m})
10120: to select and initialize the @samp{*mail*} buffer. Then you edit the text
10121: and headers of the message in this buffer, and type another command
10122: (@kbd{C-c C-c}) to send the message.
10123:
10124: @table @kbd
10125: @item C-x m
10126: Begin composing a message to send (@code{mail}).
10127: @item C-x 4 m
10128: Likewise, but display the message in another window
10129: (@code{mail-other-window}).
10130: @item C-c C-c
10131: In Mail mode, send the message and switch to another buffer
10132: (@code{mail-send-and-exit}).
10133: @end table
10134:
10135: @kindex C-x m
10136: @findex mail
10137: @kindex C-x 4 m
10138: @findex mail-other-window
10139: The command @kbd{C-x m} (@code{mail}) selects a buffer named
10140: @samp{*mail*} and initializes it with the skeleton of an outgoing message.
10141: @kbd{C-x 4 m} (@code{mail-other-window}) selects the @samp{*mail*} buffer
10142: in a different window, leaving the previous current buffer visible.@refill
10143:
10144: Because the mail composition buffer is an ordinary Emacs buffer, you can
10145: switch to other buffers while in the middle of composing mail, and switch
10146: back later (or never). If you use the @kbd{C-x m} command again when you
10147: have been composing another message but have not sent it, you are asked to
10148: confirm before the old message is erased. If you answer @kbd{n}, the
10149: @samp{*mail*} buffer is left selected with its old contents, so you can
10150: finish the old message and send it. @kbd{C-u C-x m} is another way to do
10151: this. Sending the message marks the @samp{*mail*} buffer ``unmodified'',
10152: which avoids the need for confirmation when @kbd{C-x m} is next used.
10153:
10154: If you are composing a message in the @samp{*mail*} buffer and want to
10155: send another message before finishing the first, rename the @samp{*mail*}
10156: buffer using @kbd{M-x rename-buffer} (@pxref{Misc Buffer}).
10157:
10158: @menu
10159: * Format: Mail Format. Format of the mail being composed.
10160: * Headers: Mail Headers. Details of allowed mail header fields.
10161: * Mode: Mail Mode. Special commands for editing mail being composed.
10162: @end menu
10163:
10164: @node Mail Format, Mail Headers, Sending Mail, Sending Mail
10165: @section The Format of the Mail Buffer
10166:
10167: In addition to the @dfn{text} or contents, a message has @dfn{header
10168: fields} which say who sent it, when, to whom, why, and so on. Some header
10169: fields such as the date and sender are created automatically after the
10170: message is sent. Others, such as the recipient names, must be specified by
10171: you in order to send the message properly.
10172:
10173: Mail mode provides a few commands to help you edit some header fields,
10174: and some are preinitialized in the buffer automatically at times. You can
10175: insert or edit any header fields using ordinary editing commands.
10176:
10177: The line in the buffer that says
10178:
10179: @example
10180: --text follows this line--
10181: @end example
10182:
10183: @vindex mail-header-separator
10184: @noindent
10185: is a special delimiter that separates the headers you have specified from
10186: the text. Whatever follows this line is the text of the message; the
10187: headers precede it. The delimiter line itself does not appear in the
10188: message actually sent. The text used for the delimiter line is controlled
10189: by the variable @code{mail-header-separator}.
10190:
10191: Here is an example of what the headers and text in the @samp{*mail*} buffer
10192: might look like.
10193:
10194: @example
10195: To: rms@@mc
10196: CC: mly@@mc, rg@@oz
10197: Subject: The Emacs Manual
10198: --Text follows this line--
10199: Please ignore this message.
10200: @end example
10201:
10202: @node Mail Headers, Mail Mode, Mail Format, Sending Mail
10203: @section Mail Header Fields
10204: @cindex headers (of mail message)
10205:
10206: There are several header fields you can use in the @samp{*mail*} buffer.
10207: Each header field starts with a field name at the beginning of a line,
10208: terminated by a colon. It does not matter whether you use upper or lower
10209: case in the field name. After the colon and optional whitespace comes the
10210: contents of the field.
10211:
10212: @table @samp
10213: @item To
10214: This field contains the mailing addresses to which the message is
10215: addressed.
10216:
10217: @item Subject
10218: The contents of the @samp{Subject} field should be a piece of text
10219: that says what the message is about. The reason @samp{Subject} fields
10220: are useful is that most mail-reading programs can provide a summary of
10221: messages, listing the subject of each message but not its text.
10222:
10223: @item CC
10224: This field contains additional mailing addresses to send the message
10225: to, but whose readers should not regard the message as addressed to
10226: them.
10227:
10228: @item BCC
10229: This field contains additional mailing addresses to send the message
10230: to, but which should not appear in the header of the message actually
10231: sent.
10232:
10233: @item FCC
10234: This field contains the name of one file (in Unix mail file format) to
10235: which a copy of the message should be appended when the message is
10236: sent.
10237:
10238: @item From
10239: Use the @samp{From} field to say who you are, when the account you are
10240: using to send the mail is not your own. The contents of the
10241: @samp{From} field should be a valid mailing address, since replies
10242: will normally go there.
10243:
10244: @item Reply-To
10245: Use the @samp{Reply-to} field to direct replies to a different
10246: address, not your own. There is no difference between @samp{From} and
10247: @samp{Reply-to} in their effect on where replies go, but they convey a
10248: different meaning to the human who reads the message.
10249:
10250: @item In-Reply-To
10251: This field contains a piece of text describing a message you are
10252: replying to. Some mail systems can use this information to correlate
10253: related pieces of mail. Normally this field is filled in by Rmail
10254: when you are replying to a message in Rmail, and you never need to
10255: think about it (@pxref{Rmail}).
10256: @end table
10257:
10258: @noindent
10259: The @samp{To}, @samp{CC}, @samp{BCC} and @samp{FCC} fields can appear
10260: any number of times, to specify many places to send the message.
10261:
10262: @noindent
10263: The @samp{To}, @samp{CC}, and @samp{BCC} fields can have continuation
10264: lines. All the lines starting with whitespace, following the line on
10265: which the field starts, are considered part of the field. For
10266: example,@refill
10267:
10268: @group
10269: @example
10270: To: foo@@here, this@@there,
10271: me@@gnu.cambridge.mass.usa.earth.spiral3281
10272: @end example
10273: @end group
10274:
10275: @noindent
10276: If you have a @file{~/.mailrc} file, Emacs will scan it for mail aliases
10277: the first time you try to send mail in an Emacs session. Aliases found
10278: in the @samp{To}, @samp{CC}, and @samp{BCC} fields will be expanded where
10279: appropriate.
10280:
10281: @vindex mail-archive-file-name
10282: If the variable @code{mail-archive-file-name} is non-@code{nil}, it should be a
10283: string naming a file; every time you start to edit a message to send,
10284: an @samp{FCC} field will be put in for that file. Unless you remove the
10285: @samp{FCC} field, every message will be written into that file when it is
10286: sent.
10287:
10288: @node Mail Mode,, Mail Headers, Sending Mail
10289: @section Mail Mode
10290:
10291: The major mode used in the @samp{*mail*} buffer is Mail mode, which is
10292: much like Text mode except that various special commands are provided on
10293: the @kbd{C-c} prefix. These commands all have to do specifically with
10294: editing or sending the message.
10295:
10296: @table @kbd
10297: @item C-c C-s
10298: Send the message, and leave the @samp{*mail*} buffer selected
10299: (@code{mail-send}).
10300: @item C-c C-c
10301: Send the message, and select some other buffer (@code{mail-send-and-exit}).
10302: @item C-c C-f C-t
10303: Move to the @samp{To} header field, creating one if there is none
10304: (@code{mail-to}).
10305: @item C-c C-f C-s
10306: Move to the @samp{Subject} header field, creating one if there is
10307: none (@code{mail-subject}).
10308: @item C-c C-f C-c
10309: Move to the @samp{CC} header field, creating one if there is none
10310: (@code{mail-cc}).
10311: @item C-c C-w
10312: Insert the file @file{~/.signature} at the end of the message text
10313: (@code{mail-signature}).
10314: @item C-c C-y
10315: Yank the selected message from Rmail (@code{mail-yank-original}).
10316: This command does nothing unless your command to start sending a
10317: message was issued with Rmail.
10318: @item C-c C-q
10319: Fill all paragraphs of yanked old messages, each individually
10320: (@code{mail-fill-yanked-message}).
10321: @end table
10322:
10323: @kindex C-c C-s (Mail mode)
10324: @kindex C-c C-c (Mail mode)
10325: @findex mail-send
10326: @findex mail-send-and-exit
10327: There are two ways to send the message. @kbd{C-c C-s} (@code{mail-send})
10328: sends the message and marks the @samp{*mail*} buffer unmodified, but leaves
10329: that buffer selected so that you can modify the message (perhaps with new
10330: recipients) and send it again. @kbd{C-c C-c} (@code{mail-send-and-exit})
10331: sends and then deletes the window (if there is another window) or switches
10332: to another buffer. It puts the @samp{*mail*} buffer at the lowest priority
10333: for automatic reselection, since you are finished with using it. This is
10334: the usual way to send the message.
10335:
10336: @kindex C-c C-f C-t (Mail mode)
10337: @findex mail-to
10338: @kindex C-c C-f C-s (Mail mode)
10339: @findex mail-subject
10340: @kindex C-c C-f C-c (Mail mode)
10341: @findex mail-cc
10342: Mail mode provides some other special commands that are useful for
10343: editing the headers and text of the message before you send it. There are
10344: three commands defined to move point to particular header fields, all based
10345: on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). They are
10346: @kbd{C-c C-f C-t} (@code{mail-to}) to move to the @samp{To} field, @kbd{C-c
10347: C-f C-s} (@code{mail-subject}) for the @samp{Subject} field, and @kbd{C-c
10348: C-f C-c} (@code{mail-cc}) for the @samp{CC} field. These fields have
10349: special motion commands because they are the most common fields for the
10350: user to want to edit.
10351:
10352: @kindex C-c C-w (Mail mode)
10353: @findex mail-signature
10354: @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece text at the end of the
10355: message to say more about who you are. The text comes from the file
10356: @file{.signature} in your home directory.
10357:
10358: @kindex C-c C-y (Mail mode)
10359: @findex mail-yank-original
10360: When mail sending is invoked from the Rmail mail reader using an Rmail
10361: command, @kbd{C-c C-y} can be used inside the @samp{*mail*} buffer to insert
10362: the text of the message you are replying to. Normally it indents each line
10363: of that message four spaces and eliminates most header fields. A numeric
10364: argument specifies the number of spaces to indent. An argument of just
10365: @kbd{C-u} says not to indent at all and not to eliminate anything.
10366: @kbd{C-c C-y} always uses the current message from the @samp{RMAIL} buffer,
10367: so you can insert several old messages by selecting one in @samp{RMAIL},
10368: switching to @samp{*mail*} and yanking it, then switching back to
10369: @samp{RMAIL} to select another.@refill
10370:
10371: @kindex C-c C-q (Mail mode)
10372: @findex mail-fill-yanked-message
10373: After using @kbd{C-c C-y}, the command @kbd{C-c C-q} (@code{mail-fill-yanked-message}) can
10374: be used to fill the paragraphs of the yanked old message or messages. One
10375: use of @kbd{C-c C-q} fills all such paragraphs, each one separately.
10376:
10377: @vindex mail-mode-hook
10378: Turning on Mail mode (which @kbd{C-x m} does automatically) calls the
10379: value of @code{text-mode-hook}, if it is not void or @code{nil}, and then calls
10380: the value of @code{mail-mode-hook} if that is not void or @code{nil}.
10381:
10382: @node Rmail, Recursive Edit, Sending Mail, Top
10383: @chapter Reading Mail with Rmail
10384: @cindex Rmail
10385: @cindex message
10386: @findex rmail
10387:
10388: Rmail is an Emacs subsystem for reading and disposing of mail that you
10389: receive. Rmail stores mail messages in files called Rmail files. Reading
10390: the message in an Rmail file is done in a special major mode, Rmail mode,
10391: which redefines most letters to run commands for managing mail. To enter
10392: Rmail, type @kbd{M-x rmail}. This reads your primary mail file, merges
10393: new mail in from your inboxes, displays the first new message, and lets
10394: you begin reading.
10395:
10396: @cindex primary mail file
10397: Using Rmail in the simplest fashion, you have one Rmail file @file{~/RMAIL}
10398: in which all of your mail is saved. It is called your @dfn{primary mail
10399: file}. In more sophisticated usage, you can copy messages into other Rmail
10400: files and then edit those files with Rmail.
10401:
10402: Rmail displays only one message at a time. It is called the @dfn{current
10403: message}. Rmail mode's special commands can do such things as move to
10404: another message, delete the message, copy the message into another file, or
10405: send a reply.
10406:
10407: @cindex message number
10408: Within the Rmail file, messages are arranged sequentially in order
10409: of receipt. They are also assigned consecutive integers as their
10410: @dfn{message numbers}. The number of the current message is displayed
10411: in Rmail's mode line, followed by the total number of messages in the
10412: file. You can move to a message by specifying its message number
10413: using the @kbd{j} key (@pxref{Rmail Motion}).
10414:
10415: @kindex s (Rmail)
10416: @findex rmail-save
10417: Following the usual conventions of Emacs, changes in an Rmail file become
10418: permanent only when the file is saved. You can do this with @kbd{s}
10419: (@code{rmail-save}), which also expunges deleted messages from the file
10420: first (@pxref{Rmail Deletion}). To save the file without expunging, use
10421: @kbd{C-x C-s}. Rmail saves the Rmail file spontaneously when moving new
10422: mail from an inbox file (@pxref{Rmail Inbox}).
10423:
10424: @kindex q (Rmail)
10425: @findex rmail-quit
10426: You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and saves the
10427: Rmail file and then switches to another buffer. But there is no need to
10428: `exit' formally. If you switch from Rmail to editing in other buffers, and
10429: never happen to switch back, you have exited. Just make sure to save the
10430: Rmail file eventually (like any other file you have changed). @kbd{C-x s}
10431: is a good enough way to do this (@pxref{Saving}).
10432:
10433: @menu
10434: * Scroll: Rmail Scrolling. Scrolling through a message.
10435: * Motion: Rmail Motion. Moving to another message.
10436: * Deletion: Rmail Deletion. Deleting and expunging messages.
10437: * Inbox: Rmail Inbox. How mail gets into the Rmail file.
10438: * Files: Rmail Files. Using multiple Rmail files.
10439: * Output: Rmail Output. Copying message out to files.
10440: * Labels: Rmail Labels. Classifying messages by labeling them.
10441: * Summary: Rmail Summary. Summaries show brief info on many messages.
10442: * Reply: Rmail Reply. Sending replies to messages you are viewing.
10443: * Editing: Rmail Editing. Editing message text and headers in Rmail.
10444: * Digest: Rmail Digest. Extracting the messages from a digest message.
10445: @end menu
10446:
10447: @node Rmail Scrolling, Rmail Motion, Rmail, Rmail
10448: @section Scrolling Within a Message
10449:
10450: When Rmail displays a message that does not fit on the screen, it is
10451: necessary to scroll through it. This could be done with @kbd{C-v}, @kbd{M-v}
10452: and @kbd{M-<}, but in Rmail scrolling is so frequent that it deserves to be
10453: easier to type.
10454:
10455: @table @kbd
10456: @item @key{SPC}
10457: Scroll forward (@code{scroll-up}).
10458: @item @key{DEL}
10459: Scroll backward (@code{scroll-down}).
10460: @item .
10461: Scroll to start of message (@code{rmail-beginning-of-message}).
10462: @end table
10463:
10464: @kindex SPC (Rmail)
10465: @kindex DEL (Rmail)
10466: Since the most common thing to do while reading a message is to scroll
10467: through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
10468: @kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down})
10469:
10470: @kindex . (Rmail)
10471: @findex rmail-beginning-of-message
10472: The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
10473: beginning of the selected message. This is not quite the same as @kbd{M-<}:
10474: for one thing, it does not set the mark; for another, it resets the buffer
10475: boundaries to the current message if you have changed them.
10476:
10477: @node Rmail Motion, Rmail Deletion, Rmail Scrolling, Rmail
10478: @section Moving Among Messages
10479:
10480: The most basic thing to do with a message is to read it. The way to do
10481: this in Rmail is to make the message current. You can make any message
10482: current given its message number using the @kbd{j} command, but the usual
10483: thing to do is to move sequentially through the file, since this is the
10484: order of receipt of messages. When you enter Rmail, you are positioned at
10485: the first new message (new messages are those received since the previous
10486: use of Rmail), or at the last message if there are no new messages this
10487: time. Move forward to see the other new messages; move backward to
10488: reexamine old messages.
10489:
10490: @table @kbd
10491: @item n
10492: Move to the next nondeleted message, skipping any intervening deleted @*
10493: messages (@code{rmail-next-undeleted-message}).
10494: @item p
10495: Move to the previous nondeleted message @*
10496: (@code{rmail-previous-undeleted-message}).
10497: @item M-n
10498: Move to the next message, including deleted messages
10499: (@code{rmail-next-message}).
10500: @item M-p
10501: Move to the previous message, including deleted messages
10502: (@code{rmail-previous-message}).
10503: @item j
10504: Move to the first message. With argument @var{n}, move to
10505: message number @var{n} (@code{rmail-show-message}).
10506: @item >
10507: Move to the last message (@code{rmail-last-message}).
10508:
10509: @item M-s @var{regexp} @key{RET}
10510: Move to the next message containing a match for @var{regexp}
10511: (@code{rmail-search}). If @var{regexp} is empty, the last regexp used is
10512: used again.
10513:
10514: @item - M-s @var{regexp} @key{RET}
10515: Move to the previous message containing a match for @var{regexp}.
10516: If @var{regexp} is empty, the last regexp used is used again.
10517: @end table
10518:
10519: @kindex n (Rmail)
10520: @kindex p (Rmail)
10521: @kindex M-n (Rmail)
10522: @kindex M-p (Rmail)
10523: @findex rmail-next-undeleted-message
10524: @findex rmail-previous-undeleted-message
10525: @findex rmail-next-message
10526: @findex rmail-previous-message
10527: @kbd{n} and @kbd{p} are the usual way of moving among messages in Rmail. They
10528: move through the messages sequentially, but skip over deleted messages,
10529: which is usually what you want to do. Their command definitions are named
10530: @code{rmail-next-undeleted-message} and @code{rmail-previous-undeleted-message}. If
10531: you do not want to skip deleted messages---for example, if you want to move
10532: to a message to undelete it---use the variants @kbd{M-n} and @kbd{M-p}
10533: (@code{rmail-next-message} and @code{rmail-previous-message}). A numeric
10534: argument to any of these commands serves as a repeat count.@refill
10535:
10536: In Rmail, you can specify a numeric argument by typing the digits.
10537: It is not necessary to type @kbd{C-u} first.
10538:
10539: @kindex M-s (Rmail)
10540: @findex rmail-search
10541: The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of search. The
10542: usual incremental search command @kbd{C-s} works in Rmail, but it searches
10543: only within the current message. The purpose of @kbd{M-s} is to search for
10544: another message. It reads a regular expression (@pxref{Regexps})
10545: nonincrementally, then searches starting at the beginning of the following
10546: message for a match. The message containing the match is selected.
10547:
10548: To search backward in the file for another message, give @kbd{M-s} a
10549: negative argument. In Rmail this can be done with @kbd{- M-s}.
10550:
10551: It is also possible to search for a message based on labels.
10552: @xref{Rmail Labels}.
10553:
10554: @kindex j (Rmail)
10555: @kindex > (Rmail)
10556: @findex rmail-show-message
10557: @findex rmail-last-message
10558: To move to a message specified by absolute message number, use @kbd{j}
10559: (@code{rmail-show-message}) with the message number as argument. With no
10560: argument, @kbd{j} selects the first message. @kbd{>} (@code{rmail-last-message}) selects
10561: the last message.
10562:
10563: @node Rmail Deletion, Rmail Inbox, Rmail Motion, Rmail
10564: @section Deleting Messages
10565:
10566: @cindex deletion (Rmail)
10567: When you no longer need to keep a message, you can @dfn{delete} it. This
10568: flags it as ignorable, and some Rmail commands will pretend it is no longer
10569: present; but it still has its place in the Rmail file, and still has its
10570: message number.
10571:
10572: @cindex expunging (Rmail)
10573: @dfn{Expunging} the Rmail file actually removes the deleted messages.
10574: The remaining messages are renumbered consecutively. Expunging is the only
10575: action that changes the message number of any message, except for
10576: undigestifying (@pxref{Rmail Digest}).
10577:
10578: @table @kbd
10579: @item d
10580: Delete the current message, and move to the next nondeleted message
10581: (@code{rmail-delete-forward}).
10582: @item C-d
10583: Delete the current message, and move to the previous nondeleted
10584: message (@code{rmail-delete-backward}).
10585: @item u
10586: Undelete the current message, or move back to a deleted message and
10587: undelete it (@code{rmail-undelete-previous-message}).
10588: @itemx x
10589: @item e
10590: Expunge the Rmail file (@code{rmail-expunge}). These two
10591: commands are synonyms.
10592: @end table
10593:
10594: @kindex d (Rmail)
10595: @kindex C-d (Rmail)
10596: @findex rmail-delete-forward
10597: @findex rmail-delete-backward
10598: There are two Rmail commands for deleting messages. Both delete the
10599: current message and select another message. @kbd{d} (@code{rmail-delete-forward})
10600: moves to the following message, skipping messages already deleted, while
10601: @kbd{C-d} (@code{rmail-delete-backward}) moves to the previous nondeleted message.
10602: If there is no nondeleted message to move to in the specified direction,
10603: the message that was just deleted remains current.
10604:
10605: @cindex undeletion (Rmail)
10606: @kindex e (Rmail)
10607: @findex rmail-expunge
10608: To make all the deleted messages finally vanish from the Rmail file,
10609: type @kbd{e} (@code{rmail-expunge}). Until you do this, you can still @dfn{undelete}
10610: the deleted messages.
10611:
10612: @kindex u (Rmail)
10613: @findex rmail-undelete-previous-message
10614: To undelete, type
10615: @kbd{u} (@code{rmail-undelete-previous-message}), which is designed to cancel the
10616: effect of a @kbd{d} command (usually). It undeletes the current message
10617: if the current message is deleted. Otherwise it moves backward to previous
10618: messages until a deleted message is found, and undeletes that message.
10619:
10620: You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} moves
10621: back to and undeletes the message that the @kbd{d} deleted. But this does
10622: not work when the @kbd{d} skips a few already-deleted messages that follow
10623: the message being deleted; then the @kbd{u} command will undelete the last
10624: of the messages that were skipped. There is no clean way to avoid this
10625: problem. However, by repeating the @kbd{u} command, you can eventually get
10626: back to the message that you intended to undelete. You can also reach that
10627: message with @kbd{M-p} commands and then type @kbd{u}.@refill
10628:
10629: A deleted message has the @samp{deleted} attribute, and as a result
10630: @samp{deleted} appears in the mode line when the current message is
10631: deleted. In fact, deleting or undeleting a message is nothing more than
10632: adding or removing this attribute. @xref{Rmail Labels}.
10633:
10634: @node Rmail Inbox, Rmail Files, Rmail Deletion, Rmail
10635: @section Rmail Files and Inboxes
10636: @cindex inbox file
10637:
10638: Unix places incoming mail for you in a file that we call your @dfn{inbox}.
10639: When you start up Rmail, it copies the new messages from your inbox into
10640: your primary mail file, an Rmail file, which also contains other messages
10641: saved from previous Rmail sessions. It is in this file that you actually
10642: read the mail with Rmail. This operation is called @dfn{getting new mail}.
10643: It can be repeated at any time using the @kbd{g} key in Rmail. The inbox
10644: file name is @file{/usr/spool/mail/@var{username}} in Berkeley Unix,
10645: @file{/usr/mail/@var{username}} in system V.
10646:
10647: There are two reason for having separate Rmail files and inboxes.
10648:
10649: @enumerate
10650: @item
10651: The format in which Unix delivers the mail in the inbox is not
10652: adequate for Rmail mail storage. It has no way to record attributes
10653: (such as @samp{deleted}) or user-specified labels; it has no way to record
10654: old headers and reformatted headers; it has no way to record cached
10655: summary line information.
10656:
10657: @item
10658: It is very cumbersome to access an inbox file without danger of losing
10659: mail, because it is necessary to interlock with mail delivery.
10660: Moreover, different Unix systems use different interlocking
10661: techniques. The strategy of moving mail out of the inbox once and for
10662: all into a separate Rmail file avoids the need for interlocking in all
10663: the rest of Rmail, since only Rmail operates on the Rmail file.
10664: @end enumerate
10665:
10666: When getting new mail, Rmail first copies the new mail from the inbox
10667: file to the Rmail file; then it saves the Rmail file; then it deletes the
10668: inbox file. This way, a system crash may cause duplication of mail between
10669: the inbox and the Rmail file, but cannot lose mail.
10670:
10671: Copying mail from an inbox in the system's mailer directory actually puts
10672: it in an intermediate file @file{~/.newmail}. This is because the
10673: interlocking is done by a C program that copies to another file.
10674: @file{~/.newmail} is deleted after mail merging is successful. If there is
10675: a crash at the wrong time, this file will continue to exist and will be
10676: used as an inbox the next time you get new mail.
10677:
10678: @node Rmail Files, Rmail Output, Rmail Inbox, Rmail
10679: @section Multiple Mail Files
10680:
10681: Rmail operates by default on your @dfn{primary mail file}, which is named
10682: @file{~/RMAIL} and receives your incoming mail from your system inbox file.
10683: But you can also have other mail files and edit them with Rmail. These
10684: files can receive mail through their own inboxes, or you can move messages
10685: into them by explicit command in Rmail (@pxref{Rmail Output}).
10686:
10687: @table @kbd
10688: @item i @var{file} @key{RET}
10689: Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
10690:
10691: @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
10692: Specify inbox file names for current Rmail file to get mail from.
10693:
10694: @item g
10695: Merge new mail from current Rmail file's inboxes
10696: (@code{rmail-get-new-mail}).
10697:
10698: @item C-u g @var{file}
10699: Merge new mail from inbox file @var{file}.
10700: @end table
10701:
10702: @kindex i (Rmail)
10703: @findex rmail-input
10704: To run Rmail on a file other than your primary mail file, you may use the
10705: @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file, puts it in
10706: Rmail mode, and then gets new mail from the file's inboxes if any.
10707: You can also use @kbd{M-x rmail-input} even when not in Rmail.
10708:
10709: The file you read with @kbd{i} does not have to be in Rmail file format.
10710: It could also be Unix mail format, or mmdf format; or it could be a mixture
10711: of all three, as long as each message belongs to one of the three formats.
10712: Rmail recognizes all three and converts all the messages to proper Rmail
10713: format before showing you the file.
10714:
10715: @findex set-rmail-inbox-list
10716: Each Rmail file can contain a list of inbox file names; you can specify
10717: this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
10718: @key{RET}}. The argument can contain any number of file names, separated
10719: by commas. It can also be empty, which specifies that this file should
10720: have no inboxes. Once a list of inboxes is specified, the Rmail file
10721: remembers it permanently until it is explicitly changed.@refill
10722:
10723: @kindex g (Rmail)
10724: @findex rmail-get-new-mail
10725: If an Rmail file has inboxes, new mail is merged in from the inboxes when
10726: the Rmail file is brought into Rmail, and when the @kbd{g} (@code{rmail-get-new-mail})
10727: command is used. If the Rmail file specifies no inboxes, then no new mail
10728: is merged in at these times. A special exception is made for your primary
10729: mail file in using the standard system inbox for it if it does not specify
10730: any.
10731:
10732: To merge mail from a file that is not the usual inbox, give the @kbd{g}
10733: key a numeric argument, as in @kbd{C-u g}. Then it reads a file name and
10734: merges mail from that file. The inbox file is not deleted or changed in
10735: any way when @kbd{g} with an argument is used. This is, therefore, a
10736: general way of merging one file of messages into another.
10737:
10738: @node Rmail Output, Rmail Labels, Rmail Files, Rmail
10739: @section Copying Messages Out to Files
10740:
10741: @table @kbd
10742: @item o @var{file} @key{RET}
10743: Append a copy of the current message to the file @var{file},
10744: writing it in Rmail file format (@code{rmail-output-to-rmail-file}).
10745:
10746: @item C-o @var{file} @key{RET}
10747: Append a copy of the current message to the file @var{file},
10748: writing it in Unix mail file format (@code{rmail-output}).
10749: @end table
10750:
10751: @kindex o (Rmail)
10752: @findex rmail-output-to-rmail-file
10753: @kindex C-o (Rmail)
10754: @findex rmail-output
10755: If an Rmail file has no inboxes, how does it get anything in it? By
10756: explicit @kbd{o} commands.
10757:
10758: @kbd{o} (@code{rmail-output-to-rmail-file}) appends the current message
10759: in Rmail format to the end of the specified file. This is the best command
10760: to use to move messages between Rmail files. If the other Rmail file is
10761: currently visited, the copying is done into the other file's Emacs buffer
10762: instead. You should eventually save it on disk.
10763:
10764: The @kbd{C-o} (@code{rmail-output}) command in Rmail appends a copy of the current
10765: message to a specified file, in Unix mail file format. This is useful for
10766: moving messages into files to be read by other mail processors that do not
10767: understand Rmail format.
10768:
10769: Copying a message with @kbd{o} or @kbd{C-o} gives the original copy of the
10770: message the @samp{filed} attribute, so that @samp{filed} appears in the mode
10771: line when such a message is current.
10772:
10773: Normally you should use only @kbd{o} to output messages to other Rmail
10774: files, never @kbd{C-o}. But it is also safe if you always use @kbd{C-o},
10775: never @kbd{o}. When a file is visited in Rmail, the last message is
10776: checked, and if it is in Unix format, the entire file is scanned and all
10777: Unix-format messages are converted to Rmail format. (The reason for
10778: checking the last message is that scanning the file is slow and most Rmail
10779: files have only Rmail format messages.) If you use @kbd{C-o} consistently,
10780: the last message is sure to be in Unix format, so Rmail will convert all
10781: messages properly.
10782:
10783: The case where you might want to use @kbd{C-o} always, instead of @kbd{o}
10784: always, is when you or other users want to append mail to the same file
10785: from other mail processors. Other mail processors probably do not know
10786: Rmail format but do know Unix format.
10787:
10788: In any case, always use @kbd{o} to add to an Rmail file that is being
10789: visited in Rmail. Adding messages with @kbd{C-o} to the actual disk file
10790: will trigger a ``simultaneous editing'' warning when you ask to save the
10791: Emacs buffer, and will be lost if you do save.
10792:
10793: @node Rmail Labels, Rmail Summary, Rmail Output, Rmail
10794: @section Labels
10795: @cindex label (Rmail)
10796: @cindex attribute (Rmail)
10797:
10798: Each message can have various @dfn{labels} assigned to it as a means of
10799: classification. A label has a name; different names mean different labels.
10800: Any given label is either present or absent on a particular message. A few
10801: label names have standard meanings and are given to messages automatically
10802: by Rmail when appropriate; these special labels are called @dfn{attributes}.
10803: All other labels are assigned by the user.
10804:
10805: @table @kbd
10806: @item a @var{label} @key{RET}
10807: Assign the label @var{label} to the current message (@code{rmail-add-label}).
10808: @item k @var{label} @key{RET}
10809: Remove the label @var{label} from the current message (@code{rmail-kill-label}).
10810: @item C-M-n @var{labels} @key{RET}
10811: Move to the next message that has one of the labels @var{labels}
10812: (@code{rmail-next-labeled-message}).
10813: @item C-M-p @var{labels} @key{RET}
10814: Move to the previous message that has one of the labels @var{labels}
10815: (@code{rmail-previous-labeled-message}).
10816: @item C-M-l @var{labels} @key{RET}
10817: Make a summary of all messages containing any of the labels @var{labels}
10818: (@code{rmail-summary-by-labels}).
10819: @end table
10820:
10821: @noindent
10822: Specifying an empty string for one these commands means to use the last
10823: label specified for any of these commands.
10824:
10825: @kindex a (Rmail)
10826: @kindex k (rmail)
10827: @findex rmail-add-label
10828: @findex rmail-kill-label
10829: The @kbd{a} (@code{rmail-add-label}) and @kbd{k} (@code{rmail-kill-label}) commands allow
10830: you to assign or remove any label on the current message. If the @var{label}
10831: argument is empty, it means to assign or remove the same label most
10832: recently assigned or removed.
10833:
10834: Once you have given messages labels to classify them as you wish, there
10835: are two ways to use the labels: in moving and in summaries.
10836:
10837: @kindex C-M-n (Rmail)
10838: @kindex C-M-p (Rmail)
10839: @findex rmail-next-labeled-message
10840: @findex rmail-previous-labeled-message
10841: The command @kbd{C-M-n @var{labels} @key{RET}}
10842: (@code{rmail-next-labeled-message}) moves to the next message that has one
10843: of the labels @var{labels}. @var{labels} is one or more label names,
10844: separated by commas. @kbd{C-M-p} (@code{rmail-previous-labeled-message})
10845: is similar, but moves backwards to previous messages. A preceding numeric
10846: argument to either one serves as a repeat count.@refill
10847:
10848: @kindex C-M-l (Rmail)
10849: @findex rmail-summary-by-labels
10850: The command @kbd{C-M-l @var{labels} @key{RET}}
10851: (@code{rmail-summary-by-labels}) displays a summary containing only the
10852: messages that have at least one of a specified set of messages. The
10853: argument @var{labels} is one or more label names, separated by commas.
10854: @xref{Rmail Summary}, for information on summaries.@refill
10855:
10856: If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or @kbd{C-M-l} is empty, it means
10857: to use the last set of labels specified for any of these commands.
10858:
10859: Some labels such as @samp{deleted} and @samp{filed} have built-in meanings and
10860: are assigned to or removed from messages automatically at appropriate
10861: times; these labels are called @dfn{attributes}. Here is a list of Rmail
10862: attributes:
10863:
10864: @table @samp
10865: @item unseen
10866: Means the message has never been current. Assigned to messages when
10867: they come from an inbox file, and removed when a message is made
10868: current.
10869: @item deleted
10870: Means the message is deleted. Assigned by deletion commands and
10871: removed by undeletion commands (@pxref{Rmail Deletion}).
10872: @item filed
10873: Means the message has been copied to some other file. Assigned by the
10874: file output commands (@pxref{Rmail Files}).
10875: @item answered
10876: Means you have mailed an answer to the message. Assigned by the @kbd{r}
10877: command (@code{rmail-reply}). @xref{Rmail Reply}.
10878: @item forwarded
10879: Means you have forwarded the message to other users. Assigned by the
10880: @kbd{f} command (@code{rmail-forward}). @xref{Rmail Reply}.
10881: @item edited
10882: Means you have edited the text of the message within Rmail.
10883: @xref{Rmail Editing}.
10884: @end table
10885:
10886: All other labels are assigned or removed only by the user, and it is up
10887: to the user to decide what they mean.
10888:
10889: @node Rmail Summary, Rmail Reply, Rmail Labels, Rmail
10890: @section Summaries
10891: @cindex summary (Rmail)
10892:
10893: A @dfn{summary} is a buffer containing one line per message that Rmail
10894: can make and display to give you an overview of the mail in an Rmail file.
10895: Each line shows the message number, the sender, the labels, and the
10896: subject. When the summary buffer is selected, various commands can be used
10897: to select messages by moving in the summary buffer, or delete or undelete
10898: messages.
10899:
10900: A summary buffer applies to a single Rmail file only; if you are
10901: editing multiple Rmail files, they have separate summary buffers. The
10902: summary buffer name is made by appending @samp{-summary} to the Rmail buffer's
10903: name. Only one summary buffer will be displayed at a time unless you make
10904: several windows and select the summary buffers by hand.
10905:
10906: @menu
10907: * Rmail Make Summary:: Making various sorts of summaries.
10908: * Rmail Summary Edit:: Manipulating messages from the summary.
10909: @end menu
10910:
10911: @node Rmail Make Summary, Rmail Summary Edit, Rmail Summary, Rmail Summary
10912: @subsection Making Summaries
10913:
10914: Here are the commands to create a summary for the current Rmail file.
10915: Summaries do not update automatically; to make an updated summary, you
10916: must use one of these commands again.
10917:
10918: @table @kbd
10919: @item h
10920: @itemx C-M-h
10921: Summarize all messages (@code{rmail-summary}).
10922: @item l @var{labels} @key{RET}
10923: @itemx C-M-l @var{labels} @key{RET}
10924: Summarize message that have one or more of the specified labels
10925: (@code{rmail-summary-by-labels}).
10926: @item C-M-r @var{rcpts} @key{RET}
10927: Summarize messages that have one or more of the specified recipients
10928: (@code{rmail-summary-by-recipients})
10929: @end table
10930:
10931: @kindex h (Rmail)
10932: @findex rmail-summary
10933: The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
10934: for the current Rmail file with a summary of all the messages in the file.
10935: It then displays and selects the summary buffer in another window.
10936:
10937: @kindex l (Rmail)
10938: @kindex C-M-l (Rmail)
10939: @findex rmail-summary-by-labels
10940: @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
10941: a partial summary mentioning only the messages that have one or more of the
10942: labels @var{labels}. @var{labels} should contain label names separated by
10943: commas.@refill
10944:
10945: @kindex C-M-r (Rmail)
10946: @findex rmail-summary-by-recipients
10947: @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
10948: makes a partial summary mentioning only the messages that have one or more
10949: of the recipients @var{rcpts}. @var{rcpts} should contain mailing
10950: addresses separated by commas.@refill
10951:
10952: Note that there is only one summary buffer for any Rmail file; making one
10953: kind of summary discards any previously made summary.
10954:
10955: @node Rmail Summary Edit,, Rmail Make Summary, Rmail Summary
10956: @subsection Editing in Summaries
10957:
10958: Summary buffers are given the major mode Rmail Summary mode, which
10959: provides the following special commands:
10960:
10961: @table @kbd
10962: @item j
10963: Select the message described by the line that point is on
10964: (@code{rmail-summary-goto-msg}).
10965: @item C-n
10966: Move to next line and select its message in Rmail
10967: (@code{rmail-summary-next-all}).
10968: @item C-p
10969: Move to previous line and select its message
10970: (@code{rmail-summary-previous-all}).
10971: @item n
10972: Move to next line, skipping lines saying `deleted', and select its
10973: message (@code{rmail-summary-next-msg}).
10974: @item p
10975: Move to previous line, skipping lines saying `deleted', and select
10976: its message (@code{rmail-summary-previous-msg}).
10977: @item d
10978: Delete the current line's message, then do like @kbd{n}
10979: (@code{rmail-summary-delete-forward}).
10980: @item u
10981: Undelete and select this message or the previous deleted message in
10982: the summary (@code{rmail-summary-undelete}).
10983: @item @key{SPC}
10984: Scroll the other window (presumably Rmail) forward
10985: (@code{rmail-summary-scroll-msg-up}).
10986: @item @key{DEL}
10987: Scroll the other window backward (@code{rmail-summary-scroll-msg-down}).
10988: @item x
10989: Kill the summary window (@code{rmail-summary-exit}).
10990: @item q
10991: Exit Rmail (@code{rmail-summary-quit}).
10992: @end table
10993:
10994: @kindex C-n (Rmail summary)
10995: @kindex C-p (Rmail summary)
10996: @findex rmail-summary-next-all
10997: @findex rmail-summary-previous-all
10998: The keys @kbd{C-n} and @kbd{C-p} are modified in Rmail Summary mode so that in
10999: addition to moving point in the summary buffer they also cause the line's
11000: message to become current in the associated Rmail buffer. That buffer is
11001: also made visible in another window if it is not already so.
11002:
11003: @kindex n (Rmail summary)
11004: @kindex p (Rmail summary)
11005: @findex rmail-summary-next-msg
11006: @findex rmail-summary-previous-msg
11007: @kbd{n} and @kbd{p} are similar to @kbd{C-n} and @kbd{C-p}, but skip
11008: lines that say `message deleted'. They are like the @kbd{n} and @kbd{p}
11009: keys of Rmail itself. Note, however, that in a partial summary these
11010: commands move only among the message listed in the summary.@refill
11011:
11012: @kindex j (Rmail summary)
11013: @findex rmail-summary-goto-msg
11014: The other Emacs cursor motion commands are not changed in Rmail Summary
11015: mode, so it is easy to get the point on a line whose message is not
11016: selected in Rmail. This can also happen if you switch to the Rmail window
11017: and switch messages there. To get the Rmail buffer back in sync with the
11018: summary, use the @kbd{j} (@code{rmail-summary-goto-msg}) command, which selects
11019: in Rmail the message of the current summary line.
11020:
11021: @kindex d (Rmail summary)
11022: @kindex u (Rmail summary)
11023: @findex rmail-summary-delete-forward
11024: @findex rmail-summary-undelete
11025: Deletion and undeletion can also be done from the summary buffer. They
11026: always work based on where point is located in the summary buffer, ignoring
11027: which message is selected in Rmail. @kbd{d} (@code{rmail-summary-delete-forward})
11028: deletes the current line's message, then moves to the next line whose
11029: message is not deleted and selects that message. The inverse of this is
11030: @kbd{u} (@code{rmail-summary-undelete}), which moves back (if necessary) to a line
11031: whose message is deleted, undeletes that message, and selects it in Rmail.
11032:
11033: @kindex SPC (Rmail summary)
11034: @kindex DEL (Rmail summary)
11035: @findex rmail-summary-scroll-msg-down
11036: @findex rmail-summary-scroll-msg-up
11037: When moving through messages with the summary buffer, it is convenient to
11038: be able to scroll the message while remaining in the summary window.
11039: The commands @key{SPC} (@code{rmail-summary-scroll-msg-up}) and @key{DEL}
11040: (@code{rmail-summary-scroll-msg-down}) do this. They scroll the message just
11041: as those same keys do when the Rmail buffer is selected.@refill
11042:
11043: @kindex x (Rmail summary)
11044: @findex rmail-summary-exit
11045: When you are finished using the summary, type @kbd{x} (@code{rmail-summary-exit})
11046: to kill the summary buffer's window.
11047:
11048: @kindex q (Rmail summary)
11049: @findex rmail-summary-quit
11050: You can also exit Rmail while in the summary. @kbd{q} (@code{rmail-summary-quit})
11051: kills the summary window, then saves the Rmail file and switches to another
11052: buffer.
11053:
11054: @node Rmail Reply, Rmail Editing, Rmail Summary, Rmail
11055: @section Sending Replies
11056:
11057: Rmail has several commands that use Mail mode to send outgoing mail.
11058: @xref{Sending Mail}, for information on using Mail mode. What are
11059: documented here are the special commands of Rmail for entering Mail mode.
11060: Note that the usual keys for sending mail, @kbd{C-x m} and @kbd{C-x 4 m},
11061: are available in Rmail mode and work just as they usually do.@refill
11062:
11063: @table @kbd
11064: @item m
11065: Send a message (@code{rmail-mail}).
11066: @item c
11067: Continue editing already started outgoing message @*(@code{rmail-continue}).
11068: @item r
11069: Send a reply to the current Rmail message (@code{rmail-reply}).
11070: @item f
11071: Forward current message to other users (@code{rmail-forward}).
11072: @end table
11073:
11074: @kindex r (Rmail)
11075: @findex rmail-reply
11076: @vindex rmail-dont-reply-to
11077: @cindex reply to a message
11078: The most common reason to send a message while in Rmail is to reply to
11079: the message you are reading. To do this, type @kbd{r}
11080: (@code{rmail-reply}). This displays the @samp{*mail*} buffer in another
11081: window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject},
11082: @samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the
11083: message being replied to. The @samp{To} field is given the sender of that
11084: message, and the @samp{CC} gets all the recipients of that message (but
11085: recipients that match elements of the list @code{rmail-dont-reply-to} are
11086: omitted; by default, this list contains your own mailing address).@refill
11087:
11088: Once you have initialized the @samp{*mail*} buffer this way, sending the
11089: mail goes as usual (@pxref{Sending Mail}). You can edit the presupplied
11090: header fields if they are not right for you.
11091:
11092: @kindex C-c C-y (Mail mode)
11093: @findex mail-yank-original
11094: One additional Mail mode command is available when mailing is invoked
11095: from Rmail: @kbd{C-c C-y} (@code{mail-yank-original}) inserts into the outgoing
11096: message a copy of the current Rmail message; normally this is the message
11097: you are replying to, but you can also switch to the Rmail buffer, select a
11098: different message, switch back, and yank new current message. Normally the
11099: yanked message is indented four spaces and has most header fields deleted
11100: from it; an argument to @kbd{C-c C-y} specifies the amount to indent, and
11101: @kbd{C-u C-c C-y} does not indent at all and does not delete any header
11102: fields.@refill
11103:
11104: @kindex f (Rmail)
11105: @findex rmail-forward
11106: @cindex forward a message
11107: Another frequent reason to send mail in Rmail is to forward the current
11108: message to other users. @kbd{f} (@code{rmail-forward}) makes this easy by
11109: preinitializing the @samp{*mail*} buffer with the current message as the
11110: text, and a subject designating a forwarded message. All you have to do is
11111: fill in the recipients and send.@refill
11112:
11113: @kindex m (Rmail)
11114: @findex rmail-mail
11115: The @kbd{m} (@code{rmail-mail}) command is used to start editing an
11116: outgoing message that is not a reply. It leaves the header fields empty.
11117: Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
11118: accessible for @kbd{C-c y}, just as @kbd{r} does. Thus, @kbd{m} can be
11119: used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
11120: can do.@refill
11121:
11122: @kindex c (Rmail)
11123: @findex rmail-continue
11124: The @kbd{c} (@code{rmail-continue}) command resumes editing the
11125: @samp{*mail*} buffer, to finish editing an outgoing message you were
11126: already composing, or to alter a message you have sent.@refill
11127:
11128: @node Rmail Editing, Rmail Digest, Rmail Reply, Rmail
11129: @section Editing Within a Message
11130:
11131: Rmail mode provides a few special commands for moving within and editing
11132: the current message. In addition, the usual Emacs commands are available
11133: (except for a few, such as @kbd{C-M-n} and @kbd{C-M-h}, that are redefined by Rmail for
11134: other purposes). However, the Rmail buffer is normally read-only, and to
11135: alter it you must use the Rmail command @kbd{w} described below.
11136:
11137: @table @kbd
11138: @item t
11139: Toggle display of original headers (@code{rmail-toggle-headers}).
11140: @item w
11141: Edit current message (@code{rmail-edit-current-message}).
11142: @end table
11143:
11144: @kindex t (Rmail)
11145: @findex rmail-toggle-header
11146: @vindex rmail-ignored-headers
11147: Rmail reformats the header of each message before displaying it.
11148: Normally this involves deleting most header fields, on the grounds that
11149: they are not interesting. The variable @code{rmail-ignored-headers} should
11150: contain a regexp that matches the header fields to discard in this way.
11151: The original headers are saved permanently, and to see what they look like,
11152: use the @kbd{t} (@code{rmail-toggle-headers}) command. This discards the reformatted
11153: headers of the current message and displays it with the original headers.
11154: Repeating @kbd{t} reformats the message again. Selecting the message again
11155: also reformats.
11156:
11157: @kindex w (Rmail)
11158: @findex rmail-edit-current-message
11159: The Rmail buffer is normally read only, and most of the characters you
11160: would type to modify it (including most letters) are redefined as Rmail
11161: commands. This is usually not a problem since it is rare to want to change
11162: the text of a message. When you do want to do this, the way is to type
11163: @kbd{w} (@code{rmail-edit-current-message}), which changes from Rmail mode into
11164: Rmail Edit mode, another major mode which is nearly the same as Text mode.
11165: The mode line illustrates this change.
11166:
11167: In Rmail Edit mode, letters insert themselves as usual and the Rmail
11168: commands are not available. When you are finished editing the message and
11169: are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to
11170: Rmail mode. Alternatively, you can return to Rmail mode but cancel all the
11171: editing that you have done by typing @kbd{C-c C-]}.
11172:
11173: @vindex rmail-edit-mode-hook
11174: Entering Rmail Edit mode calls with no arguments the value of the variable
11175: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
11176: does the same with the variable @code{rmail-edit-mode-hook}. It adds the
11177: attribute @samp{edited} to the message.
11178:
11179: @node Rmail Digest,, Rmail Editing, Rmail
11180: @section Digest Messages
11181: @cindex digest message
11182: @cindex undigestify
11183:
11184: A @dfn{digest message} is a message which exists to contain and carry
11185: several other messages. Digests are used on moderated mailing lists; all
11186: the messages that arrive for the list during a period of time such as one
11187: day are put inside a single digest which is then sent to the subscribers.
11188: Transmitting the single digest uses much less computer time than
11189: transmitting the individual messages even though the total size is the
11190: same, because the per-message overhead in network mail transmission is
11191: considerable.
11192:
11193: @findex undigestify-rmail-message
11194: When you receive a digest message, the most convenient way to read it is
11195: to @dfn{undigestify} it: to turn it back into many individual messages.
11196: Then you can read and delete the individual messages as it suits you.
11197:
11198: To undigestify a message, select it and then type @kbd{M-x
11199: undigestify-rmail-message}. This copies each submessage as a separate
11200: Rmail message and inserts them all following the digest. The digest
11201: message itself is flagged as deleted.
11202:
11203: @iftex
11204: @chapter Miscellaneous Commands
11205:
11206: This chapter contains several brief topics that do not fit anywhere else.
11207:
11208: @end iftex
11209: @node Recursive Edit, Narrowing, Rmail, Top
11210: @section Recursive Editing Levels
11211: @cindex recursive editing level
11212: @cindex editing level, recursive
11213:
11214: A @dfn{recursive edit} is a situation in which you are using Emacs
11215: commands to perform arbitrary editing while in the middle of another Emacs
11216: command. For example, when you type @kbd{C-r} inside of a @code{query-replace},
11217: you enter a recursive edit in which you can change the current buffer. On
11218: exiting from the recursive edit, you go back to the @code{query-replace}.
11219:
11220: @kindex C-M-c
11221: @findex exit-recursive-edit
11222: @cindex exiting
11223: @dfn{Exiting} the recursive edit means returning to the unfinished
11224: command, which continues execution. For example, exiting the recursive
11225: edit requested by @kbd{C-r} in @code{query-replace} causes query replacing
11226: to resume. Exiting is done with @kbd{C-M-c} (@code{exit-recursive-edit}).
11227:
11228: @kindex C-]
11229: @findex abort-recursive-edit
11230: You can also @dfn{abort} the recursive edit. This is like exiting, but
11231: also quits the unfinished command immediately. Use the command @kbd{C-]}
11232: (@code{abort-recursive-edit}) for this. @xref{Quitting}.
11233:
11234: The mode line shows you when you are in a recursive edit by displaying
11235: square brackets around the parentheses that always surround the major and
11236: minor mode names. Every window's mode line shows this, in the same way,
11237: since being in a recursive edit is true of Emacs as a whole rather than
11238: any particular buffer.
11239:
11240: @findex top-level
11241: It is possible to be in recursive edits within recursive edits. For
11242: example, after typing @kbd{C-r} in a @code{query-replace}, you might type a
11243: command that entered the debugger. In such circumstances, two or more sets
11244: of square brackets appear in the mode line. Exiting the inner recursive
11245: edit (such as, with the debugger @kbd{c} command) would resume the command
11246: where it called the debugger. After the end of this command, you would be
11247: able to exit the first recursive edit. Aborting also gets out of only one
11248: level of recursive edit; it returns immediately to the command level of the
11249: previous recursive edit. So you could immediately abort that one too.
11250:
11251: Alternatively, the command @kbd{M-x top-level} aborts all levels of
11252: recursive edits, returning immediately to the top level command reader.
11253:
11254: The text being edited inside the recursive edit need not be the same text
11255: that you were editing at top level. It depends on what the recursive edit
11256: is for. If the command that invokes the recursive edit selects a different
11257: buffer first, that is the buffer you will edit recursively. In any case,
11258: you can switch buffers within the recursive edit in the normal manner (as
11259: long as the buffer-switching keys have not been rebound). You could
11260: probably do all the rest of your editing inside the recursive edit,
11261: visiting files and all. But this could have surprising effects (such as
11262: stack overflow) from time to time. So remember to exit or abort the
11263: recursive edit when you no longer need it.
11264:
11265: In general, GNU Emacs tries to avoid using recursive edits. It is
11266: usually preferable to allow the user to switch among the possible editing
11267: modes in any order he likes. With recursive edits, the only way to get to
11268: another state is to go ``back'' to the state that the recursive edit was
11269: invoked from.
11270:
11271: @node Narrowing, Sorting, Recursive Edit, Top
11272: @section Narrowing
11273: @cindex widening
11274: @cindex restriction
11275: @cindex narrowing
11276:
11277: @dfn{Narrowing} means focusing in on some portion of the buffer, making
11278: the rest temporarily invisible and inaccessible. Cancelling the narrowing,
11279: and making the entire buffer once again visible, is called @dfn{widening}.
11280: The amount of narrowing in effect in a buffer at any time is called the
11281: buffer's @dfn{restriction}.
11282:
11283: @c WideCommands
11284: @table @kbd
11285: @item C-x n
11286: Narrow down to between point and mark (@code{narrow-to-region}).
11287: @item C-x w
11288: Widen to make the entire buffer visible again (@code{widen}).
11289: @end table
11290:
11291: When you have narrowed down to a part of the buffer, that part appears to
11292: be all there is. You can't see the rest, you can't move into it (motion
11293: commands won't go outside the visible part), you can't change it in any
11294: way. However, it is not gone, and if you save the file all the invisible
11295: text will be saved. In addition to sometimes making it easier to
11296: concentrate on a single subroutine or paragraph by eliminating clutter,
11297: narrowing can be used to restrict the range of operation of a replace
11298: command or repeating keyboard macro. The word @samp{Narrow} appears in the
11299: mode line whenever narrowing is in effect.
11300:
11301: @kindex C-x n
11302: @findex narrow-to-region
11303: The primary narrowing command is @kbd{C-x n} (@code{narrow-to-region}).
11304: It sets the current buffer's restrictions so that the text in the current
11305: region remains visible but all text before the region or after the region
11306: is invisible. Point and mark do not change.
11307:
11308: Because narrowing can easily confuse users who do not understand it,
11309: @code{narrow-to-region} is normally a disabled command. Attempting to use
11310: this command asks for confirmation and gives you the option of enabling it;
11311: once you enable the command, confirmation will no longer be required for
11312: it. @xref{Disabling}.
11313:
11314: @kindex C-x w
11315: @findex widen
11316: The way to undo narrowing is to widen with @kbd{C-x w} (@code{widen}).
11317: This makes all text in the buffer accessible again.
11318:
11319: You can get information on what part of the buffer you are narrowed down
11320: to using the @kbd{C-x =} command. @xref{Position Info}.
11321:
11322: @node Sorting, Shell, Narrowing, Top
11323: @section Sorting Text
11324: @cindex sorting
11325:
11326: Emacs provides several commands for sorting text in the buffer. All
11327: operate on the contents of the region (the text between point and the
11328: mark). They divide the text of the region into many @dfn{sort records},
11329: identify a @dfn{sort key} for each record, and then reorder the records
11330: into the order determined by the sort keys. The records are ordered so
11331: that their keys are in alphabetical order, or, for numeric sorting, in
11332: numeric order. In alphabetic sorting, all upper case letters `A' through
11333: `Z' come before lower case `a', in accord with the ASCII character
11334: sequence.
11335:
11336: The various sort commands differ in how they divide the text into sort
11337: records and in which part of each record is used as the sort key. Most of
11338: the commands make each line a separate sort record, but some commands use
11339: paragraphs or pages as sort records. Most of the sort commands use each
11340: entire sort record as its own sort key, but some use only a portion of the
11341: record as the sort key.
11342:
11343: @findex sort-lines
11344: @findex sort-paragraphs
11345: @findex sort-pages
11346: @findex sort-fields
11347: @findex sort-numeric-fields
11348: @table @kbd
11349: @item M-x sort-lines
11350: Divide the region into lines, and sort by comparing the entire
11351: text of a line. A prefix argument means sort into descending order.
11352:
11353: @item M-x sort-paragraphs
11354: Divide the region into paragraphs, and sort by comparing the entire
11355: text of a paragraph (except for leading blank lines). A prefix
11356: argument means sort into descending order.
11357:
11358: @item M-x sort-pages
11359: Divide the region into pages, and sort by comparing the entire
11360: text of a page (except for leading blank lines). A prefix
11361: argument means sort into descending order.
11362:
11363: @item M-x sort-fields
11364: Divide the region into lines, and sort by comparing the contents of
11365: one field in each line. Fields are defined as separated by
11366: whitespace, so the first run of consecutive non-whitespace characters
11367: in a line constitutes field 1, the second such run constitutes field
11368: 2, etc.
11369:
11370: You specify which field to sort by with a numeric argument: 1 to sort
11371: by field 1, etc. A negative argument means sort into descending
11372: order. Thus, minus 2 means sort by field 2 in reverse-alphabetical
11373: order.
11374:
11375: @item M-x sort-numeric-fields
11376: Like @kbd{M-x sort-fields} except the specified field is converted
11377: to a number for each line, and the numbers are compared. @samp{10}
11378: comes before @samp{2} when considered as text, but after it when
11379: considered as a number.
11380:
11381: @item M-x sort-columns
11382: Like @kbd{M-x sort-fields} except that the text within each line
11383: used for comparison comes from a fixed range of columns. See below
11384: for an explanation.
11385: @end table
11386:
11387: For example, if the buffer contains
11388:
11389: @smallexample
11390: On systems where clash detection (locking of files being edited) is
11391: implemented, Emacs also checks the first time you modify a buffer
11392: whether the file has changed on disk since it was last visited or
11393: saved. If it has, you are asked to confirm that you want to change
11394: the buffer.
11395: @end smallexample
11396:
11397: @noindent
11398: then if you apply @kbd{M-x sort-lines} to the entire buffer you get
11399:
11400: @smallexample
11401: On systems where clash detection (locking of files being edited) is
11402: implemented, Emacs also checks the first time you modify a buffer
11403: saved. If it has, you are asked to confirm that you want to change
11404: the buffer.
11405: whether the file has changed on disk since it was last visited or
11406: @end smallexample
11407:
11408: @noindent
11409: where the upper case `O' comes before all lower case letters. If you apply
11410: instead @kbd{C-u 2 M-x sort-fields} you get
11411:
11412: @smallexample
11413: implemented, Emacs also checks the first time you modify a buffer
11414: saved. If it has, you are asked to confirm that you want to change
11415: the buffer.
11416: On systems where clash detection (locking of files being edited) is
11417: whether the file has changed on disk since it was last visited or
11418: @end smallexample
11419:
11420: @noindent
11421: where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer},
11422: @samp{systems} and @samp{the}.@refill
11423:
11424: @findex sort-columns
11425: @kbd{M-x sort-columns} requires more explanation. You specify the
11426: columns by putting point at one of the columns and the mark at the other
11427: column. Because this means you cannot put point or the mark at the
11428: beginning of the first line to sort, this command uses an unusual
11429: definition of `region': all of the line point is in is considered part of
11430: the region, and so is all of the line the mark is in.
11431:
11432: For example, to sort a table by information found in columns 10 to 15,
11433: you could put the mark on column 10 in the first line of the table, and
11434: point on column 15 in the last line of the table, and then use this command.
11435: Or you could put the mark on column 15 in the first line and point on
11436: column 10 in the last line.
11437:
11438: This can be thought of as sorting the rectangle specified by point and
11439: the mark, except that the text on each line to the left or right of the
11440: rectangle moves along with the text inside the rectangle.
11441: @xref{Rectangles}.
11442:
11443: @node Shell, Hardcopy, Sorting, Top
11444: @section Running Shell Commands from Emacs
11445: @cindex subshell
11446: @cindex shell commands
11447:
11448: Emacs has commands for passing single command lines to inferior shell
11449: processes; it can also run a shell interactively with input and output to
11450: an Emacs buffer @samp{*shell*}.
11451:
11452: @table @kbd
11453: @item M-!
11454: Run a specified shell command line and display the output
11455: (@code{shell-command}).
11456: @item M-|
11457: Run a specified shell command line with region contents as input;
11458: optionally replace the region with the output
11459: (@code{shell-command-on-region}).
11460: @item M-x shell
11461: Run a subshell with input and output through an Emacs buffer.
11462: You can then give commands interactively.
11463: @end table
11464:
11465: @menu
11466: * Single Shell:: How to run one shell command and return.
11467: * Interactive Shell:: Permanent shell taking input via Emacs.
11468: * Shell Mode:: Special Emacs commands used with permanent shell.
11469: @end menu
11470:
11471: @node Single Shell, Interactive Shell, Shell, Shell
11472: @subsection Single Shell Commands
11473:
11474: @kindex M-!
11475: @findex shell-command
11476: @kbd{M-!} (@code{shell-command}) reads a line of text using the
11477: minibuffer and creates an inferior shell to execute the line as a command.
11478: Standard input from the command comes from the null device. If the shell
11479: command produces any output, the output goes into an Emacs buffer named
11480: @samp{*Shell Command Output*}, which is displayed in another window but not
11481: selected. A numeric argument, as in @kbd{M-1 M-!}, directs this command to
11482: insert any output into the current buffer. In that case, point is left
11483: before the output and the mark is set after the output.
11484:
11485: @kindex M-|
11486: @findex shell-command-on-region
11487: @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but passes
11488: the contents of the region as input to the shell command, instead of no
11489: input. If a numeric argument is used, meaning insert output in the current
11490: buffer, then the old region is deleted first and the output replaces it as
11491: the contents of the region.@refill
11492:
11493: @vindex shell-file-name
11494: @cindex environment
11495: Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
11496: shell to use. This variable is initialized based on your @code{SHELL}
11497: environment variable when Emacs is started. If the file name does not
11498: specify a directory, the directories in the list @code{exec-path} are
11499: searched; this list is initialized based on the environment variable
11500: @code{PATH} when Emacs is started. Your @file{.emacs} file can override
11501: either or both of these default initializations.@refill
11502:
11503: With @kbd{M-!} and @kbd{M-|}, Emacs has to wait until the shell command
11504: completes. You can quit with @kbd{C-g}; that terminates the shell command.
11505:
11506: @node Interactive Shell, Shell Mode, Single Shell, Shell
11507: @subsection Interactive Inferior Shell
11508:
11509: @findex shell
11510: To run a subshell interactively, putting its typescript in an Emacs
11511: buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named
11512: @samp{*shell*} and runs a subshell with input coming from and output going
11513: to that buffer. That is to say, any ``terminal output'' from the subshell
11514: will go into the buffer, advancing point, and any ``terminal input'' for
11515: the subshell comes from text in the buffer. To give input to the subshell,
11516: go to the end of the buffer and type the input, terminated by @key{RET}.
11517:
11518: Emacs does not wait for the subshell to do anything. You can switch
11519: windows or buffers and edit them while the shell is waiting, or while it is
11520: running a command. Output from the subshell waits until Emacs has time to
11521: process it; this happens whenever Emacs is waiting for keyboard input or
11522: for time to elapse.
11523:
11524: If you would like multiple subshells, change the name of buffer
11525: @samp{*shell*} to something different by using @kbd{M-x rename-buffer}. The
11526: next use of @kbd{M-x shell} will create a new buffer @samp{*shell*} with
11527: its own subshell. By renaming this buffer as well you can create a third
11528: one, and so on. All the subshells run independently and in parallel.
11529:
11530: @vindex explicit-shell-file-name
11531: The file name used to load the subshell is the value of the variable
11532: @code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise, the
11533: environment variable @code{ESHELL} is used, or the environment variable
11534: @code{SHELL} if there is no @code{ESHELL}. If the file name specified
11535: is relative, the directories in the list @code{exec-path} are searched
11536: (@pxref{Single Shell,Single Shell Commands}).@refill
11537:
11538: As soon as the subshell is started, it is sent as input the contents of
11539: the file @file{~/.emacs_@var{shellname}}, if that file exists, where
11540: @var{shellname} is the name of the file that the shell was loaded from.
11541: For example, if you use @code{csh}, the file sent to it is
11542: @file{~/.emacs_csh}.@refill
11543:
11544: @vindex shell-pushd-regexp
11545: @vindex shell-popd-regexp
11546: @vindex shell-cd-regexp
11547: @code{cd}, @code{pushd} and @code{popd} commands given to the inferior
11548: shell are watched by Emacs so it can keep the @samp{*shell*} buffer's
11549: default directory the same as the shell's working directory. These
11550: commands are recognized syntactically by examining lines of input that are
11551: sent. If you use aliases for these commands, you can tell Emacs to
11552: recognize them also. For example, if the value of the variable
11553: @code{shell-pushd-regexp} matches the beginning of a shell command line,
11554: that line is regarded as a @code{pushd} command. Change this variable when
11555: you add aliases for @samp{pushd}. Likewise, @code{shell-popd-regexp} and
11556: @code{shell-cd-regexp} are used to recognize commands with the meaning of
11557: @samp{popd} and @samp{cd}. These commands are recognized only at the
11558: beginning of a shell command line.@refill
11559:
11560: @vindex shell-set-directory-error-hook
11561: If Emacs gets an error while trying to handle what it believes is
11562: a @samp{cd}, @samp{pushd} or @samp{popd} command, and the value of
11563: @code{shell-set-directory-error-hook} is non-@code{nil}, that value is
11564: called as a function with no arguments.@refill
11565:
11566: @node Shell Mode,, Interactive Shell, Shell
11567: @subsection Shell Mode
11568:
11569: @cindex Shell mode
11570: The shell buffer uses Shell mode, which defines several special keys
11571: attached to the @kbd{C-c} prefix. They are chosen to resemble the usual
11572: editing and job control characters present in shells that are not under
11573: Emacs, except that you must type @kbd{C-c} first. Here is a complete list
11574: of the special key bindings of Shell mode:
11575:
11576: @kindex RET (Shell mode)
11577: @kindex C-c C-d (Shell mode)
11578: @kindex C-c C-u (Shell mode)
11579: @kindex C-c C-w (Shell mode)
11580: @kindex C-c C-c (Shell mode)
11581: @kindex C-c C-z (Shell mode)
11582: @kindex C-c C-\ (Shell mode)
11583: @kindex C-c C-o (Shell mode)
11584: @kindex C-c C-r (Shell mode)
11585: @kindex C-c C-y (Shell mode)
11586: @findex send-shell-input
11587: @findex shell-send-eof
11588: @findex interrupt-shell-subjob
11589: @findex stop-shell-subjob
11590: @findex quit-shell-subjob
11591: @findex kill-output-from-shell
11592: @findex show-output-from-shell
11593: @findex copy-last-shell-input
11594: @vindex shell-prompt-pattern
11595: @table @kbd
11596: @item @key{RET}
11597: At end of buffer send line as input; otherwise, copy current line to end of
11598: buffer and send it (@code{send-shell-input}). When a line is copied, any
11599: text at the beginning of the line that matches the variable
11600: @code{shell-prompt-pattern} is left out; this variable's value should be a
11601: regexp string that matches the prompts that you use in your subshell.
11602: @item C-c C-d
11603: Send end-of-file as input, probably causing the shell or its current
11604: subjob to finish (@code{shell-send-eof}).
11605: @item C-c C-u
11606: Kill all text that has yet to be sent as input (@code{kill-shell-input}).
11607: @item C-c C-w
11608: Kill a word before point (@code{backward-kill-word}).
11609: @item C-c C-c
11610: Interrupt the shell or its current subjob if any
11611: (@code{interrupt-shell-subjob}).
11612: @item C-c C-z
11613: Stop the shell or its current subjob if any (@code{stop-shell-subjob}).
11614: @item C-c C-\
11615: Send quit signal to the shell or its current subjob if any
11616: (@code{quit-shell-subjob}).
11617: @item C-c C-o
11618: Delete last batch of output from shell (@code{kill-output-from-shell}).
11619: @item C-c C-r
11620: Scroll top of last batch of output to top of window
11621: (@code{show-output-from-shell}).
11622: @item C-c C-y
11623: Copy the previous bunch of shell input, and insert it into the
11624: buffer before point (@code{copy-last-shell-input}). No final newline
11625: is inserted, and the input copied is not resubmitted until you type
11626: @key{RET}.
11627: @end table
11628:
11629: @node Hardcopy, Dissociated Press, Shell, Top
11630: @section Hardcopy Output
11631: @cindex hardcopy
11632:
11633: The Emacs commands for making hardcopy derive their names from the
11634: Unix commands @samp{print} and @samp{lpr}.
11635:
11636: @table @kbd
11637: @item M-x print-buffer
11638: Print hardcopy of current buffer using Unix command @samp{print}
11639: (@samp{lpr -p}). This makes page headings containing the file name
11640: and page number.
11641: @item M-x lpr-buffer
11642: Print hardcopy of current buffer using Unix command @samp{lpr}.
11643: This makes no page headings.
11644: @item M-x print-region
11645: Like @code{print-buffer} but prints only the current region.
11646: @item M-x lpr-region
11647: Like @code{lpr-buffer} but prints only the current region.
11648: @end table
11649:
11650: @findex print-buffer
11651: @findex print-region
11652: @findex lpr-buffer
11653: @findex lpr-region
11654: @vindex lpr-switches
11655: All the hardcopy commands pass extra switches to the @code{lpr} program
11656: based on the value of the variable @code{lpr-switches}. Its value should
11657: be a list of strings, each string a switch starting with @samp{-}. For
11658: example, the value could be @code{("-Pfoo")} to print on printer
11659: @samp{foo}.
11660:
11661: @node Dissociated Press, Amusements, Hardcopy, Top
11662: @section Dissociated Press
11663:
11664: @findex dissociated-press
11665: @kbd{M-x dissociated-press} is a command for scrambling a file of text
11666: either word by word or character by character. Starting from a buffer of
11667: straight English, it produces extremely amusing output. The input comes
11668: from the current Emacs buffer. Dissociated Press writes its output in a
11669: buffer named @samp{*Dissociation*}, and redisplays that buffer after every
11670: couple of lines (approximately) to facilitate reading it.
11671:
11672: @code{dissociated-press} asks every so often whether to continue
11673: operating. Answer @kbd{n} to stop it. You can also stop at any time by
11674: typing @kbd{C-g}. The dissociation output remains in the @samp{*Dissociation*}
11675: buffer for you to copy elsewhere if you wish.
11676:
11677: @cindex presidentagon
11678: Dissociated Press operates by jumping at random from one point in the
11679: buffer to another. In order to produce plausible output rather than
11680: gibberish, it insists on a certain amount of overlap between the end of one
11681: run of consecutive words or characters and the start of the next. That is,
11682: if it has just printed out `president' and then decides to jump to a
11683: different point in the file, it might spot the `ent' in `pentagon' and
11684: continue from there, producing `presidentagon'. Long sample texts produce
11685: the best results.
11686:
11687: @cindex againformation
11688: A positive argument to @kbd{M-x dissociated-press} tells it to operate
11689: character by character, and specifies the number of overlap characters. A
11690: negative argument tells it to operate word by word and specifies the number
11691: of overlap words. In this mode, whole words are treated as the elements to
11692: be permuted, rather than characters. No argument is equivalent to an
11693: argument of two. For your againformation, the output goes only into the
11694: buffer @samp{*Dissociation*}. The buffer you start with is not changed.
11695:
11696: @cindex Markov chain
11697: @cindex ignoriginal
11698: @cindex techniquitous
11699: Dissociated Press produces nearly the same results as a Markov chain
11700: based on a frequency table constructed from the sample text. It is,
11701: however, an independent, ignoriginal invention. Dissociated Press
11702: techniquitously copies several consecutive characters from the sample
11703: between random choices, whereas a Markov chain would choose randomly for
11704: each word or character. This makes for more plausible sounding results,
11705: and runs faster.
11706:
11707: @cindex outragedy
11708: @cindex buggestion
11709: @cindex properbose
11710: It is a mustatement that too much use of Dissociated Press can be a
11711: developediment to your real work. Sometimes to the point of outragedy.
11712: And keep dissociwords out of your documentation, if you want it to be well
11713: userenced and properbose. Have fun. Your buggestions are welcome.
11714:
11715: @node Amusements, Emulation, Dissociated Press, Top
11716: @section Other Amusements
11717: @cindex boredom
11718: @findex hanoi
11719: @findex yow
11720:
11721: If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are
11722: considerably bored, give it a numeric argument. If you are very very
11723: bored, try an argument of 9. Sit back and watch.
11724:
11725: When you are frustrated, try the famous Eliza program. Just do
11726: @kbd{M-x doctor}. End each input by typing @kbd{RET} twice.
11727:
11728: When you are feeling strange, type @kbd{M-x yow}.
11729:
11730: @node Emulation, Customization, Amusements, Top
11731: @section Emulation
11732: @cindex other editors
11733: @cindex EDT
11734: @cindex vi
11735:
11736: GNU Emacs can be programmed to emulate (more or less) most other
11737: editors. Standard facilities can emulate these:
11738:
11739: @table @asis
11740: @item EDT (DEC VMS editor)
11741: @findex edt-emulation-on
11742: @findex edt-emulation-off
11743: Turn on EDT emulation with @kbd{M-x edt-emulation-on}. @kbd{M-x
11744: edt-emulation-off} restores normal Emacs command bindings.
11745:
11746: Most of the EDT emulation commands are keypad keys, and most standard
11747: Emacs key bindings are still available. The EDT emulation rebindings
11748: are done in the global keymap, so there is no problem switching
11749: buffers or major modes while in EDT emulation.
11750:
11751: @item Gosling Emacs
11752: @findex set-gosmacs-bindings
11753: @findex set-gnu-bindings
11754: Turn on emulation of Gosling Emacs (aka Unipress Emacs) with @kbd{M-x
11755: set-gosmacs-bindings}. This redefines many keys, mostly on the
11756: @kbd{C-x} and @kbd{ESC} prefixes, to work as they do in Gosmacs.
11757: @kbd{M-x set-gnu-bindings} returns to normal GNU Emacs by rebinding
11758: the same keys to the definitions they had at the time @kbd{M-x
11759: set-gosmacs-bindings} was done.
11760:
11761: It is also possible to run Mocklisp code written for Gosling Emacs.
11762: @xref{Mocklisp}.
11763:
11764: @item vi (Berkeley Unix editor)
11765: @findex vi-mode
11766: Turn on vi emulation with @kbd{M-x vi-mode}. This is a major mode
11767: that replaces the previously established major mode. All of the
11768: vi commands that, in real vi, enter ``input'' mode are programmed
11769: in the Emacs emulator to return to the previous major mode. Thus,
11770: ordinary Emacs serves as vi's ``input'' mode.
11771:
11772: Because vi emulation works through major modes, it does not work
11773: to switch buffers during emulation. Return to normal Emacs first.
11774:
11775: If you plan to use vi emulation much, you probably want to bind a key
11776: to the @code{vi-mode} command.
11777:
11778: @item vi (alternate emulator)
11779: @findex vip-mode
11780: Another vi emulator said to resemble real vi more thoroughly is
11781: invoked by @kbd{M-x vip-mode}. ``Input'' mode in this emulator is
11782: changed from ordinary Emacs so you can use @key{ESC} to go back to
11783: emulated vi command mode. To get from emulated vi command mode back
11784: to ordinary Emacs, type @kbd{C-z}.
11785:
11786: This emulation does not work through major modes, and it is possible
11787: to switch buffers in various ways within the emulator. It is not
11788: so necessary to assign a key to the command @code{vip-mode} as
11789: it is with @code{vi-mode} because terminating insert mode does
11790: not use it.
11791:
11792: For full information, see the long comment at the beginning of the
11793: source file, which is @file{lisp/vip.el} in the Emacs distribution.
11794: @end table
11795:
11796: I am interested in hearing which vi emulator users prefer, as well as in
11797: receiving more complete user documentation for either or both emulators.
11798: Warning: loading both at once may cause name conficts; no one has checked.
11799:
11800: @node Customization, Quitting, Emulation, Top
11801: @chapter Customization
11802: @cindex customization
11803:
11804: This chapter talks about various topics relevant to adapting the
11805: behavior of Emacs in minor ways.
11806:
11807: All kinds of customization affect only the particular Emacs job that you
11808: do them in. They are completely lost when you kill the Emacs job, and have
11809: no effect on other Emacs jobs you may run at the same time or later. The
11810: only way an Emacs job can affect anything outside of it is by writing a
11811: file; in particular, the only way to make a customization `permanent' is to
11812: put something in your @file{.emacs} file or other appropriate file to do the
11813: customization in each session. @xref{Init File}.
11814:
11815: @menu
11816: * Minor Modes:: Each minor mode is one feature you can turn on
11817: independently of any others.
11818: * Variables:: Many Emacs commands examine Emacs variables
11819: to decide what to do; by setting variables,
11820: you can control their functioning.
11821: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
11822: to be replayed with a single command.
11823: * Key Bindings:: The keymaps say what command each key runs.
11824: By changing them, you can "redefine keys".
11825: * Syntax:: The syntax table controls how words and expressions
11826: are parsed.
11827: * Init File:: How to write common customizations in the @file{.emacs} file.
11828: @end menu
11829:
11830: @node Minor Modes, Variables, Customization, Customization
11831: @section Minor Modes
11832: @cindex minor modes
11833:
11834: @cindex mode line
11835: Minor modes are options which you can use or not. For example, Auto Fill
11836: mode is a minor mode in which @key{SPC} breaks lines between words as you
11837: type. All the minor modes are independent of each other and of the
11838: selected major mode. Most minor modes say in the mode line when they are
11839: on; for example, @samp{Fill} in the mode line means that Auto Fill mode is
11840: on.
11841:
11842: Append @code{-mode} to the name of a minor mode to get the name of a
11843: command function that turns the mode on or off. Thus, the command to
11844: enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
11845: commands are usually invoked with @kbd{M-x}, but you can bind keys to them
11846: if you wish. With no argument, the function turns the mode on if it was
11847: off and off if it was on. This is known as @dfn{toggling}. A positive
11848: argument always turns the mode on, and an explicit zero argument or a
11849: negative argument always turns it off.
11850:
11851: @cindex Auto Fill mode
11852: @findex auto-fill-mode
11853: Auto Fill mode allows you to enter filled text without breaking lines
11854: explicitly. Emacs inserts newlines as necessary to prevent lines from
11855: becoming too long. @xref{Filling}.
11856:
11857: @cindex Overwrite mode
11858: @findex overwrite-mode
11859: Overwrite mode causes ordinary printing characters to replace existing
11860: text instead of shoving it over. For example, if the point is in front of
11861: the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a @kbd{G}
11862: changes it to @samp{FOOGAR}, instead of making it @samp{FOOGBAR} as
11863: usual.@refill
11864:
11865: @cindex Abbrev mode
11866: @findex abbrev-mode
11867: Abbrev mode allows you to define abbreviations that automatically expand
11868: as you type them. For example, @samp{amd} might expand to @samp{abbrev
11869: mode}. @xref{Abbrevs}, for full information.
11870:
11871: @node Variables, Keyboard Macros, Minor Modes, Customization
11872: @section Variables
11873: @cindex variable
11874: @cindex option
11875:
11876: A @dfn{variable} is a Lisp symbol which has a value. The symbol's name
11877: is also called the name of the variable. Variable names can contain any
11878: characters, but conventionally they are chosen to be words separated by
11879: hyphens. A variable can have a documentation string which describes what
11880: kind of value it should have and how the value will be used.
11881:
11882: Lisp allows any variable to have any kind of value, but most variables
11883: that Emacs uses require a value of a certain type. Often the value should
11884: always be a string, or should always be a number. Sometimes we say that a
11885: certain feature is turned on if a variable is ``non-@code{nil},'' meaning
11886: that if the variable's value is @code{nil}, the feature is off, but the
11887: feature is on for @i{any} other value. The conventional value to use to
11888: turn on the feature---since you have to pick one particular value when you
11889: set the variable---is @code{t}.
11890:
11891: Emacs uses many Lisp variables for internal recordkeeping, as any Lisp
11892: program must, but the most interesting variables for you are the ones that
11893: exist for the sake of customization. Emacs does not (usually) change the
11894: values of these variables; instead, you set the values, and thereby alter
11895: and control the behavior of certain Emacs commands. These variables are
11896: called @dfn{options}. Most options are documented in this manual, and
11897: appear in the Variable Index (@pxref{Variable Index}).
11898:
11899: One example of a variable which is an option is @code{fill-column}, which
11900: specifies the position of the right margin (as a number of characters from
11901: the left margin) to be used by the fill commands (@pxref{Filling}).
11902:
11903: @menu
11904: * Examining:: Examining or setting one variable's value.
11905: * Edit Options:: Examining or editing list of all variables' values.
11906: * Locals:: Per-buffer values of variables.
11907: * File Variables:: How files can specify variable values.
11908: @end menu
11909:
11910: @node Examining, Edit Options, Variables, Variables
11911: @subsection Examining and Setting Variables
11912: @cindex setting variables
11913:
11914: @table @kbd
11915: @item C-h v
11916: @itemx M-x describe-variable
11917: Print the value and documentation of a variable.
11918: @item M-x set-variable
11919: Change the value of a variable.
11920: @end table
11921:
11922: @kindex C-h v
11923: @findex describe-variable
11924: To examine the value of a single variable, use @kbd{C-h v}
11925: (@code{describe-variable}), which reads a variable name using the
11926: minibuffer, with completion. It prints both the value and the
11927: documentation of the variable.
11928:
11929: @example
11930: C-h v fill-column @key{RET}
11931: @end example
11932: @noindent
11933: prints something like
11934: @smallexample
11935: fill-column's value is 75
11936:
11937: Documentation:
11938: *Column beyond which automatic line-wrapping should happen.
11939: Automatically becomes local when set in any fashion.
11940: @end smallexample
11941:
11942: @cindex option
11943: @noindent
11944: The star at the beginning of the documentation indicates that this variable
11945: is an option. @kbd{C-h v} is not restricted to options; it allows any
11946: variable name.
11947:
11948: @findex set-variable
11949: If you know which option you want to set, you can set it using @kbd{M-x
11950: set-variable}. This reads the variable name with the minibuffer (with
11951: completion), and then reads a Lisp expression for the new value using the
11952: minibuffer a second time. For example,
11953:
11954: @example
11955: M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
11956: @end example
11957:
11958: @noindent
11959: sets @code{fill-column} to 75, like executing the Lisp expression
11960:
11961: @example
11962: (setq fill-column 75)
11963: @end example
11964:
11965: Setting variables in this way, like all means of customizing Emacs
11966: except where explicitly stated, affects only the current Emacs session.
11967:
11968: @node Edit Options, Locals, Examining, Variables
11969: @subsection Editing Variable Values
11970:
11971: @table @kbd
11972: @item M-x list-options
11973: Display a buffer listing names, values and documentation of all options.
11974: @item M-x edit-options
11975: Change option values by editing a list of options.
11976: @end table
11977:
11978: @findex list-options
11979: @kbd{M-x list-options} displays a list of all Emacs option variables, in
11980: an Emacs buffer named @samp{*List Options*}. Each option is shown with its
11981: documentation and its current value. Here is what a portion of it might
11982: look like:
11983:
11984: @smallexample
11985: ;; exec-path:
11986: ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
11987: *List of directories to search programs to run in subprocesses.
11988: Each element is a string (directory name)
11989: or nil (try the default directory).
11990: ;;
11991: ;; fill-column:
11992: 75
11993: *Column beyond which automatic line-wrapping should happen.
11994: Automatically becomes local when set in any fashion.
11995: ;;
11996: @end smallexample
11997:
11998: @findex edit-options
11999: @kbd{M-x edit-options} goes one step further and immediately selects the
12000: @samp{*List Options*} buffer; this buffer uses the major mode Options mode,
12001: which provides commands that allow you to point at an option and change its
12002: value:
12003:
12004: @table @kbd
12005: @item s
12006: Set the variable point is in or near to a new value read using the
12007: minibuffer.
12008: @item x
12009: Toggle the variable point is in or near: if the value was @code{nil},
12010: it becomes @code{t}; otherwise it becomes @code{nil}.
12011: @item 1
12012: Set the variable point is in or near to @code{t}.
12013: @item 0
12014: Set the variable point is in or near to @code{nil}.
12015: @item n
12016: @itemx p
12017: Move to the next or previous variable.
12018: @end table
12019:
12020: @node Locals, File Variables, Edit Options, Variables
12021: @subsection Local Variables
12022:
12023: @table @kbd
12024: @item M-x make-local-variable
12025: Make a variable have a local value in the current buffer.
12026: @item M-x kill-local-variable
12027: Make a variable use its global value in the current buffer.
12028: @item M-x make-variable-buffer-local
12029: Mark a variable so that setting it will make it local to the
12030: buffer that is current at that time.
12031: @end table
12032:
12033: @cindex local variables
12034: Any variable can be made @dfn{local} to a specific Emacs buffer. This
12035: means that its value in that buffer is independent of its value in other
12036: buffers. A few variables are always local in every buffer. Every other
12037: Emacs variable has a @dfn{global} value which is in effect in all buffers
12038: that have not made the variable local.
12039:
12040: Major modes always make the variables they set local to the buffer.
12041: This is why changing major modes in one buffer has no effect on other
12042: buffers.
12043:
12044: @findex make-local-variable
12045: @kbd{M-x make-local-variable} reads the name of a variable and makes it
12046: local to the current buffer. Further changes in this buffer will not
12047: affect others, and further changes in the global value will not affect this
12048: buffer.
12049:
12050: @findex make-variable-buffer-local
12051: @cindex per-buffer variables
12052: @kbd{M-x make-variable-buffer-local} reads the name of a variable and
12053: changes the future behavior of the variable so that it will become local
12054: automatically when it is set. More precisely, once a variable has been
12055: marked in this way, the usual ways of setting the variable will
12056: automatically do @code{make-local-variable} first. We call such variables
12057: @dfn{per-buffer} variables.
12058:
12059: Some important variables have been marked per-buffer already. These include
12060: @code{abbrev-mode}, @code{auto-fill-hook}, @code{case-fold-search},
12061: @code{comment-column}, @code{ctl-arrow}, @code{fill-column},
12062: @code{fill-prefix}, @code{indent-tabs-mode}, @code{left-margin},
12063: @code{mode-line-format}, @code{overwrite-mode},@*
12064: @code{selective-display-ellipses}, @code{selective-display},
12065: @code{tab-width}, and @code{truncate-lines}. Some other variables are
12066: always local in every buffer, but they are used for internal purposes.@refill
12067:
12068: @findex kill-local-variable
12069: @kbd{M-x kill-local-variable} reads the name of a variable and makes it
12070: cease to be local to the current buffer. The global value of the variable
12071: henceforth is in effect in this buffer. Setting the major mode kills all
12072: the local variables of the buffer.
12073:
12074: @findex setq-default
12075: To set the global value of a variable, regardless of whether the
12076: variable has a local value in the current buffer, you can use the
12077: Lisp function @code{setq-default}. It works like @code{setq}.
12078: If there is a local value in the current buffer, the local value is
12079: not affected by @code{setq-default}; thus, the new global value may
12080: not be visible until you switch to another buffer. For example,
12081:
12082: @example
12083: (setq-default fill-column 75)
12084: @end example
12085:
12086: @noindent
12087: @code{setq-default} is the only way to set the global value of a variable
12088: that has been marked with @code{make-variable-buffer-local}.
12089:
12090: @findex default-value
12091: Programs can look at a variable's default value with @code{default-value}.
12092: This function takes a symbol as argument and returns its default value.
12093: The argument is evaluated; usually you must quote it explicitly. For
12094: example,
12095:
12096: @example
12097: (default-value 'fill-column)
12098: @end example
12099:
12100: @node File Variables,, Locals, Variables
12101: @subsection Local Variables in Files
12102: @cindex local variables in files
12103:
12104: A file can contain a @dfn{local variables list}, which specifies the
12105: values to use for certain Emacs variables when that file is edited.
12106: Visiting the file checks for a local variables list and makes each variable
12107: in the list local to the buffer in which the file is visited, with the
12108: value specified in the file.
12109:
12110: A local variables list goes near the end of the file, in the last page.
12111: (It is often best to put it on a page by itself.) The local variables list
12112: starts with a line containing the string @samp{Local Variables:}, and ends
12113: with a line containing the string @samp{End:}. In between come the
12114: variable names and values, one set per line, as @samp{@var{variable}:@:
12115: @var{value}}. The @var{value}s are not evaluated; they are used literally.
12116:
12117: The line which starts the local variables list does not have to say just
12118: @samp{Local Variables:}. If there is other text before @samp{Local
12119: Variables:}, that text is called the @dfn{prefix}, and if there is other
12120: text after, that is called the @dfn{suffix}. If these are present, each
12121: entry in the local variables list should have the prefix before it and the
12122: suffix after it. This includes the @samp{End:} line. The prefix and
12123: suffix are included to disguise the local variables list as a comment so
12124: that the compiler or text formatter will not be perplexed by it. If you do
12125: not need to disguise the local variables list as a comment in this way, do
12126: not bother with a prefix or a suffix.@refill
12127:
12128: Two ``variable'' names are special in a local variables list: a value for
12129: the variable @code{mode} really sets the major mode, and a value for the
12130: variable @code{eval} is simply evaluated as an expression and the value is
12131: ignored. These are not real variables; setting such variables in any other
12132: context has no such effect. If @code{mode} is used in a local variables
12133: list, it should be the first entry in the list.
12134:
12135: Here is an example of a local variables list:
12136: @example
12137: ;;; Local Variables: ***
12138: ;;; mode:lisp ***
12139: ;;; comment-column:0 ***
12140: ;;; comment-start: ";;; " ***
12141: ;;; comment-end:"***" ***
12142: ;;; End: ***
12143: @end example
12144:
12145: Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}. Note also
12146: that comments in the file begin with and end with the same strings.
12147: Presumably the file contains code in a language which is like Lisp
12148: (like it enough for Lisp mode to be useful) but in which comments start
12149: and end in that way. The prefix and suffix are used in the local
12150: variables list to make the list appear as comments when the file is read
12151: by the compiler or interpreter for that language.
12152:
12153: The start of the local variables list must be no more than 3000
12154: characters from the end of the file, and must be in the last page if the
12155: file is divided into pages. Otherwise, Emacs will not notice it is there.
12156: The purpose of this is so that a stray @samp{Local Variables:}@: not in the
12157: last page does not confuse Emacs, and so that visiting a long file that is
12158: all one page and has no local variables list need not take the time to
12159: search the whole file.
12160:
12161: You may be tempted to try to turn on Auto Fill mode with a local variable
12162: list. That is a mistake. The choice of Auto Fill mode or not is a matter
12163: of individual taste, not a matter of the contents of particular files.
12164: If you want to use Auto Fill, set up major mode hooks with your @file{.emacs}
12165: file to turn it on (when appropriate) for you alone (@pxref{Init File}).
12166: Don't try to use a local variable list that would impose your taste on
12167: everyone.
12168:
12169: @node Keyboard Macros, Key Bindings, Variables, Customization
12170: @section Keyboard Macros
12171:
12172: @cindex keyboard macros
12173: A @dfn{keyboard macro} is a command defined by the user to abbreviate a
12174: sequence of keys. For example, if you discover that you are about to type
12175: @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
12176: macro to do @kbd{C-n C-d} and calling it with a repeat count of forty.
12177:
12178: @c widecommands
12179: @table @kbd
12180: @item C-x (
12181: Start defining a keyboard macro (@code{start-kbd-macro}).
12182: @item C-x )
12183: End the definition of a keyboard macro (@code{end-kbd-macro}).
12184: @item C-x e
12185: Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
12186: @item C-u C-x (
12187: Re-execute last keyboard macro, then add more keys to its definition.
12188: @item C-x q
12189: When this point is reached during macro execution, ask for confirmation
12190: (@code{kbd-macro-query}).
12191: @item M-x name-last-kbd-macro
12192: Give a command name (for the duration of the session) to the most
12193: recently defined keyboard macro.
12194: @item M-x insert-kbd-macro
12195: Insert in the buffer a keyboard macro's definition, as Lisp code.
12196: @end table
12197:
12198: Keyboard macros differ from ordinary Emacs commands in that they are
12199: written in the Emacs command language rather than in Lisp. This makes it
12200: easier for the novice to write them, and makes them more convenient as
12201: temporary hacks. However, the Emacs command language is not powerful
12202: enough as a programming language to be useful for writing anything
12203: intelligent or general. For such things, Lisp must be used.
12204:
12205: You define a keyboard macro while executing the commands which are the
12206: definition. Put differently, as you are defining a keyboard macro, the
12207: definition is being executed for the first time. This way, you can see
12208: what the effects of your commands are, so that you don't have to figure
12209: them out in your head. When you are finished, the keyboard macro is
12210: defined and also has been, in effect, executed once. You can then do the
12211: whole thing over again by invoking the macro.
12212:
12213: @menu
12214: * Basic Kbd Macro:: Defining and running keyboard macros.
12215: * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
12216: * Kbd Macro Query:: Keyboard macros that do different things each use.
12217: @end menu
12218:
12219: @node Basic Kbd Macro, Save Kbd Macro, Keyboard Macros, Keyboard Macros
12220: @subsection Basic Use
12221:
12222: @kindex C-x (
12223: @kindex C-x )
12224: @kindex C-x e
12225: @findex start-kbd-macro
12226: @findex end-kbd-macro
12227: @findex call-last-kbd-macro
12228: To start defining a keyboard macro, type the @kbd{C-x (} command
12229: (@code{start-kbd-macro}). From then on, your keys continue to be
12230: executed, but also become part of the definition of the macro. @samp{Def}
12231: appears in the mode line to remind you of what is going on. When you are
12232: finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
12233: definition (without becoming part of it!). For example
12234:
12235: @example
12236: C-x ( M-F foo C-x )
12237: @end example
12238:
12239: @noindent
12240: defines a macro to move forward a word and then insert @samp{foo}.
12241:
12242: The macro thus defined can be invoked again with the @kbd{C-x e} command
12243: (@code{call-last-kbd-macro}), which may be given a repeat count as a
12244: numeric argument to execute the macro many times. @kbd{C-x )} can also be
12245: given a repeat count as an argument, in which case it repeats the macro
12246: that many times right after defining it, but defining the macro counts as
12247: the first repetition (since it is executed as you define it). So, giving
12248: @kbd{C-x )} an argument of 4 executes the macro immediately 3 additional
12249: times. An argument of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the
12250: macro indefinitely (until it gets an error or you type @kbd{C-g}).
12251:
12252: If you wish to repeat an operation at regularly spaced places in the
12253: text, define a macro and include as part of the macro the commands to move
12254: to the next place you want to use it. For example, if you want to change
12255: each line, you should position point at the start of a line, and define a
12256: macro to change that line and leave point at the start of the next line.
12257: Then repeating the macro will operate on successive lines.
12258:
12259: After you have terminated the definition of a keyboard macro, you can add
12260: to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
12261: to plain @kbd{C-x (} followed by retyping the whole definition so far. As
12262: a consequence it re-executes the macro as previously defined.
12263:
12264: @node Save Kbd Macro, Kbd Macro Query, Basic Kbd Macro, Keyboard Macros
12265: @subsection Naming and Saving Keyboard Macros
12266:
12267: @findex name-last-kbd-macro
12268: If you wish to save a keyboard macro for longer than until you define the
12269: next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
12270: This reads a name as an argument using the minibuffer and defines that name
12271: to execute the macro. The macro name is a Lisp symbol, and defining it in
12272: this way makes it a valid command name for calling with @kbd{M-x} or for
12273: binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
12274: specify a name that has a prior definition other than another keyboard
12275: macro, an error message is printed and nothing is changed.
12276:
12277: @findex insert-kbd-macro
12278: Once a macro has a command name, you can save its definition in a file.
12279: Then it can be used in another editing session. First visit the file
12280: you want to save the definition in. Then use the command
12281:
12282: @example
12283: M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
12284: @end example
12285:
12286: @noindent
12287: This inserts some Lisp code that, when executed later, will define the same
12288: macro with the same definition it has now. You need not understand Lisp
12289: code to do this, because @code{insert-kbd-macro} writes the Lisp code for you.
12290: Then save the file. The file can be loaded with @code{load-file}
12291: (@pxref{Lisp Libraries}). If the file you save in is your init file
12292: @file{~/.emacs} (@pxref{Init File}) then the macro will be defined each
12293: time you run Emacs.
12294:
12295: If you give @code{insert-kbd-macro} a prefix argument, it makes
12296: additional Lisp code to record the keys (if any) that you have bound to the
12297: keyboard macro, so that the macro will be reassigned the same keys when you
12298: load the file.
12299:
12300: @node Kbd Macro Query,, Save Kbd Macro, Keyboard Macros
12301: @subsection Executing Macros with Variations
12302:
12303: @kindex C-x q
12304: @findex kbd-macro-query
12305: Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect similar
12306: to that of @code{query-replace}, where the macro asks you each time around
12307: whether to make a change. When you are defining the macro, type @kbd{C-x
12308: q} at the point where you want the query to occur. During macro
12309: definition, the @kbd{C-x q} does nothing, but when the macro is invoked the
12310: @kbd{C-x q} reads a character from the terminal to decide whether to
12311: continue.
12312:
12313: The special answers are @key{SPC}, @key{DEL}, @kbd{C-d}, @kbd{C-l} and
12314: @kbd{C-r}. Any other character terminates execution of the keyboard macro
12315: and is then read as a command. @key{SPC} means to continue. @key{DEL}
12316: means to skip the remainder of this repetition of the macro, starting again
12317: from the beginning in the next repetition. @kbd{C-d} means to skip the
12318: remainder of this repetition and cancel further repetition. @kbd{C-l}
12319: redraws the screen and asks you again for a character to say what to do.
12320: @kbd{C-r} enters a recursive editing level, in which you can perform
12321: editing which is not part of the macro. When you exit the recursive edit
12322: using @kbd{C-M-c}, you are asked again how to continue with the keyboard
12323: macro. If you type a @key{SPC} at this time, the rest of the macro
12324: definition is executed. It is up to you to leave point and the text in a
12325: state such that the rest of the macro will do what you want.@refill
12326:
12327: @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a
12328: different function. It enters a recursive edit reading input from the
12329: keyboard, both when you type it during the definition of the macro, and
12330: when it is executed from the macro. During definition, the editing you do
12331: inside the recursive edit does not become part of the macro. During macro
12332: execution, the recursive edit gives you a chance to do some particularized
12333: editing. @xref{Recursive Edit}.
12334:
12335: @node Key Bindings, Syntax, Keyboard Macros, Customization
12336: @section Customizing Key Bindings
12337:
12338: This section deals with the @dfn{keymaps} which define the bindings
12339: between keys and functions, and shows how you can customize these bindings.
12340: @cindex command
12341: @cindex function
12342: @cindex command name
12343:
12344: A command is a Lisp function whose definition provides for interactive
12345: use. Like every Lisp function, a command has a function name, a Lisp
12346: symbol whose name usually consists of lower case letters and hyphens.
12347:
12348: @menu
12349: * Keymaps:: Definition of the keymap data structure.
12350: Names of Emacs's standard keymaps.
12351: * Rebinding:: How to redefine one key's meaning conveniently.
12352: * Disabling:: Disabling a command means confirmation is required
12353: before it can be executed. This is done to protect
12354: beginners from surprises.
12355: @end menu
12356:
12357: @node Keymaps, Rebinding, Key Bindings, Key Bindings
12358: @subsection Keymaps
12359: @cindex keymap
12360:
12361: @cindex global keymap
12362: @vindex global-map
12363: The bindings between characters and command functions are recorded in
12364: data structures called @dfn{keymaps}. Emacs has many of these. One, the
12365: @dfn{global} keymap, defines the meanings of the single-character keys that
12366: are defined regardless of major mode. It is the value of the variable
12367: @code{global-map}.
12368:
12369: @cindex local keymap
12370: @vindex c-mode-map
12371: @vindex lisp-mode-map
12372: Each major mode has another keymap, its @dfn{local keymap}, which
12373: contains overriding definitions for the single-character keys that are to
12374: be redefined in that mode. Each buffer records which local keymap is
12375: installed for it at any time, and the current buffer's local keymap is the
12376: only one that directly affects command execution. The local keymaps for
12377: Lisp mode, C mode, and many other major modes always exist even when not in
12378: use. They are the values of the variables @code{lisp-mode-map},
12379: @code{c-mode-map}, and so on. For major modes less often used, the local
12380: keymap is sometimes constructed only when the mode is used for the first
12381: time in a session. This is to save space.
12382:
12383: @cindex minibuffer
12384: @vindex minibuffer-local-map
12385: @vindex minibuffer-local-ns-map
12386: @vindex minibuffer-local-completion-map
12387: @vindex minibuffer-local-must-match-map
12388: @vindex repeat-complex-command-map
12389: There are local keymaps for the minibuffer too; they contain various
12390: completion and exit commands.
12391:
12392: @itemize @bullet
12393: @item
12394: @code{minibuffer-local-map} is used for ordinary input (no completion).
12395: @item
12396: @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
12397: just like @key{RET}. This is used mainly for Mocklisp compatibility.
12398: @item
12399: @code{minibuffer-local-completion-map} is for permissive completion.
12400: @item
12401: @code{minibuffer-local-must-match-map} is for strict completion and
12402: for cautious completion.
12403: @item
12404: @code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}.
12405: @end itemize
12406:
12407: @vindex ctl-x-map
12408: @vindex help-map
12409: @vindex esc-map
12410: Finally, each prefix key has a keymap which defines the key sequences
12411: that start with it. For example, @code{ctl-x-map} is the keymap used for
12412: characters following a @kbd{C-x}.
12413:
12414: @itemize @bullet
12415: @item
12416: @code{ctl-x-map} is the variable name for the map used for characters that
12417: follow @kbd{C-x}.
12418: @item
12419: @code{help-map} is used for characters that follow @kbd{C-h}.
12420: @item
12421: @code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta
12422: characters are actually defined by this map.
12423: @item
12424: @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
12425: @item
12426: @code{mode-specific-map} is for characters that follow @kbd{C-c}.
12427: @end itemize
12428:
12429: The definition of a prefix key is just the keymap to use for looking up
12430: the following character. Actually, the definition is sometimes a Lisp
12431: symbol whose function definition is the following character keymap. The
12432: effect is the same, but it provides a command name for the prefix key that
12433: can be used as a description of what the prefix key is for. Thus, the
12434: binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
12435: definition is the keymap for @kbd{C-x} commands, the value of
12436: @code{ctl-x-map}.@refill
12437:
12438: Prefix key definitions of this sort can appear in either the global map
12439: or a local map. The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC}
12440: as prefix keys appear in the global map, so these prefix keys are always
12441: available. Major modes can locally redefine a key as a prefix by putting
12442: a prefix key definition for it in the local map.@refill
12443:
12444: A mode can also put a prefix definition of a global prefix character such
12445: as @kbd{C-x} into its local map. This is how major modes override the
12446: definitions of certain keys that start with @kbd{C-x}. This case is
12447: special, because the local definition does not entirely replace the global
12448: one. When both the global and local definitions of a key are other
12449: keymaps, the next character is looked up in both keymaps, with the local
12450: definition overriding the global one as usual. So, the character after the
12451: @kbd{C-x} is looked up in both the major mode's own keymap for redefined
12452: @kbd{C-x} commands and in @code{ctl-x-map}. If the major mode's own keymap
12453: for @kbd{C-x} commands contains @code{nil}, the definition from the global
12454: keymap for @kbd{C-x} commands is used.@refill
12455:
12456: @cindex sparse keymap
12457: A keymap is actually a Lisp object. The simplest form of keymap is a
12458: Lisp vector of length 128. The binding for a character in such a keymap is
12459: found by indexing into the vector with the character as an index. A keymap
12460: can also be a Lisp list whose car is the symbol @code{keymap} and whose
12461: remaining elements are pairs of the form @code{(@var{char} .@: @var{binding})}.
12462: Such lists are called @dfn{sparse keymaps} because they are used when most
12463: of the characters' entries will be @code{nil}. Sparse keymaps are used
12464: mainly for prefix characters.
12465:
12466: Keymaps are only of length 128, so what about Meta characters, whose
12467: codes are from 128 to 255? A key that contains a Meta character actually
12468: represents it as a sequence of two characters, the first of which is
12469: @key{ESC}. So the key @kbd{M-a} is really represented as @kbd{@key{ESC}
12470: a}, and its binding is found at the slot for @samp{a} in
12471: @code{esc-map}.@refill
12472:
12473: @node Rebinding, Disabling, Keymaps, Key Bindings
12474: @subsection Changing Key Bindings Interactively
12475: @cindex key rebinding, this session
12476: @cindex rebinding keys, this session
12477: @cindex rebinding keys, this session
12478:
12479: The way to redefine an Emacs key is to change its entry in a keymap.
12480: You can change the global keymap, in which case the change is effective in
12481: all major modes (except those that have their own overriding local
12482: definitions for the same key). Or you can change the current buffer's
12483: local map, which affects all buffers using the same major mode.
12484: @findex global-set-key
12485: @findex local-set-key
12486:
12487: @table @kbd
12488: @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
12489: Defines @var{key} globally to run @var{cmd}.
12490: @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
12491: Defines @var{key} locally (in the major mode now in effect) to run
12492: @var{cmd}.
12493: @end table
12494:
12495: For example,
12496:
12497: @example
12498: M-x global-set-key @key{RET} C-f next-line @key{RET}
12499: @end example
12500:
12501: @noindent
12502: would redefine @kbd{C-f} to move down a line. The fact that @var{cmd} is
12503: read second makes it serve as a kind of confirmation for @var{key}.
12504:
12505: These functions offer no way to specify a particular prefix keymap as the
12506: one to redefine in, but that is not necessary, as you can include prefixes
12507: in @var{key}. @var{key} is read by reading characters one by one until
12508: they amount to a complete key (that is, not a prefix key). Thus, if you
12509: type @kbd{C-f} for @var{key}, that's the end; the minibuffer is entered
12510: immediately to read @var{cmd}. But if you type @kbd{C-x}, another
12511: character is read; if that is @kbd{4}, another character is read, and so
12512: on. For example,@refill
12513:
12514: @example
12515: M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
12516: @end example
12517:
12518: @noindent
12519: would redefine @kbd{C-x 4 $} to run the (fictitious) command
12520: @code{spell-other-window}.
12521:
12522: @findex define-key
12523: @findex substitute-key-definition
12524: The most general way to modify a keymap is the function @code{define-key},
12525: used in Lisp code (such as your @file{.emacs} file). @code{define-key}
12526: takes three arguments: the keymap, the key to modify in it, and the new
12527: definition. @xref{Init File}, for an example. @code{substitute-key-definition}
12528: is used similarly; it takes three arguments, an old definition, a new
12529: definition and a keymap, and redefines in that keymap all keys that were
12530: previously defined with the old definition to have the new definition
12531: instead.
12532:
12533: @node Disabling,, Rebinding, Key Bindings
12534: @subsection Disabling Commands
12535: @cindex disabled command
12536:
12537: Disabling a command marks the command as requiring confirmation before it
12538: can be executed. The purpose of disabling a command is to prevent
12539: beginning users from executing it by accident and being confused.
12540:
12541: The direct mechanism for disabling a command is to have a non-@code{nil}
12542: @code{disabled} property on the Lisp symbol for the command. These
12543: properties are normally set up by the user's @file{.emacs} file with
12544: Lisp expressions such as
12545:
12546: @example
12547: (put 'delete-region 'disabled t)
12548: @end example
12549:
12550: If the value of the @code{disabled} property is a string, that string
12551: is included in the message printed when the command is used:
12552:
12553: @example
12554: (put 'delete-region 'disabled
12555: "Text deleted this way cannot be yanked back!\n")
12556: @end example
12557:
12558: @findex disable-command
12559: @findex enable-command
12560: You can make a command disabled either by editing the @file{.emacs} file
12561: directly or with the command @kbd{M-x disable-command}, which edits the
12562: @file{.emacs} file for you. @xref{Init File}.
12563:
12564: Attempting to invoke a disabled command interactively in Emacs causes the
12565: display of a window containing the command's name, its documentation, and
12566: some instructions on what to do immediately; then Emacs asks for input
12567: saying whether to execute the command as requested, enable it and execute,
12568: or cancel it. If you decide to enable the command, you are asked whether to
12569: do this permanently or just for the current session. Enabling permanently
12570: works by automatically editing your @file{.emacs} file. You can use
12571: @kbd{M-x enable-command} at any time to enable any command permanently.
12572:
12573: Whether a command is disabled is independent of what key is used to
12574: invoke it; it also applies if the command is invoked using @kbd{M-x}.
12575: Disabling a command has no effect on calling it as a function from Lisp
12576: programs.
12577:
12578: @node Syntax, Init File, Key Bindings, Customization
12579: @section The Syntax Table
12580: @cindex syntax table
12581:
12582: All the Emacs commands which parse words or balance parentheses are
12583: controlled by the @dfn{syntax table}. The syntax table says which
12584: characters are opening delimiters, which are parts of words, which are
12585: string quotes, and so on. Actually, each major mode has its own syntax
12586: table (though sometimes related major modes use the same one) which it
12587: installs in each buffer that uses that major mode. The syntax table
12588: installed in the current buffer is the one that all commands use, so we
12589: call it ``the'' syntax table. A syntax table is a Lisp object, a vector of
12590: length 256 whose elements are numbers.
12591:
12592: @menu
12593: * Entry: Syntax Entry. What the syntax table records for each character.
12594: * Change: Syntax Change. How to change the information.
12595: @end menu
12596:
12597: @node Syntax Entry, Syntax Change, Syntax, Syntax
12598: @subsection Information about Each Character
12599:
12600: The syntax table entry for a character is a number that encodes six
12601: pieces of information:
12602:
12603: @itemize @bullet
12604: @item
12605: The syntactic class of the character, represented as a small integer.
12606: @item
12607: The matching delimiter, for delimiter characters only.
12608: The matching delimiter of @samp{(} is @samp{)}, and vice versa.
12609: @item
12610: A flag saying whether the character is the first character of a
12611: two-character comment starting sequence.
12612: @item
12613: A flag saying whether the character is the second character of a
12614: two-character comment starting sequence.
12615: @item
12616: A flag saying whether the character is the first character of a
12617: two-character comment ending sequence.
12618: @item
12619: A flag saying whether the character is the second character of a
12620: two-character comment ending sequence.
12621: @end itemize
12622:
12623: The syntactic classes are stored internally as small integers, but are
12624: usually described to or by the user with characters. For example, @samp{(}
12625: is used to specify the syntactic class of opening delimiters. Here is a
12626: table of syntactic classes, with the characters that specify them.
12627:
12628: @table @samp
12629: @item @w{ }
12630: The class of whitespace characters.
12631: @item w
12632: The class of word-constituent characters.
12633: @item _
12634: The class of characters that are part of symbol names but not words.
12635: This class is represented by @samp{_} because the character @samp{_}
12636: has this class in both C and Lisp.
12637: @item .
12638: The class of punctuation characters that do not fit into any other
12639: special class.
12640: @item (
12641: The class of opening delimiters.
12642: @item )
12643: The class of closing delimiters.
12644: @item '
12645: The class of expression-adhering characters. These characters are
12646: part of a symbol if found within or adjacent to one, and are part
12647: of a following expression if immediately preceding one, but are like
12648: whitespace if surrounded by whitespace.
12649: @item "
12650: The class of string-quote characters. They match each other in pairs,
12651: and the characters within the pair all lose their syntactic
12652: significance except for the @samp{\} and @samp{/} classes of escape
12653: characters, which can be used to include a string-quote inside the
12654: string.
12655: @item $
12656: The class of self-matching delimiters. This is intended for @TeX{}'s
12657: @samp{$}, which is used both to enter and leave math mode. Thus,
12658: a pair of matching @samp{$} characters surround each piece of math mode
12659: @TeX{} input. A pair of adjacent @samp{$} characters act like a single
12660: one for purposes of matching
12661:
12662: @item /
12663: The class of escape characters that always just deny the following
12664: character its special syntactic significance. The character after one
12665: of these escapes is always treated as alphabetic.
12666: @item \
12667: The class of C-style escape characters. In practice, these are
12668: treated just like @samp{/}-class characters, because the extra
12669: possibilities for C escapes (such as being followed by digits) have no
12670: effect on where the containing expression ends.
12671: @item <
12672: The class of comment-starting characters. Only single-character
12673: comment starters (such as @samp{;} in Lisp mode) are represented this
12674: way.
12675: @item >
12676: The class of comment-ending characters. Newline has this syntax in
12677: Lisp mode.
12678: @end table
12679:
12680: @vindex parse-sexp-ignore-comments
12681: The characters flagged as part of two-character comment delimiters can
12682: have other syntactic functions most of the time. For example, @samp{/} and
12683: @samp{*} in C code, when found separately, have nothing to do with
12684: comments. The comment-delimiter significance overrides when the pair of
12685: characters occur together in the proper order. Only the list and sexp
12686: commands use the syntax table to find comments; the commands specifically
12687: for comments have other variables that tell them where to find comments.
12688: And the list and sexp commands notice comments only if
12689: @code{parse-sexp-ignore-comments} is non-@code{nil}. This variable is set
12690: to @code{nil} in modes where comment-terminator sequences are liable to
12691: appear where there is no comment; for example, in Lisp mode where the
12692: comment terminator is a newline but not every newline ends a comment.
12693:
12694: @node Syntax Change,, Syntax Entry, Syntax
12695: @subsection Altering Syntax Information
12696:
12697: It is possible to alter a character's syntax table entry by storing a new
12698: number in the appropriate element of the syntax table, but it would be hard
12699: to determine what number to use. Therefore, Emacs provides a command that
12700: allows you to specify the syntactic properties of a character in a
12701: convenient way.
12702:
12703: @findex modify-syntax-entry
12704: @kbd{M-x modify-syntax-entry} is the command to change a character's
12705: syntax. It can be used interactively, and is also the means used by major
12706: modes to initialize their own syntax tables. Its first argument is the
12707: character to change. The second argument is a string that specifies the
12708: new syntax. When called from Lisp code, there is a third, optional
12709: argument, which specifies the syntax table in which to make the change. If
12710: not supplied, or if this command is called interactively, the third
12711: argument defaults to the current buffer's syntax table.
12712:
12713: @enumerate
12714: @item
12715: The first character in the string specifies the syntactic class. It
12716: is one of the characters in the previous table (@pxref{Syntax Entry}).
12717:
12718: @item
12719: The second character is the matching delimiter. For a character that
12720: is not an opening or closing delimiter, this should be a space, and may
12721: be omitted if no following characters are needed.
12722:
12723: @item
12724: The remaining characters are flags. The flag characters allowed are
12725:
12726: @table @samp
12727: @item 1
12728: Flag this character as the first of a two-character comment starting sequence.
12729: @item 2
12730: Flag this character as the second of a two-character comment starting sequence.
12731: @item 3
12732: Flag this character as the first of a two-character comment ending sequence.
12733: @item 4
12734: Flag this character as the second of a two-character comment ending sequence.
12735: @end table
12736: @end enumerate
12737:
12738: @kindex C-h s
12739: @findex describe-syntax
12740: A description of the contents of the current syntax table can be
12741: displayed with @kbd{C-h s} (@code{describe-syntax}). The description of
12742: each character includes both the string you would have to give to
12743: @code{modify-syntax-entry} to set up that character's current syntax, and
12744: some English to explain that string if necessary.
12745:
12746: @node Init File,, Syntax, Customization
12747: @section The Init File, .emacs
12748: @cindex init file
12749: @cindex Emacs initialization file
12750: @cindex key rebinding, permanent
12751: @cindex rebinding keys, permanently
12752:
12753: When Emacs is started, it normally loads the file @file{.emacs} in your
12754: home directory. This file, if it exists, should contain Lisp code. It is
12755: called your @dfn{init file}. The command line switches @samp{-q} and
12756: @samp{-u} can be used to tell Emacs whether to load an init file
12757: (@pxref{Entering Emacs}).
12758:
12759: There can also be a @dfn{default init file}, which is the library named
12760: @file{default.el}, found via the standard search path for libraries. The
12761: Emacs distribution contains no such library; your site may create one for
12762: local customizations. If this library exists, it is loaded whenever you
12763: start Emacs. But your init file, if any, is loaded first; if it sets
12764: @code{inhibit-default-init} non-@code{nil}, then @file{default} is not
12765: loaded.
12766:
12767: If you have a large amount of code in your @file{.emacs} file, you
12768: should move it into another file named @file{@var{something}.el},
12769: byte-compile it (@pxref{Lisp Libraries}), and make your @file{.emacs}
12770: file load the other file using @code{load}.
12771:
12772: @menu
12773: * Init Syntax:: Syntax of constants in Emacs Lisp.
12774: * Init Examples:: How to do some things with an init file.
12775: * Terminal Init:: Each terminal type can have an init file.
12776: @end menu
12777:
12778: @node Init Syntax, Init Examples, Init File, Init File
12779: @subsection Init File Syntax
12780:
12781: The @file{.emacs} file contains one or more Lisp function call
12782: expressions. Each of these consists of a function name followed by
12783: arguments, all surrounded by parentheses. For example, @code{(setq
12784: fill-column 60)} represents a call to the function @code{setq} which is
12785: used to set the variable @code{fill-column} (@pxref{Filling}) to 60.
12786:
12787: The second argument to @code{setq} is an expression for the new value of
12788: the variable. This can be a constant, a variable, or a function call
12789: expression. In @file{.emacs}, constants are used most of the time. They can be:
12790:
12791: @table @asis
12792: @item Numbers:
12793: Numbers are written in decimal, with an optional initial minus sign.
12794:
12795: @item Strings:
12796: Lisp string syntax is the same as C string syntax with a few extra
12797: features. Use a double-quote character to begin and end a string constant.
12798:
12799: Newlines and special characters may be present literally in strings. They
12800: can also be represented as backslash sequences: @samp{\n} for newline,
12801: @samp{\b} for backspace, @samp{\r} for carriage return, @samp{\t} for tab,
12802: @samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a
12803: backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the
12804: character whose octal code is @var{ooo}. Backslash and double-quote are
12805: the only characters for which backslash sequences are mandatory.
12806:
12807: @samp{\C-} can be used as a prefix for a control character, as in
12808: @samp{\C-s} for ASCII Control-S, and @samp{\M-} can be used as a prefix for
12809: a meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for
12810: Control-Meta-A.@refill
12811:
12812: @item Characters:
12813: Lisp character constant syntax consists of a @samp{?} followed by
12814: either a character or an escape sequence starting with @samp{\}.
12815: Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
12816: strings and characters are not interchangeable in Lisp; some contexts
12817: require one and some contexts require the other.
12818:
12819: @item True:
12820: @code{t} stands for `true'.
12821:
12822: @item False:
12823: @code{nil} stands for `false'.
12824:
12825: @item Other Lisp objects:
12826: Write a single-quote (') followed by the Lisp object you want.
12827: @end table
12828:
12829: @node Init Examples, Terminal Init, Init Syntax, Init File
12830: @subsection Init File Examples
12831:
12832: Here are some examples of doing certain commonly desired things with
12833: Lisp expressions:
12834:
12835: @itemize @bullet
12836: @item
12837: Make @key{TAB} in C mode just insert a tab if point is in the middle of a
12838: line.
12839:
12840: @example
12841: (setq c-tab-always-indent nil)
12842: @end example
12843:
12844: Here we have a variable whose value is normally @code{t} for `true'
12845: and the alternative is @code{nil} for `false'.
12846:
12847: @item
12848: Make searches case sensitive by default (in all buffers that do not
12849: override this).
12850:
12851: @example
12852: (setq-default case-fold-search nil)
12853: @end example
12854:
12855: This sets the default value, which is effective in all buffers that do
12856: not have local values for the variable. Setting @code{case-fold-search}
12857: with @code{setq} affects only the current buffer's local value, which
12858: is not what you probably want to do in an init file.
12859:
12860: @item
12861: Make Text mode the default mode for new buffers.
12862:
12863: @example
12864: (setq default-major-mode 'text-mode)
12865: @end example
12866:
12867: Note that @code{text-mode} is used because it is the command for entering
12868: the mode we want. A single-quote is written before it to make a symbol
12869: constant; otherwise, @code{text-mode} would be treated as a variable name.
12870:
12871: @item
12872: Turn on Auto Fill mode automatically in Text mode and related modes.
12873:
12874: @example
12875: (setq text-mode-hook
12876: '(lambda () (auto-fill-mode 1)))
12877: @end example
12878:
12879: Here we have a variable whose value should be a Lisp function. The
12880: function we supply is a list starting with @code{lambda}, and a single
12881: quote is written in front of it to make it (for the purpose of this
12882: @code{setq}) a list constant rather than an expression. Lisp functions
12883: are not explained here, but for mode hooks it is enough to know that
12884: @code{(auto-fill-mode 1)} is an expression that will be executed when
12885: Text mode is entered, and you could replace it with any other expression
12886: that you like, or with several expressions in a row.
12887:
12888: @example
12889: (setq text-mode-hook 'turn-on-auto-fill)
12890: @end example
12891:
12892: This is another way to accomplish the same result.
12893: @code{turn-on-auto-fill} is a symbol whose function definition is
12894: @code{(lambda () (auto-fill-mode 1))}.
12895:
12896: @item
12897: Load the installed Lisp library named @file{foo} (actually a file
12898: @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
12899:
12900: @example
12901: (load "foo")
12902: @end example
12903:
12904: When the argument to @code{load} is a relative pathname, not starting
12905: with @samp{/} or @samp{~}, @code{load} searches the directories in
12906: @code{load-path} (@pxref{Loading}).
12907:
12908: @item
12909: Load the compiled Lisp file @file{foo.elc} from your home directory.
12910:
12911: @example
12912: (load "~/foo.elc")
12913: @end example
12914:
12915: Here an absolute file name is used, so no searching is done.
12916:
12917: @item
12918: Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
12919:
12920: @example
12921: (global-set-key "\C-xl" 'make-symbolic-link)
12922: @end example
12923:
12924: or
12925:
12926: @example
12927: (define-key global-map "\C-xl" 'make-symbolic-link)
12928: @end example
12929:
12930: Note once again the single-quote used to refer to the symbol
12931: @code{make-symbolic-link} instead of its value as a variable.
12932:
12933: @item
12934: Do the same thing for C mode only.
12935:
12936: @example
12937: (define-key c-mode-map "\C-xl" 'make-symbolic-link)
12938: @end example
12939:
12940: @item
12941: Redefine all keys which now run @code{next-line} in Fundamental mode
12942: so that they run @code{forward-line} instead.
12943:
12944: @example
12945: (substitute-key-definition 'next-line 'forward-line
12946: global-map)
12947: @end example
12948:
12949: @item
12950: Make @kbd{C-x C-v} undefined.
12951:
12952: @example
12953: (global-unset-key "\C-x\C-v")
12954: @end example
12955:
12956: One reason to undefine a key is so that you can make it a prefix.
12957: Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v}
12958: a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition
12959: first.
12960:
12961: @item
12962: Make @samp{$} have the syntax of punctuation in Text mode.
12963: Note the use of a character constant for @samp{$}.
12964:
12965: @example
12966: (modify-syntax-entry ?\$ "." text-mode-syntax-table)
12967: @end example
12968:
12969: @item
12970: Enable the use of the command @code{eval-expression} without confirmation.
12971:
12972: @example
12973: (put 'eval-expression 'disabled nil)
12974: @end example
12975: @end itemize
12976:
12977: @node Terminal Init,, Init Examples, Init File
12978: @subsection Terminal-specific Initialization
12979:
12980: Each terminal type can have a Lisp library to be loaded into Emacs when
12981: it is run on that type of terminal. For a terminal type named
12982: @var{termtype}, the library is called @file{term/@var{termtype}} and it is
12983: found by searching the directories @code{load-path} as usual and trying the
12984: suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
12985: subdirectory @file{term} of the directory where most Emacs libraries are
12986: kept.@refill
12987:
12988: The usual purpose of the terminal-specific library is to define the
12989: escape sequences used by the terminal's function keys using the library
12990: @file{keypad.el}. See the file
12991: @file{term/vt100.el} for an example of how this is done.@refill
12992:
12993: When the terminal type contains a hyphen, only the part of the name
12994: before the first hyphen is significant in choosing the library name.
12995: Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
12996: the library @file{term/aaa}. The code in the library can use
12997: @code{(getenv "TERM")} to find the full terminal type name.@refill
12998:
12999: @vindex term-file-prefix
13000: The library's name is constructed by concatenating the value of the
13001: variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
13002: file can prevent the loading of the terminal-specific library by setting
13003: @code{term-file-prefix} to @code{nil}.
13004:
13005: @vindex term-setup-hook
13006: The value of the variable @code{term-setup-hook}, if not @code{nil}, is
13007: called as a function of no arguments at the end of Emacs initialization,
13008: after both your @file{.emacs} file and any terminal-specific library have
13009: been read in. You can set the value in the @file{.emacs} file to override
13010: part of any of the terminal-specific libraries and to define
13011: initializations for terminals that do not have a library.@refill
13012:
13013: @iftex
13014: @chapter Correcting Mistakes (Yours or Emacs's)
13015:
13016: If you type an Emacs command you did not intend, the results are often
13017: mysterious. This chapter tells what you can do to cancel your mistake or
13018: recover from a mysterious situation. Emacs bugs and system crashes are
13019: also considered.
13020: @end iftex
13021:
13022: @node Quitting, Lossage, Customization, Top
13023: @section Quitting and Aborting
13024: @cindex quitting
13025:
13026: @table @kbd
13027: @item C-g
13028: Quit. Cancel running or partially typed command.
13029: @item C-]
13030: Abort innermost recursive editing level and cancel the command which
13031: invoked it (@code{abort-recursive-edit}).
13032: @item M-x top-level
13033: Abort all recursive editing levels that are currently executing.
13034: @item C-x u
13035: Cancel an already-executed command, usually (@code{undo}).
13036: @end table
13037:
13038: There are two ways of cancelling commands which are not finished
13039: executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]}
13040: or @kbd{M-x top-level}. Quitting is cancelling a partially typed command
13041: or one which is already running. Aborting is getting out of a recursive
13042: editing level and cancelling the command that invoked the recursive edit.
13043:
13044: @cindex quitting
13045: @cindex C-g
13046: Quitting with @kbd{C-g} is used for getting rid of a partially typed
13047: command, or a numeric argument that you don't want. It also stops a
13048: running command in the middle in a relatively safe way, so you can use it
13049: if you accidentally give a command which takes a long time. In particular,
13050: it is safe to quit out of killing; either your text will @var{all} still be
13051: there, or it will @var{all} be in the kill ring (or maybe both). Quitting
13052: an incremental search does special things documented under searching; in
13053: general, it may take two successive @kbd{C-g} characters to get out of a
13054: search. @kbd{C-g} works by setting the variable @code{quit-flag} to
13055: @code{t} the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
13056: frequently and quits if it is non-@code{nil}. @kbd{C-g} is only actually
13057: executed as a command if it is typed while Emacs is waiting for input.
13058:
13059: If you quit twice in a row before the first @kbd{C-g} is recognized, you
13060: activate the ``emergency escape'' feature and return to the shell.
13061: @xref{Emergency Escape}.
13062:
13063: @cindex recursive editing level
13064: @cindex editing level, recursive
13065: @cindex aborting
13066: @findex abort-recursive-edit
13067: @kindex C-]
13068: Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get out
13069: of a recursive editing level and cancel the command which invoked it.
13070: Quitting with @kbd{C-g} does not do this, and could not do this, because it
13071: is used to cancel a partially typed command @i{within} the recursive
13072: editing level. Both operations are useful. For example, if you are in the
13073: Emacs debugger (@pxref{Lisp Debug}) and have typed @kbd{C-u 8} to enter a
13074: numeric argument, you can cancel that argument with @kbd{C-g} and remain in
13075: the debugger.
13076:
13077: @findex top-level
13078: The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
13079: commands to get you out of all the levels of recursive edits that you are
13080: in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level}
13081: goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} are
13082: like all other commands, and unlike @kbd{C-g}, in that they are effective
13083: only when Emacs is ready for a command. @kbd{C-]} is an ordinary key and
13084: has its meaning only because of its binding in the keymap.
13085: @xref{Recursive Edit}.
13086:
13087: @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelling a
13088: command, but you can think of it as cancelling a command already finished
13089: executing. @xref{Undo}.
13090:
13091: @node Lossage, Bugs, Quitting, Top
13092: @section Dealing with Emacs Trouble
13093:
13094: This section describes various conditions in which Emacs fails to work,
13095: and how to recognize them and correct them.
13096:
13097: @menu
13098: * Stuck Recursive:: `[...]' in mode line around the parentheses
13099: * Screen Garbled:: Garbage on the screen
13100: * Text Garbled:: Garbage in the text
13101: * Unasked-for Search:: Spontaneous entry to incremental search
13102: * Emergency Escape:: Emergency escape---
13103: What to do if Emacs stops responding
13104: * Total Frustration:: When you are at your wits' end.
13105: @end menu
13106:
13107: @node Stuck Recursive, Screen Garbled, Lossage, Lossage
13108: @subsection Recursive Editing Levels
13109:
13110: Recursive editing levels are important and useful features of Emacs, but
13111: they can seem like malfunctions to the user who does not understand them.
13112:
13113: If the mode line has square brackets @samp{[@dots{}]} around the parentheses
13114: that contain the names of the major and minor modes, you have entered a
13115: recursive editing level. If you did not do this on purpose, or if you
13116: don't understand what that means, you should just get out of the recursive
13117: editing level. To do so, type @kbd{M-x top-level}. This is called getting
13118: back to top level. @xref{Recursive Edit}.
13119:
13120: @node Screen Garbled, Text Garbled, Stuck Recursive, Lossage
13121: @subsection Garbage on the Screen
13122:
13123: If the data on the screen looks wrong, the first thing to do is see
13124: whether the text is really wrong. Type @kbd{C-l}, to redisplay the entire
13125: screen. If it appears correct after this, the problem was entirely in the
13126: previous screen update.
13127:
13128: Display updating problems often result from an incorrect termcap entry
13129: for the terminal you are using. The file @file{etc/TERMS} in the Emacs
13130: distribution gives the fixes for known problems of this sort.
13131: @file{INSTALL} contains general advice for these problems in one of its
13132: sections. Very likely there is simply insufficient padding for certain
13133: display operations. To investigate the possibility that you have this sort
13134: of problem, try Emacs on another terminal made by a different manufacturer.
13135: If problems happen frequently on one kind of terminal but not another kind,
13136: it is likely to be a bad termcap entry, though it could also be due to a
13137: bug in Emacs that appears for terminals that have or that lack specific
13138: features.
13139:
13140: @node Text Garbled, Unasked-for Search, Screen Garbled, Lossage
13141: @subsection Garbage in the Text
13142:
13143: If @kbd{C-l} shows that the text is wrong, try undoing the changes to it
13144: using @kbd{C-x u} until it gets back to a state you consider correct. Also
13145: try @kbd{C-h l} to find out what command you typed to produce the observed
13146: results.
13147:
13148: If a large portion of text appears to be missing at the beginning or
13149: end of the buffer, check for the word @samp{Narrow} in the mode line.
13150: If it appears, the text is still present, but marked off-limits.
13151: To make it visible again, type @kbd{C-x w}. @xref{Narrowing}.
13152:
13153: @node Unasked-for Search, Emergency Escape, Text Garbled, Lossage
13154: @subsection Spontaneous Entry to Incremental Search
13155:
13156: If Emacs spontaneously displays @samp{I-search:} at the bottom of the
13157: screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q}
13158: according to the poorly designed xon/xoff ``flow control'' protocol. You
13159: should try to prevent this by putting the terminal in a mode where it will
13160: not use flow control or giving it enough padding that it will never send a
13161: @kbd{C-s}. If that cannot be done, you must tell Emacs to expect flow
13162: control to be used, until you can get a properly designed terminal.
13163:
13164: Information on how to do these things can be found in the file
13165: @file{INSTALL} in the Emacs distribution.
13166:
13167: @node Emergency Escape, Total Frustration, Unasked-for Search, Lossage
13168: @subsection Emergency Escape
13169:
13170: Because at times there have been bugs causing Emacs to loop without
13171: checking @code{quit-flag}, a special feature causes Emacs to be suspended
13172: immediately if you type a second @kbd{C-g} while the flag is already set,
13173: so you can always get out of GNU Emacs. Normally Emacs recognizes and
13174: clears @code{quit-flag} (and quits!) quickly enough to prevent this from
13175: happening.
13176:
13177: When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it
13178: asks two questions before going back to what it had been doing:
13179:
13180: @example
13181: Auto-save? (y or n)
13182: Abort (and dump core)? (y or n)
13183: @end example
13184:
13185: @noindent
13186: Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.
13187:
13188: Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all
13189: modified buffers in which auto-saving is enabled.
13190:
13191: Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be
13192: executed, dumping core. This is to enable a wizard to figure out why Emacs
13193: was failing to quit in the first place. Execution does not continue
13194: after a core dump. If you answer @kbd{n}, execution does continue. With
13195: luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally.
13196: If not, and you type another @kbd{C-g}, it is suspended again.
13197:
13198: If Emacs is not really hung, just slow, you may invoke the double
13199: @kbd{C-g} feature without really meaning to. Then just resume and answer
13200: @kbd{n} to both questions, and you will arrive at your former state.
13201: Presumably the quit you requested will happen soon.
13202:
13203: The double-@kbd{C-g} feature may be turned off when Emacs is running under
13204: a window system, since the window system always enables you to kill Emacs
13205: or to create another window and run another program.
13206:
13207: @node Total Frustration,, Emergency Escape, Lossage
13208: @subsection Help for Total Frustration
13209: @cindex Eliza
13210: @cindex doctor
13211:
13212: If using Emacs (or something else) becomes terribly frustrating and none
13213: of the techniques described above solve the problem, Emacs can still help
13214: you.
13215:
13216: First, if the Emacs you are using is not responding to commands, type
13217: @kbd{C-g C-g} to get out of it and then start a new one.
13218:
13219: @findex doctor
13220: Second, type @kbd{M-x doctor @key{RET}}.
13221:
13222: The doctor will make you feel better. Each time you say something to
13223: the doctor, you must end it by typing @key{RET} @key{RET}. This lets the
13224: doctor know you are finished.
13225:
13226: @node Bugs, Manifesto, Lossage, Top
13227: @section Reporting Bugs
13228:
13229: @cindex bugs
13230: Sometimes you will encounter a bug in Emacs. Although we cannot promise
13231: we can or will fix the bug, and we might not even agree that it is a bug,
13232: we want to hear about bugs you encounter in case we do want to fix them.
13233:
13234: To make it possible for us to fix a bug, you must report it. In order
13235: to do so effectively, you must know when and how to do it.
13236:
13237: @subsection When Is There a Bug
13238:
13239: If Emacs executes an illegal instruction, or dies with an operating
13240: system error message that indicates a problem in the program (as opposed to
13241: something like ``disk full''), then it is certainly a bug.
13242:
13243: If Emacs updates the display in a way that does not correspond to what is
13244: in the buffer, then it is certainly a bug. If a command seems to do the
13245: wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
13246: case of incorrect display updating.
13247:
13248: Taking forever to complete a command can be a bug, but you must make
13249: certain that it was really Emacs's fault. Some commands simply take a long
13250: time. Type @kbd{C-g} and then @kbd{C-h l} to see whether the input Emacs
13251: received was what you intended to type; if the input was such that you
13252: @var{know} it should have been processed quickly, report a bug. If you
13253: don't know whether the command should take a long time, find out by looking
13254: in the manual or by asking for assistance.
13255:
13256: If a command you are familiar with causes an Emacs error message in a
13257: case where its usual definition ought to be reasonable, it is probably a
13258: bug.
13259:
13260: If a command does the wrong thing, that is a bug. But be sure you know
13261: for certain what it ought to have done. If you aren't familiar with the
13262: command, or don't know for certain how the command is supposed to work,
13263: then it might actually be working right. Rather than jumping to
13264: conclusions, show the problem to someone who knows for certain.
13265:
13266: Finally, a command's intended definition may not be best for editing
13267: with. This is a very important sort of problem, but it is also a matter of
13268: judgment. Also, it is easy to come to such a conclusion out of ignorance
13269: of some of the existing features. It is probably best not to complain
13270: about such a problem until you have checked the documentation in the usual
13271: ways, feel confident that you understand it, and know for certain that what
13272: you want is not available. If you are not sure what the command is
13273: supposed to do after a careful reading of the manual, check the index and
13274: glossary for any terms that may be unclear. If you still do not
13275: understand, this indicates a bug in the manual. The manual's job is to
13276: make everything clear. It is just as important to report documentation
13277: bugs as program bugs.
13278:
13279: If the on-line documentation string of a function or variable disagrees
13280: with the manual, one of them must be wrong, so report the bug.
13281:
13282: @subsection How to Report a Bug
13283:
13284: @findex emacs-version
13285: When you decide that there is a bug, it is important to report it and to
13286: report it in a way which is useful. What is most useful is an exact
13287: description of what commands you type, starting with the shell command to
13288: run Emacs, until the problem happens. Always include the version number
13289: of Emacs that you are using; type @kbd{M-x emacs-version} to print this.
13290:
13291: The most important principle in reporting a bug is to report @var{facts},
13292: not hypotheses or categorizations. It is always easier to report the facts,
13293: but people seem to prefer to strain to posit explanations and report
13294: them instead. If the explanations are based on guesses about how Emacs is
13295: implemented, they will be useless; we will have to try to figure out what
13296: the facts must have been to lead to such speculations. Sometimes this is
13297: impossible. But in any case, it is unnecessary work for us.
13298:
13299: For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
13300: @key{RET}}, visiting a file which (you know) happens to be rather large,
13301: and Emacs prints out @samp{I feel pretty today}. The best way to report
13302: the bug is with a sentence like the preceding one, because it gives all the
13303: facts and nothing but the facts.
13304:
13305: Do not assume that the problem is due to the size of the file and say,
13306: ``When I visit a large file, Emacs prints out @samp{I feel pretty today}.''
13307: This is what we mean by ``guessing explanations''. The problem is just as
13308: likely to be due to the fact that there is a @samp{z} in the file name. If
13309: this is so, then when we got your report, we would try out the problem with
13310: some ``large file'', probably with no @samp{z} in its name, and not find
13311: anything wrong. There is no way in the world that we could guess that we
13312: should try visiting a file with a @samp{z} in its name.
13313:
13314: Alternatively, the problem might be due to the fact that the file starts
13315: with exactly 25 spaces. For this reason, you should make sure that you
13316: inform us of the exact contents of any file that is needed to reproduce the
13317: bug. What if the problem only occurs when you have typed the @kbd{C-x C-a}
13318: command previously? This is why we ask you to give the exact sequence of
13319: characters you typed since starting to use Emacs.
13320:
13321: You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
13322: you @i{know} that it makes no difference which visiting command is used.
13323: Similarly, rather than saying ``if I have three characters on the line,''
13324: say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is
13325: the way you entered the text.@refill
13326:
13327: If you are not in Fundamental mode when the problem occurs, you should
13328: say what mode you are in.
13329:
13330: If the manifestation of the bug is an Emacs error message, it is
13331: important to report not just the text of the error message but a backtrace
13332: showing how the Lisp program in Emacs arrived at the error. To make the
13333: backtrace, you must execute the Lisp expression
13334: @code{(setq @w{debug-on-error t})} before the error happens (that is to
13335: say, you must execute that expression and then make the bug happen). This
13336: causes the Lisp debugger to run (@pxref{Lisp Debug}). The debugger's
13337: backtrace can be copied as text into the bug report. This use of the
13338: debugger is possible only if you know how to make the bug happen again. Do
13339: note the error message the first time the bug happens, so if you can't make
13340: it happen again, you can report at least that.
13341:
13342: Check whether any programs you have loaded into the Lisp world, including
13343: your @file{.emacs} file, set any variables that may affect the functioning
13344: of Emacs. Also, see whether the problem happens in a freshly started Emacs
13345: without loading your @file{.emacs} file (start Emacs with the @code{-q} switch
13346: to prevent loading the init file.) If the problem does @var{not} occur
13347: then, it is essential that we know the contents of any programs that you
13348: must load into the Lisp world in order to cause the problem to occur.
13349:
13350: If the problem does depend on an init file or other Lisp programs that
13351: are not part of the standard Emacs system, then you should make sure it is
13352: not a bug in those programs by complaining to their maintainers first.
13353: After they verify that they are using Emacs in a way that is supposed to
13354: work, they should report the bug.
13355:
13356: If you can tell us a way to cause the problem without visiting any files,
13357: please do so. This makes it much easier to debug. If you do need files,
13358: make sure you arrange for us to see their exact contents. For example, it
13359: can often matter whether there are spaces at the ends of lines, or a
13360: newline after the last line in the buffer (nothing ought to care whether
13361: the last line is terminated, but tell that to the bugs).
13362:
13363: @findex open-dribble-file
13364: @cindex dribble file
13365: The easy way to record the input to Emacs precisely is to to write a
13366: dribble file; execute the Lisp expression
13367:
13368: @example
13369: (open-dribble-file "~/dribble")
13370: @end example
13371:
13372: @noindent
13373: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting
13374: Emacs. From then on, all Emacs input will be written in the specified
13375: dribble file until the Emacs process is killed.
13376:
13377: @findex open-termscript
13378: @cindex termscript file
13379: For possible display bugs, it is important to report the terminal type
13380: (the value of environment variable @code{TERM}), the complete termcap entry
13381: for the terminal from @file{/etc/termcap} (since that file is not identical
13382: on all machines), and the output that Emacs actually sent to the terminal.
13383: The way to collect this output is to execute the Lisp expression
13384:
13385: @example
13386: (open-termscript "~/termscript")
13387: @end example
13388:
13389: @noindent
13390: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just
13391: after starting Emacs. From then on, all output from Emacs to the terminal
13392: will be written in the specified termscript file as well, until the Emacs
13393: process is killed. If the problem happens when Emacs starts up, put this
13394: expression into your @file{.emacs} file so that the termscript file will
13395: be open when Emacs displays the screen for the first time. Be warned:
13396: it is often difficult, and sometimes impossible, to fix a terminal-dependent
13397: bug without access to a terminal of the type that stimulates the bug.@refill
13398:
13399: The address for reporting bugs is
13400:
13401: @format
13402: GNU Emacs Bugs
13403: 545 Tech Sq, rm 703
13404: Cambridge, MA 02139
13405: @end format
13406:
13407: @noindent
13408: or send email to @samp{mit-eddie!bug-gnu-emacs} (Usenet) or
13409: @samp{bug-gnu-emacs@@prep.ai.mit.edu} (Internet).
13410:
13411: Once again, we do not promise to fix the bug; but if the bug is serious,
13412: or ugly, or easy to fix, chances are we will want to.
13413:
13414: @iftex
13415: @unnumbered Emacs Version 17 Antinews
13416:
13417: For those of you who are downgrading from version 18 to version 17 of GNU
13418: Emacs, here is a list of the old features. You will note many
13419: simplifications; complicated features have been eliminated. The list does
13420: not include changes affecting only topics not dealt with in this manual.
13421:
13422: @unnumberedsec General Changes
13423:
13424: @itemize @bullet
13425: @item
13426: Vi, EDT and Gosmacs emulation have been eliminated in version 17. The
13427: idea is that other editors are obsolete and nobody should want to
13428: remember they exist.
13429:
13430: @item
13431: The buffer-sorting commands of version 18 have been eliminated in version
13432: 17. @xref{Sorting}.
13433:
13434: @item
13435: The @kbd{M-@key{TAB}} command for completion of Lisp symbol names has
13436: been eliminated.
13437:
13438: @item
13439: The @kbd{M-/} command for dynamic abbrev expansion has been eliminated.
13440:
13441: @item
13442: @kbd{C-M-v} is no longer redefined in the minibuffer. It has its standard
13443: meaning, which is to scroll the ``next'' window. In the minibuffer, the
13444: ``next'' window is always the one at the top of the screen. @xref{Windows}.
13445:
13446: @item
13447: The old command @kbd{M-x occur-menu} is now the way to ask for a list
13448: of matches for a regexp and then pick one and move point to it. Refer
13449: to its on-line documentation for full details of its use. @kbd{M-x
13450: occur} has been simplified and now just displays a list of matches
13451: with no fancy options. @xref{Other Repeating Search}.
13452:
13453: @item
13454: Incremental searches both ordinary and regexp now share a single
13455: default search string which is the last thing searched for by either
13456: kind of incremental search. They do not wrap to the beginning or end
13457: of the buffer. @xref{Incremental Search}.
13458:
13459: @item
13460: The variables @code{search-low-speed} and @code{search-slow-window-lines}
13461: have been renamed to start with @code{isearch} instead of @code{search}.
13462:
13463: @item
13464: Undo in version 17 clears the ``modified'' flag more often. If the
13465: buffer contents that result from undoing are the same as at a prior
13466: instant when the ``modified'' flag was clear, the ``modified'' flag
13467: is cleared again. @xref{Undo}.
13468:
13469: @item
13470: @kbd{C-x C-v} is allowed only when the current buffer is visiting a
13471: file. @xref{Visiting}.
13472:
13473: @item
13474: Auto-save file names in version 17 do not have a final @samp{#}. The
13475: auto-save file name for a file @file{foo.c} is therefore @file{#foo.c}.
13476: @xref{Auto Save}.
13477:
13478: @item
13479: @kbd{M-x recover-file} works more simply. It does not compare the dates of
13480: the specified file and its auto-save file; it does not display a directory
13481: listing for them. You must figure out on your own whether you want to
13482: recover the file from its auto-save file.
13483:
13484: @item
13485: Some of the command line switches have been eliminated
13486: (@pxref{Command Switches}). Switches eliminated include
13487: @samp{-insert} and @samp{-i}, and the alternate names @samp{-funcall},
13488: @samp{-load}, @samp{-user} and @samp{-no-init-file}.@refill
13489: @end itemize
13490:
13491: @unnumberedsec Changes in Major Modes
13492:
13493: @itemize @bullet
13494: @item
13495: Fortran mode has been eliminated.
13496:
13497: @item
13498: Nroff mode no longer defines a syntax for comments (@pxref{Nroff Mode}).
13499:
13500: @item
13501: The two kinds of @TeX{} mode have been combined into one; @kbd{M-x tex-mode}
13502: simply turns on this mode instead of choosing among two others. A further
13503: simplification is the elimination of the commands @kbd{C-c C-f},
13504: @kbd{C-c C-k}, @kbd{C-c C-l} and @kbd{C-c C-q}. @xref{TeX Mode}.@refill
13505:
13506: @item
13507: All the special commands of Outline mode have been moved to new keys
13508: or eliminated (@pxref{Outline Mode}).
13509:
13510: @itemize @bullet
13511: @item
13512: @kbd{C-c C-n} becomes @kbd{M-@}}.
13513: @item
13514: @kbd{C-c C-p} becomes @kbd{M-@{}.
13515: @item
13516: @kbd{C-c C-f}, @kbd{C-c C-b} and @kbd{C-c C-u} are eliminated.
13517: @end itemize
13518:
13519: The variable @code{outline-regexp} has also been eliminated in version
13520: 17.
13521:
13522: @item
13523: In C mode, @key{TAB} always reindents the current line. The variable
13524: @code{c-tab-always-indent} has been eliminated and Emacs acts as if
13525: it were @code{t}. @xref{C Indent}.
13526:
13527: @item
13528: Linefeed is now redefined in C mode so that it reindents (with
13529: @key{TAB}) both of the lines that result from breaking the current
13530: line.
13531:
13532: @item
13533: The special commands used in Picture mode to specify the direction of
13534: cursor motion after self-inserting characters have been given new keys
13535: (@pxref{Picture}). They are now
13536:
13537: @itemize @bullet
13538: @item
13539: @kbd{M-`} to request leftward motion.
13540: @item
13541: @kbd{M-'} to request rightward motion.
13542: @item
13543: @kbd{M--} to request upward motion.
13544: @item
13545: @kbd{M-=} to request downward motion.
13546: @item
13547: @kbd{C-c `} to request upward and leftward motion.
13548: @item
13549: @kbd{C-c '} to request upward and rightward motion.
13550: @item
13551: @kbd{C-c /} to request downward and leftward motion.
13552: @item
13553: @kbd{C-c \} to request downward and rightward motion.
13554: @end itemize
13555:
13556: @item
13557: The special @kbd{C-c} commands of Mail mode have been given new keys
13558: (@pxref{Sending Mail}).
13559:
13560: @itemize @bullet
13561: @item
13562: @kbd{C-c C-f C-s} becomes @kbd{C-c s}
13563: @item
13564: @kbd{C-c C-f C-t} becomes @kbd{C-c t}
13565: @item
13566: @kbd{C-c C-f C-b} becomes @kbd{C-c b}
13567: @item
13568: @kbd{C-c C-f C-c} becomes @kbd{C-c c}
13569: @item
13570: @kbd{C-c C-y} becomes @kbd{C-c y}
13571: @item
13572: @kbd{C-c C-q} becomes @kbd{C-c q}
13573: @item
13574: @kbd{C-c C-w} becomes @kbd{C-c w}
13575: @end itemize
13576:
13577: @item
13578: The @kbd{g} command in Dired has been removed (@pxref{Dired}).
13579: @end itemize
13580:
13581: @unnumberedsec Init Files and Library Changes
13582:
13583: @itemize @bullet
13584: @item
13585: The commands @code{load-file} and @code{load-library} are replaced
13586: with one command, @code{load}. This command is logically the same as
13587: version 18 @code{load-library}, but due to changes in the order of
13588: searching it can also serve in place of @code{load-file}.
13589: @xref{Loading}.
13590:
13591: The search order in version 17 is:
13592: @enumerate
13593: @item
13594: Search all the directories in the search path for the file name as given.
13595: @item
13596: Append the suffix @samp{.elc} and search all the directories.
13597: @item
13598: Remove the final @samp{c}, resulting in a suffix @samp{.el}, and search
13599: all the directories.
13600: @end enumerate
13601:
13602: The search path in version 17 normally starts with @code{nil}, meaning
13603: the current default directory.
13604:
13605: As a result, the first file name that @code{load} tries is the one
13606: @code{load-file} would use in version 18: no suffix, and current
13607: default directory.
13608:
13609: @item
13610: The default init file is called @file{default-profile} instead of
13611: @file{default.el} or @file{default.elc}. Also, it is executed
13612: only if you have no init file of your own.
13613:
13614: @item
13615: The terminal-independent keypad support in the @file{keypad} library
13616: has been eliminated. @xref{Terminal Init}.
13617:
13618: @item
13619: The function @code{setq-default} has been eliminated. Use
13620: @code{set-default} and quote the variable name, as in
13621:
13622: @example
13623: (set-default '@var{variable} @var{value})
13624: @end example
13625:
13626: Several built-in variables now are always local to all buffers.
13627:
13628: These variables are @code{tab-width}, @code{ctl-arrow},
13629: @code{truncate-lines}, @code{fill-column}, @code{left-margin},
13630: @code{mode-line-format}, @code{abbrev-mode}, @code{overwrite-mode},
13631: @code{case-fold-search}, @code{auto-fill-hook},
13632: @code{selective-display}.@refill
13633:
13634: @code{set-default} does not work with these variables. They do have
13635: defaults, but the defaults affect only buffers yet to be created. The
13636: only way to set the default for variable @var{foo} is to set the
13637: variable named @code{default-@var{foo}}, such as
13638: @code{default-case-fold-search} and @code{default-fill-column}.@refill
13639:
13640: @item
13641: Some variables have been eliminated. Emacs version 17 always behaves
13642: as if they were @code{nil}.
13643:
13644: @itemize @bullet
13645: @item
13646: @code{backup-by-copying-when-mismatch}
13647: @item
13648: @code{find-file-hooks}
13649: @item
13650: @code{find-file-not-found-hooks}
13651: @item
13652: @code{write-file-hooks}
13653: @item
13654: @code{file-precious-flag}
13655: @item
13656: @code{no-redraw-on-reenter}
13657: @end itemize
13658: @end itemize
13659:
13660: @end iftex
13661:
13662: @node Manifesto,, Bugs, Top
13663: @unnumbered The GNU Manifesto
13664:
13665: @unnumberedsec What's GNU? Gnu's Not Unix!
13666:
13667: GNU, which stands for Gnu's Not Unix, is the name for the complete
13668: Unix-compatible software system which I am writing so that I can give it
13669: away free to everyone who can use it. Several other volunteers are helping
13670: me. Contributions of time, money, programs and equipment are greatly
13671: needed.
13672:
13673: So far we have an Emacs text editor with Lisp for writing editor commands,
13674: a source level debugger, a yacc-compatible parser generator, a linker, and
13675: around 35 utilities. A shell (command interpreter) is nearly completed. A
13676: new portable optimizing C compiler has compiled itself and may be released
13677: this year. An initial kernel exists but many more features are needed to
13678: emulate Unix. When the kernel and compiler are finished, it will be
13679: possible to distribute a GNU system suitable for program development. We
13680: will use @TeX{} as our text formatter, but an nroff is being worked on. We
13681: will use the free, portable X window system as well. After this we will
13682: add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of
13683: other things, plus on-line documentation. We hope to supply, eventually,
13684: everything useful that normally comes with a Unix system, and more.
13685:
13686: GNU will be able to run Unix programs, but will not be identical to Unix.
13687: We will make all improvements that are convenient, based on our experience
13688: with other operating systems. In particular, we plan to have longer
13689: filenames, file version numbers, a crashproof file system, filename
13690: completion perhaps, terminal-independent display support, and perhaps
13691: eventually a Lisp-based window system through which several Lisp programs
13692: and ordinary Unix programs can share a screen. Both C and Lisp will be
13693: available as system programming languages. We will try to support UUCP,
13694: MIT Chaosnet, and Internet protocols for communication.
13695:
13696: GNU is aimed initially at machines in the 68000/16000 class with virtual
13697: memory, because they are the easiest machines to make it run on. The extra
13698: effort to make it run on smaller machines will be left to someone who wants
13699: to use it on them.
13700:
13701: To avoid horrible confusion, please pronounce the `G' in the word `GNU'
13702: when it is the name of this project.
13703:
13704: @unnumberedsec Why I Must Write GNU
13705:
13706: I consider that the golden rule requires that if I like a program I must
13707: share it with other people who like it. Software sellers want to divide
13708: the users and conquer them, making each user agree not to share with
13709: others. I refuse to break solidarity with other users in this way. I
13710: cannot in good conscience sign a nondisclosure agreement or a software
13711: license agreement. For years I worked within the Artificial Intelligence
13712: Lab to resist such tendencies and other inhospitalities, but eventually
13713: they had gone too far: I could not remain in an institution where such
13714: things are done for me against my will.
13715:
13716: So that I can continue to use computers without dishonor, I have decided to
13717: put together a sufficient body of free software so that I will be able to
13718: get along without any software that is not free. I have resigned from the
13719: AI lab to deny MIT any legal excuse to prevent me from giving GNU away.
13720:
13721: @unnumberedsec Why GNU Will Be Compatible with Unix
13722:
13723: Unix is not my ideal system, but it is not too bad. The essential features
13724: of Unix seem to be good ones, and I think I can fill in what Unix lacks
13725: without spoiling them. And a system compatible with Unix would be
13726: convenient for many other people to adopt.
13727:
13728: @unnumberedsec How GNU Will Be Available
13729:
13730: GNU is not in the public domain. Everyone will be permitted to modify and
13731: redistribute GNU, but no distributor will be allowed to restrict its
13732: further redistribution. That is to say, proprietary modifications will not
13733: be allowed. I want to make sure that all versions of GNU remain free.
13734:
13735: @unnumberedsec Why Many Other Programmers Want to Help
13736:
13737: I have found many other programmers who are excited about GNU and want to
13738: help.
13739:
13740: Many programmers are unhappy about the commercialization of system
13741: software. It may enable them to make more money, but it requires them to
13742: feel in conflict with other programmers in general rather than feel as
13743: comrades. The fundamental act of friendship among programmers is the
13744: sharing of programs; marketing arrangements now typically used essentially
13745: forbid programmers to treat others as friends. The purchaser of software
13746: must choose between friendship and obeying the law. Naturally, many decide
13747: that friendship is more important. But those who believe in law often do
13748: not feel at ease with either choice. They become cynical and think that
13749: programming is just a way of making money.
13750:
13751: By working on and using GNU rather than proprietary programs, we can be
13752: hospitable to everyone and obey the law. In addition, GNU serves as an
13753: example to inspire and a banner to rally others to join us in sharing.
13754: This can give us a feeling of harmony which is impossible if we use
13755: software that is not free. For about half the programmers I talk to, this
13756: is an important happiness that money cannot replace.
13757:
13758: @unnumberedsec How You Can Contribute
13759:
13760: I am asking computer manufacturers for donations of machines and money.
13761: I'm asking individuals for donations of programs and work.
13762:
13763: One consequence you can expect if you donate machines is that GNU will run
13764: on them at an early date. The machines should be complete, ready to use
13765: systems, approved for use in a residential area, and not in need of
13766: sophisticated cooling or power.
13767:
13768: I have found very many programmers eager to contribute part-time work for
13769: GNU. For most projects, such part-time distributed work would be very hard
13770: to coordinate; the independently-written parts would not work together.
13771: But for the particular task of replacing Unix, this problem is absent. A
13772: complete Unix system contains hundreds of utility programs, each of which
13773: is documented separately. Most interface specifications are fixed by Unix
13774: compatibility. If each contributor can write a compatible replacement for
13775: a single Unix utility, and make it work properly in place of the original
13776: on a Unix system, then these utilities will work right when put together.
13777: Even allowing for Murphy to create a few unexpected problems, assembling
13778: these components will be a feasible task. (The kernel will require closer
13779: communication and will be worked on by a small, tight group.)
13780:
13781: If I get donations of money, I may be able to hire a few people full or
13782: part time. The salary won't be high by programmers' standards, but I'm
13783: looking for people for whom building community spirit is as important as
13784: making money. I view this as a way of enabling dedicated people to devote
13785: their full energies to working on GNU by sparing them the need to make a
13786: living in another way.
13787:
13788: @unnumberedsec Why All Computer Users Will Benefit
13789:
13790: Once GNU is written, everyone will be able to obtain good system software
13791: free, just like air.
13792:
13793: This means much more than just saving everyone the price of a Unix license.
13794: It means that much wasteful duplication of system programming effort will
13795: be avoided. This effort can go instead into advancing the state of the
13796: art.
13797:
13798: Complete system sources will be available to everyone. As a result, a user
13799: who needs changes in the system will always be free to make them himself,
13800: or hire any available programmer or company to make them for him. Users
13801: will no longer be at the mercy of one programmer or company which owns the
13802: sources and is in sole position to make changes.
13803:
13804: Schools will be able to provide a much more educational environment by
13805: encouraging all students to study and improve the system code. Harvard's
13806: computer lab used to have the policy that no program could be installed on
13807: the system if its sources were not on public display, and upheld it by
13808: actually refusing to install certain programs. I was very much inspired by
13809: this.
13810:
13811: Finally, the overhead of considering who owns the system software and what
13812: one is or is not entitled to do with it will be lifted.
13813:
13814: Arrangements to make people pay for using a program, including licensing of
13815: copies, always incur a tremendous cost to society through the cumbersome
13816: mechanisms necessary to figure out how much (that is, which programs) a
13817: person must pay for. And only a police state can force everyone to obey
13818: them. Consider a space station where air must be manufactured at great
13819: cost: charging each breather per liter of air may be fair, but wearing the
13820: metered gas mask all day and all night is intolerable even if everyone can
13821: afford to pay the air bill. And the TV cameras everywhere to see if you
13822: ever take the mask off are outrageous. It's better to support the air
13823: plant with a head tax and chuck the masks.
13824:
13825: Copying all or parts of a program is as natural to a programmer as
13826: breathing, and as productive. It ought to be as free.
13827:
13828: @unnumberedsec Some Easily Rebutted Objections to GNU's Goals
13829:
13830: @quotation
13831: ``Nobody will use it if it is free, because that means they can't rely
13832: on any support.''
13833:
13834: ``You have to charge for the program to pay for providing the
13835: support.''
13836: @end quotation
13837:
13838: If people would rather pay for GNU plus service than get GNU free without
13839: service, a company to provide just service to people who have obtained GNU
13840: free ought to be profitable.
13841:
13842: We must distinguish between support in the form of real programming work
13843: and mere handholding. The former is something one cannot rely on from a
13844: software vendor. If your problem is not shared by enough people, the
13845: vendor will tell you to get lost.
13846:
13847: If your business needs to be able to rely on support, the only way is to
13848: have all the necessary sources and tools. Then you can hire any available
13849: person to fix your problem; you are not at the mercy of any individual.
13850: With Unix, the price of sources puts this out of consideration for most
13851: businesses. With GNU this will be easy. It is still possible for there to
13852: be no available competent person, but this problem cannot be blamed on
13853: distibution arrangements. GNU does not eliminate all the world's problems,
13854: only some of them.
13855:
13856: Meanwhile, the users who know nothing about computers need handholding:
13857: doing things for them which they could easily do themselves but don't know
13858: how.
13859:
13860: Such services could be provided by companies that sell just hand-holding
13861: and repair service. If it is true that users would rather spend money and
13862: get a product with service, they will also be willing to buy the service
13863: having got the product free. The service companies will compete in quality
13864: and price; users will not be tied to any particular one. Meanwhile, those
13865: of us who don't need the service should be able to use the program without
13866: paying for the service.
13867:
13868: @quotation
13869: ``You cannot reach many people without advertising,
13870: and you must charge for the program to support that.''
13871:
13872: ``It's no use advertising a program people can get free.''
13873: @end quotation
13874:
13875: There are various forms of free or very cheap publicity that can be used to
13876: inform numbers of computer users about something like GNU. But it may be
13877: true that one can reach more microcomputer users with advertising. If this
13878: is really so, a business which advertises the service of copying and
13879: mailing GNU for a fee ought to be successful enough to pay for its
13880: advertising and more. This way, only the users who benefit from the
13881: advertising pay for it.
13882:
13883: On the other hand, if many people get GNU from their friends, and such
13884: companies don't succeed, this will show that advertising was not really
13885: necessary to spread GNU. Why is it that free market advocates don't want
13886: to let the free market decide this?
13887:
13888: @quotation
13889: ``My company needs a proprietary operating system
13890: to get a competitive edge.''
13891: @end quotation
13892:
13893: GNU will remove operating system software from the realm of competition.
13894: You will not be able to get an edge in this area, but neither will your
13895: competitors be able to get an edge over you. You and they will compete in
13896: other areas, while benefitting mutually in this one. If your business is
13897: selling an operating system, you will not like GNU, but that's tough on
13898: you. If your business is something else, GNU can save you from being
13899: pushed into the expensive business of selling operating systems.
13900:
13901: I would like to see GNU development supported by gifts from many
13902: manufacturers and users, reducing the cost to each.
13903:
13904: @quotation
13905: ``Don't programmers deserve a reward for their creativity?''
13906: @end quotation
13907:
13908: If anything deserves a reward, it is social contribution. Creativity can
13909: be a social contribution, but only in so far as society is free to use the
13910: results. If programmers deserve to be rewarded for creating innovative
13911: programs, by the same token they deserve to be punished if they restrict
13912: the use of these programs.
13913:
13914: @quotation
13915: ``Shouldn't a programmer be able to ask for a reward for his creativity?''
13916: @end quotation
13917:
13918: There is nothing wrong with wanting pay for work, or seeking to maximize
13919: one's income, as long as one does not use means that are destructive. But
13920: the means customary in the field of software today are based on
13921: destruction.
13922:
13923: Extracting money from users of a program by restricting their use of it is
13924: destructive because the restrictions reduce the amount and the ways that
13925: the program can be used. This reduces the amount of wealth that humanity
13926: derives from the program. When there is a deliberate choice to restrict,
13927: the harmful consequences are deliberate destruction.
13928:
13929: The reason a good citizen does not use such destructive means to become
13930: wealthier is that, if everyone did so, we would all become poorer from the
13931: mutual destructiveness. This is Kantian ethics; or, the Golden Rule.
13932: Since I do not like the consequences that result if everyone hoards
13933: information, I am required to consider it wrong for one to do so.
13934: Specifically, the desire to be rewarded for one's creativity does not
13935: justify depriving the world in general of all or part of that creativity.
13936:
13937: @quotation
13938: ``Won't programmers starve?''
13939: @end quotation
13940:
13941: I could answer that nobody is forced to be a programmer. Most of us cannot
13942: manage to get any money for standing on the street and making faces. But
13943: we are not, as a result, condemned to spend our lives standing on the
13944: street making faces, and starving. We do something else.
13945:
13946: But that is the wrong answer because it accepts the questioner's implicit
13947: assumption: that without ownership of software, programmers cannot possibly
13948: be paid a cent. Supposedly it is all or nothing.
13949:
13950: The real reason programmers will not starve is that it will still be
13951: possible for them to get paid for programming; just not paid as much as
13952: now.
13953:
13954: Restricting copying is not the only basis for business in software. It is
13955: the most common basis because it brings in the most money. If it were
13956: prohibited, or rejected by the customer, software business would move to
13957: other bases of organization which are now used less often. There are
13958: always numerous ways to organize any kind of business.
13959:
13960: Probably programming will not be as lucrative on the new basis as it is
13961: now. But that is not an argument against the change. It is not considered
13962: an injustice that sales clerks make the salaries that they now do. If
13963: programmers made the same, that would not be an injustice either. (In
13964: practice they would still make considerably more than that.)
13965:
13966: @quotation
13967: ``Don't people have a right to control how their creativity is used?''
13968: @end quotation
13969:
13970: ``Control over the use of one's ideas'' really constitutes control over
13971: other people's lives; and it is usually used to make their lives more
13972: difficult.
13973:
13974: People who have studied the issue of intellectual property rights carefully
13975: (such as lawyers) say that there is no intrinsic right to intellectual
13976: property. The kinds of supposed intellectual property rights that the
13977: government recognizes were created by specific acts of legislation for
13978: specific purposes.
13979:
13980: For example, the patent system was established to encourage inventors to
13981: disclose the details of their inventions. Its purpose was to help society
13982: rather than to help inventors. At the time, the life span of 17 years for
13983: a patent was short compared with the rate of advance of the state of the
13984: art. Since patents are an issue only among manufacturers, for whom the
13985: cost and effort of a license agreement are small compared with setting up
13986: production, the patents often do not do much harm. They do not obstruct
13987: most individuals who use patented products.
13988:
13989: The idea of copyright did not exist in ancient times, when authors
13990: frequently copied other authors at length in works of non-fiction. This
13991: practice was useful, and is the only way many authors' works have survived
13992: even in part. The copyright system was created expressly for the purpose
13993: of encouraging authorship. In the domain for which it was
13994: invented---books, which could be copied economically only on a printing
13995: press---it did little harm, and did not obstruct most of the individuals
13996: who read the books.
13997:
13998: All intellectual property rights are just licenses granted by society
13999: because it was thought, rightly or wrongly, that society as a whole would
14000: benefit by granting them. But in any particular situation, we have to ask:
14001: are we really better off granting such license? What kind of act are we
14002: licensing a person to do?
14003:
14004: The case of programs today is very different from that of books a hundred
14005: years ago. The fact that the easiest way to copy a program is from one
14006: neighbor to another, the fact that a program has both source code and
14007: object code which are distinct, and the fact that a program is used rather
14008: than read and enjoyed, combine to create a situation in which a person who
14009: enforces a copyright is harming society as a whole both materially and
14010: spiritually; in which a person should not do so regardless of whether the
14011: law enables him to.
14012:
14013: @quotation
14014: ``Competition makes things get done better.''
14015: @end quotation
14016:
14017: The paradigm of competition is a race: by rewarding the winner, we
14018: encourage everyone to run faster. When capitalism really works this way,
14019: it does a good job; but its defenders are wrong in assuming it always works
14020: this way. If the runners forget why the reward is offered and become
14021: intent on winning, no matter how, they may find other strategies---such as,
14022: attacking other runners. If the runners get into a fist fight, they will
14023: all finish late.
14024:
14025: Proprietary and secret software is the moral equivalent of runners in a
14026: fist fight. Sad to say, the only referee we've got does not seem to
14027: object to fights; he just regulates them (``For every ten yards you run,
14028: you can fire one shot''). He really ought to break them up, and penalize
14029: runners for even trying to fight.
14030:
14031: @quotation
14032: ``Won't everyone stop programming without a monetary incentive?''
14033: @end quotation
14034:
14035: Actually, many people will program with absolutely no monetary incentive.
14036: Programming has an irresistible fascination for some people, usually the
14037: people who are best at it. There is no shortage of professional musicians
14038: who keep at it even though they have no hope of making a living that way.
14039:
14040: But really this question, though commonly asked, is not appropriate to the
14041: situation. Pay for programmers will not disappear, only become less. So
14042: the right question is, will anyone program with a reduced monetary
14043: incentive? My experience shows that they will.
14044:
14045: For more than ten years, many of the world's best programmers worked at the
14046: Artificial Intelligence Lab for far less money than they could have had
14047: anywhere else. They got many kinds of non-monetary rewards: fame and
14048: appreciation, for example. And creativity is also fun, a reward in itself.
14049:
14050: Then most of them left when offered a chance to do the same interesting
14051: work for a lot of money.
14052:
14053: What the facts show is that people will program for reasons other than
14054: riches; but if given a chance to make a lot of money as well, they will
14055: come to expect and demand it. Low-paying organizations do poorly in
14056: competition with high-paying ones, but they do not have to do badly if the
14057: high-paying ones are banned.
14058:
14059: @quotation
14060: ``We need the programmers desperately. If they demand that we
14061: stop helping our neighbors, we have to obey.''
14062: @end quotation
14063:
14064: You're never so desperate that you have to obey this sort of demand.
14065: Remember: millions for defense, but not a cent for tribute!
14066:
14067: @quotation
14068: ``Programmers need to make a living somehow.''
14069: @end quotation
14070:
14071: In the short run, this is true. However, there are plenty of ways that
14072: programmers could make a living without selling the right to use a program.
14073: This way is customary now because it brings programmers and businessmen the
14074: most money, not because it is the only way to make a living. It is easy to
14075: find other ways if you want to find them. Here are a number of examples.
14076:
14077: A manufacturer introducing a new computer will pay for the porting of
14078: operating systems onto the new hardware.
14079:
14080: The sale of teaching, hand-holding and maintenance services could also
14081: employ programmers.
14082:
14083: People with new ideas could distribute programs as freeware, asking for
14084: donations from satisfied users, or selling hand-holding services. I have
14085: met people who are already working this way successfully.
14086:
14087: Users with related needs can form users' groups, and pay dues. A group
14088: would contract with programming companies to write programs that the
14089: group's members would like to use.
14090:
14091: All sorts of development can be funded with a Software Tax:
14092:
14093: @quotation
14094: Suppose everyone who buys a computer has to pay x percent of
14095: the price as a software tax. The government gives this to
14096: an agency like the NSF to spend on software development.
14097:
14098: But if the computer buyer makes a donation to software development
14099: himself, he can take a credit against the tax. He can donate to
14100: the project of his own choosing---often, chosen because he hopes to
14101: use the results when it is done. He can take a credit for any amount
14102: of donation up to the total tax he had to pay.
14103:
14104: The total tax rate could be decided by a vote of the payers of
14105: the tax, weighted according to the amount they will be taxed on.
14106:
14107: The consequences:
14108:
14109: @itemize @bullet
14110: @item
14111: The computer-using community supports software development.
14112: @item
14113: This community decides what level of support is needed.
14114: @item
14115: Users who care which projects their share is spent on
14116: can choose this for themselves.
14117: @end itemize
14118: @end quotation
14119:
14120: In the long run, making programs free is a step toward the post-scarcity
14121: world, where nobody will have to work very hard just to make a living.
14122: People will be free to devote themselves to activities that are fun, such
14123: as programming, after spending the necessary ten hours a week on required
14124: tasks such as legislation, family counseling, robot repair and asteroid
14125: prospecting. There will be no need to be able to make a living from
14126: programming.
14127:
14128: We have already greatly reduced the amount of work that the whole society
14129: must do for its actual productivity, but only a little of this has
14130: translated itself into leisure for workers because much nonproductive
14131: activity is required to accompany productive activity. The main causes of
14132: this are bureaucracy and isometric struggles against competition. Free
14133: software will greatly reduce these drains in the area of software
14134: production. We must do this, in order for technical gains in productivity
14135: to translate into less work for us.
14136:
14137: @node Glossary, Key Index, Intro, Top
14138: @unnumbered Glossary
14139:
14140: @table @asis
14141: @item Abbrev
14142: An abbrev is a text string which expands into a different text string
14143: when present in the buffer. For example, you might define a short
14144: word as an abbrev for a long phrase that you want to insert
14145: frequently. @xref{Abbrevs}.
14146:
14147: @item Aborting
14148: Aborting means getting out of a recursive edit (q.v.@:). The
14149: commands @kbd{C-]} and @kbd{M-x top-level} are used for this.
14150: @xref{Quitting}.
14151:
14152: @item Auto Fill mode
14153: Auto Fill mode is a minor mode in which text that you insert is
14154: automatically broken into lines of fixed width. @xref{Filling}.
14155:
14156: @item Auto Saving
14157: Auto saving is when Emacs automatically stores the contents of an
14158: Emacs buffer in a specially-named file so that the information will
14159: not be lost if the buffer is lost due to a system error or user error.
14160: @xref{Auto Save}.
14161:
14162: @item Backup File
14163: A backup file records the contents that a file had before the current
14164: editing session. Emacs makes backup files automatically to help you
14165: track down or cancel changes you later regret making. @xref{Backup}.
14166:
14167: @item Balance Parentheses
14168: Emacs can balance parentheses manually or automatically. Manual
14169: balancing is done by the commands to move over balanced expressions
14170: (@pxref{Lists}). Automatic balancing is done by blinking the
14171: parenthesis that matches one just inserted (@pxref{Matching,,Matching
14172: Parens}).
14173:
14174: @item Bind
14175: To bind a key is to change its binding (q.v.@:). @xref{Rebinding}.
14176:
14177: @item Binding
14178: A key gets its meaning in Emacs by having a binding which is a
14179: command (q.v.@:), a Lisp function that is run when the key is typed.
14180: @xref{Commands,Binding}. Customization often involves rebinding a
14181: character to a different command function. The bindings of all keys
14182: are recorded in the keymaps (q.v.@:). @xref{Keymaps}.
14183:
14184: @item Blank Lines
14185: Blank lines are lines that contain only whitespace. Emacs has several
14186: commands for operating on the blank lines in the buffer.
14187:
14188: @item Buffer
14189: The buffer is the basic editing unit; one buffer corresponds to one
14190: piece of text being edited. You can have several buffers, but at any
14191: time you are editing only one, the `selected' buffer, though several
14192: can be visible when you are using multiple windows. @xref{Buffers}.
14193:
14194: @item Buffer Selection History
14195: Emacs keeps a buffer selection history which records how recently each
14196: Emacs buffer has been selected. This is used for choosing a buffer to
14197: select. @xref{Buffers}.
14198:
14199: @item C-
14200: @samp{C} in the name of a character is an abbreviation for Control.
14201: @xref{Characters,C-}.
14202:
14203: @item C-M-
14204: @samp{C-M-} in the name of a character is an abbreviation for
14205: Control-Meta. @xref{Characters,C-M-}.
14206:
14207: @item Case Conversion
14208: Case conversion means changing text from upper case to lower case or
14209: vice versa. @xref{Case}, for the commands for case conversion.
14210:
14211: @item Characters
14212: Characters form the contents of an Emacs buffer; also, Emacs commands
14213: are invoked by keys (q.v.@:), which are sequences of one or more
14214: characters. @xref{Characters}.
14215:
14216: @item Command
14217: A command is a Lisp function specially defined to be able to serve as
14218: a key binding in Emacs. When you type a key (q.v.@:), its binding
14219: (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find the
14220: command to run. @xref{Commands}.
14221:
14222: @item Command Name
14223: A command name is the name of a Lisp symbol which is a command
14224: (@pxref{Commands}). You can invoke any command by its name using
14225: @kbd{M-x} (@pxref{M-x}).
14226:
14227: @item Comments
14228: A comment is text in a program which is intended only for humans
14229: reading the program, and is marked specially so that it will be
14230: ignored when the program is loaded or compiled. Emacs offers special
14231: commands for creating, aligning and killing comments.
14232: @xref{Comments}.
14233:
14234: @item Compilation
14235: Compilation is the process of creating an executable program from
14236: source code. Emacs has commands for compiling files of Emacs Lisp
14237: code (@pxref{Lisp Libraries}) and programs in C and other languages
14238: (@pxref{Compilation}).
14239:
14240: @item Complete Key
14241: A complete key is a character or sequence of characters which, when typed
14242: by the user, fully specifies one action to be performed by Emacs. For
14243: example, @kbd{X} and @kbd{Control-f} and @kbd{Control-x m} are keys. Keys
14244: derive their meanings from being bound (q.v.@:) to commands (q.v.@:).
14245: Thus, @kbd{X} is conventionally bound to a command to insert @samp{X} in
14246: the buffer; @kbd{C-x m} is conventionally bound to a command to begin
14247: composing a mail message. @xref{Keys}.
14248:
14249: @item Completion
14250: Completion is what Emacs does when it automatically fills out an
14251: abbreviation for a name into the entire name. Completion is done for
14252: minibuffer (q.v.@:) arguments when the set of possible valid inputs
14253: is known; for example, on command names, buffer names, and
14254: file names. Completion occurs when @key{TAB}, @key{SPC} or @key{RET}
14255: is typed. @xref{Completion}.@refill
14256:
14257: @item Continuation Line
14258: When a line of text is longer than the width of the screen, it
14259: takes up more than one screen line when displayed. We say that the
14260: text line is continued, and all screen lines used for it after the
14261: first are called continuation lines. @xref{Basic,Continuation,Basic
14262: Editing}.
14263:
14264: @item Control-Character
14265: ASCII characters with octal codes 0 through 037, and also code 0177,
14266: do not have graphic images assigned to them. These are the control
14267: characters. Any control character can be typed by holding down the
14268: @key{CTRL} key and typing some other character; some have special keys
14269: on the keyboard. @key{RET}, @key{TAB}, @key{ESC}, @key{LFD} and
14270: @key{DEL} are all control characters. @xref{Characters}.@refill
14271:
14272: @item Copyleft
14273: A copyleft is a notice giving the public legal permission to redistribute
14274: a program or other work of art. Copylefts are used by leftists to enrich
14275: the public just as copyrights are used by rightists to gain power over
14276: the public.
14277:
14278: @item Current Buffer
14279: The current buffer in Emacs is the Emacs buffer on which most editing
14280: commands operate. You can select any Emacs buffer as the current one.
14281: @xref{Buffers}.
14282:
14283: @item Current Line
14284: The line point is on (@pxref{Point}).
14285:
14286: @item Current Paragraph
14287: The paragraph that point is in. If point is between paragraphs, the
14288: current paragraph is the one that follows point. @xref{Paragraphs}.
14289:
14290: @item Current Defun
14291: The defun (q.v.@:) that point is in. If point is between defuns, the
14292: current defun is the one that follows point. @xref{Defuns}.
14293:
14294: @item Cursor
14295: The cursor is the rectangle on the screen which indicates the position
14296: called point (q.v.@:) at which insertion and deletion takes place.
14297: The cursor is on or under the character that follows point. Often
14298: people speak of `the cursor' when, strictly speaking, they mean
14299: `point'. @xref{Basic,Cursor,Basic Editing}.
14300:
14301: @item Customization
14302: Customization is making minor changes in the way Emacs works. It is
14303: often done by setting variables (@pxref{Variables}) or by rebinding
14304: keys (@pxref{Keymaps}).
14305:
14306: @item Default Argument
14307: The default for an argument is the value that will be assumed if you
14308: do not specify one. When the minibuffer is used to read an argument,
14309: the default argument is used if you just type @key{RET}.
14310: @xref{Minibuffer}.
14311:
14312: @item Default Directory
14313: When you specify a file name that does not start with @samp{/} or @samp{~},
14314: it is interpreted relative to the current buffer's default directory.
14315: @xref{Minibuffer File,Default Directory}.
14316:
14317: @item Defun
14318: A defun is a list at the top level of parenthesis or bracket structure
14319: in a program. It is so named because most such lists in Lisp programs
14320: are calls to the Lisp function @code{defun}. @xref{Defuns}.
14321:
14322: @item @key{DEL}
14323: @key{DEL} is a character that runs the command to delete one character of
14324: text. @xref{Basic,DEL,Basic Editing}.
14325:
14326: @item Deletion
14327: Deletion means erasing text without saving it. Emacs deletes text
14328: only when it is expected not to be worth saving (all whitespace, or
14329: only one character). The alternative is killing (q.v.@:).
14330: @xref{Killing,Deletion}.
14331:
14332: @item Deletion of Files
14333: Deleting a file means erasing it from the file system.
14334: @xref{Misc File Ops}.
14335:
14336: @item Deletion of Messages
14337: Deleting a message means flagging it to be eliminated from your mail
14338: file. This can be undone by undeletion until the mail file is expunged.
14339: @xref{Rmail Deletion}.
14340:
14341: @item Deletion of Windows
14342: Deleting a window means eliminating it from the screen. Other windows
14343: expand to use up the space. The deleted window can never come back,
14344: but no actual text is thereby lost. @xref{Windows}.
14345:
14346: @item Directory
14347: Files in the Unix file system are grouped into file directories.
14348: @xref{ListDir,,Directories}.
14349:
14350: @item Dired
14351: Dired is the Emacs facility that displays the contents of a file
14352: directory and allows you to ``edit the directory'', performing
14353: operations on the files in the directory. @xref{Dired}.
14354:
14355: @item Disabled Command
14356: A disabled command is one that you may not run without special
14357: confirmation. The usual reason for disabling a command is that it is
14358: confusing for beginning users. @xref{Disabling}.
14359:
14360: @item Dribble File
14361: A file into which Emacs writes all the characters that the user types
14362: on the keyboard. Dribble files are used to make a record for
14363: debugging Emacs bugs. Emacs does not make a dribble file unless you
14364: tell it to. @xref{Bugs}.
14365:
14366: @item Echo Area
14367: The echo area is the bottom line of the screen, used for echoing the
14368: arguments to commands, for asking questions, and printing brief
14369: messages (including error messages). @xref{Echo Area}.
14370:
14371: @item Echoing
14372: Echoing is acknowledging the receipt of commands by displaying them
14373: (in the echo area). Emacs never echoes single-character keys; longer
14374: keys echo only if you pause while typing them.
14375:
14376: @item Error
14377: An error occurs when an Emacs command cannot execute in the current
14378: circumstances. When an error occurs, execution of the command stops
14379: (unless the command has been programmed to do otherwise) and Emacs
14380: reports the error by printing an error message (q.v.). Type-ahead
14381: is discarded. Then Emacs is ready to read another editing command.
14382:
14383: @item Error Messages
14384: Error messages are single lines of output printed by Emacs when the
14385: user asks for something impossible to do (such as, killing text
14386: forward when point is at the end of the buffer). They appear in the
14387: echo area, accompanied by a beep.
14388:
14389: @item @key{ESC}
14390: @key{ESC} is a character, used to end incremental searches and as a
14391: prefix for typing Meta characters on keyboards lacking a @key{META}
14392: key. Unlike the @key{META} key (which, like the @key{SHIFT} key, is held
14393: down while another character is typed), the @key{ESC} key is pressed
14394: once and applies to the next character typed.
14395:
14396: @item Fill Prefix
14397: The fill prefix is a string that should be expected at the beginning
14398: of each line when filling is done. It is not regarded as part of the
14399: text to be filled. @xref{Filling}.
14400:
14401: @item Filling
14402: Filling text means moving text from line to line so that all the lines
14403: are approximately the same length. @xref{Filling}.
14404:
14405: @item Global
14406: Global means `independent of the current environment; in effect
14407: throughout Emacs'. It is the opposite of local (q.v.@:). Particular
14408: examples of the use of `global' appear below.
14409:
14410: @item Global Abbrev
14411: A global definition of an abbrev (q.v.@:) is effective in all major
14412: modes that do not have local (q.v.@:) definitions for the same abbrev.
14413: @xref{Abbrevs}.
14414:
14415: @item Global Keymap
14416: The global keymap (q.v.@:) contains key bindings that are in effect
14417: except when overridden by local key bindings in a major mode's local
14418: keymap (q.v.@:). @xref{Keymaps}.
14419:
14420: @item Global Substitution
14421: Global substitution means replacing each occurrence of one string by
14422: another string through a large amount of text. @xref{Replace}.
14423:
14424: @item Global Variable
14425: The global value of a variable (q.v.@:) takes effect in all buffers
14426: that do not have their own local (q.v.@:) values for the variable.
14427: @xref{Variables}.
14428:
14429: @item Graphic Character
14430: Graphic characters are those assigned pictorial images rather than
14431: just names. All the non-Meta (q.v.@:) characters except for the
14432: Control (q.v.@:) characters are graphic characters. These include
14433: letters, digits, punctuation, and spaces; they do not include
14434: @key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts
14435: that character (in ordinary editing modes). @xref{Basic,,Basic Editing}.
14436:
14437: @item Grinding
14438: Grinding means adjusting the indentation in a program to fit the
14439: nesting structure. @xref{Indentation,Grinding}.
14440:
14441: @item Hardcopy
14442: Hardcopy means printed output. Emacs has commands for making printed
14443: listings of text in Emacs buffers. @xref{Hardcopy}.
14444:
14445: @item @key{HELP}
14446: You can type @key{HELP} at any time to ask what options you have, or
14447: to ask what any command does. @key{HELP} is really @kbd{Control-h}.
14448: @xref{Help}.
14449:
14450: @item Inbox
14451: An inbox is a file in which mail is delivered by the operating system.
14452: Rmail transfers mail from inboxes to mail files (q.v.) in which the
14453: mail is then stored permanently or until explicitly deleted.
14454: @xref{Rmail Inbox}.
14455:
14456: @item Indentation
14457: Indentation means blank space at the beginning of a line. Most
14458: programming languages have conventions for using indentation to
14459: illuminate the structure of the program, and Emacs has special
14460: features to help you set up the correct indentation.
14461: @xref{Indentation}.
14462:
14463: @item Insertion
14464: Insertion means copying text into the buffer, either from the keyboard
14465: or from some other place in Emacs.
14466:
14467: @item Justification
14468: Justification means adding extra spaces to lines of text to make them
14469: come exactly to a specified width. @xref{Filling,Justification}.
14470:
14471: @item Keyboard Macros
14472: Keyboard macros are a way of defining new Emacs commands from
14473: sequences of existing ones, with no need to write a Lisp program.
14474: @xref{Keyboard Macros}.
14475:
14476: @item Key
14477: A key is a sequence of characters that, when input to Emacs, specify
14478: or begin to specify a single action for Emacs to perform. That is,
14479: the sequence is not more than a single unit. If the key is enough to
14480: specify one action, it is a complete key (q.v.); if it is less than
14481: enough, it is a prefix key (q.v.). @xref{Keys}.
14482:
14483: @item Keymap
14484: The keymap is the data structure that records the bindings (q.v.@:) of
14485: keys to the commands that they run. For example, the keymap binds the
14486: character @kbd{C-n} to the command function @code{next-line}.
14487: @xref{Keymaps}.
14488:
14489: @item Kill Ring
14490: The kill ring is where all text you have killed recently is saved.
14491: You can reinsert any of the killed text still in the ring; this is
14492: called yanking (q.v.@:). @xref{Yanking}.
14493:
14494: @item Killing
14495: Killing means erasing text and saving it on the kill ring so it can be
14496: yanked (q.v.@:) later. Some other systems call this ``cutting''.
14497: Most Emacs commands to erase text do killing, as opposed to deletion
14498: (q.v.@:). @xref{Killing}.
14499:
14500: @item Killing Jobs
14501: Killing a job (such as, an invocation of Emacs) means making it cease
14502: to exist. Any data within it, if not saved in a file, is lost.
14503: @xref{Exiting}.
14504:
14505: @item List
14506: A list is, approximately, a text string beginning with an open
14507: parenthesis and ending with the matching close parenthesis. In C mode
14508: and other non-Lisp modes, groupings surrounded by other kinds of matched
14509: delimiters appropriate to the language, such as braces, are also
14510: considered lists. Emacs has special commands for many operations on
14511: lists. @xref{Lists}.
14512:
14513: @item Local
14514: Local means `in effect only in a particular context'; the relevant
14515: kind of context is a particular function execution, a particular
14516: buffer, or a particular major mode. It is the opposite of `global'
14517: (q.v.@:). Specific uses of `local' in Emacs terminology appear below.
14518:
14519: @item Local Abbrev
14520: A local abbrev definition is effective only if a particular major mode
14521: is selected. In that major mode, it overrides any global definition
14522: for the same abbrev. @xref{Abbrevs}.
14523:
14524: @item Local Keymap
14525: A local keymap is used in a particular major mode; the key bindings
14526: (q.v.@:) in the current local keymap override global bindings of the
14527: same keys. @xref{Keymaps}.
14528:
14529: @item Local Variable
14530: A local value of a variable (q.v.@:) applies to only one buffer.
14531: @xref{Locals}.
14532:
14533: @item M-
14534: @kbd{M-} in the name of a character is an abbreviation for @key{META},
14535: one of the modifier keys that can accompany any character.
14536: @xref{Characters}.
14537:
14538: @item M-C-
14539: @samp{M-C-} in the name of a character is an abbreviation for
14540: Control-Meta; it means the same thing as @samp{C-M-}. If your
14541: terminal lacks a real @key{META} key, you type a Control-Meta character by
14542: typing @key{ESC} and then typing the corresponding Control character.
14543: @xref{Characters,C-M-}.
14544:
14545: @item M-x
14546: @kbd{M-x} is the key which is used to call an Emacs command by name.
14547: This is how commands that are not bound to keys are called.
14548: @xref{M-x}.
14549:
14550: @item Mail
14551: Mail means messages sent from one user to another through the computer
14552: system, to be read at the recipient's convenience. Emacs has commands for
14553: composing and sending mail, and for reading and editing the mail you have
14554: received. @xref{Sending Mail}. @xref{Rmail}, for how to read mail.
14555:
14556: @item Mail File
14557: A mail file is a file which is edited using Rmail and in which Rmail
14558: stores mail. @xref{Rmail}.
14559:
14560: @item Major Mode
14561: The major modes are a mutually exclusive set of options each of which
14562: configures Emacs for editing a certain sort of text. Ideally, each
14563: programming language has its own major mode. @xref{Major Modes}.
14564:
14565: @item Mark
14566: The mark points to a position in the text. It specifies one end of
14567: the region (q.v.@:), point being the other end. Many commands operate
14568: on all the text from point to the mark. @xref{Mark}.
14569:
14570: @item Mark Ring
14571: The mark ring is used to hold several recent previous locations of the
14572: mark, just in case you want to move back to them. @xref{Mark Ring}.
14573:
14574: @item Message
14575: See `mail'.
14576:
14577: @item Meta
14578: Meta is the name of a modifier bit which a command character may have.
14579: It is present in a character if the character is typed with the
14580: @key{META} key held down. Such characters are given names that start
14581: with @kbd{Meta-}. For example, @kbd{Meta-<} is typed by holding down
14582: @key{META} and at the same time typing @kbd{<} (which itself is done,
14583: on most terminals, by holding down @key{SHIFT} and typing @kbd{,}).
14584: @xref{Characters,Meta}.
14585:
14586: @item Meta Character
14587: A Meta character is one whose character code includes the Meta bit.
14588:
14589: @item Minibuffer
14590: The minibuffer is the window that appears when necessary inside the
14591: echo area (q.v.@:), used for reading arguments to commands.
14592: @xref{Minibuffer}.
14593:
14594: @item Minor Mode
14595: A minor mode is an optional feature of Emacs which can be switched on
14596: or off independently of all other features. Each minor mode has a
14597: command to turn it on or off. @xref{Minor Modes}.
14598:
14599: @item Mode Line
14600: The mode line is the line at the bottom of each text window (q.v.@:),
14601: which gives status information on the buffer displayed in that window.
14602: @xref{Mode Line}.
14603:
14604: @item Modified Buffer
14605: A buffer (q.v.@:) is modified if its text has been changed since the
14606: last time the buffer was saved (or since when it was created, if it
14607: has never been saved). @xref{Saving}.
14608:
14609: @item Moving Text
14610: Moving text means erasing it from one place and inserting it in
14611: another. This is done by killing (q.v.@:) and then yanking (q.v.@:).
14612: @xref{Killing}.
14613:
14614: @item Named Mark
14615: A named mark is a register (q.v.@:) in its role of recording a
14616: location in text so that you can move point to that location.
14617: @xref{Registers}.
14618:
14619: @item Narrowing
14620: Narrowing means creating a restriction (q.v.@:) that limits editing in
14621: the current buffer to only a part of the text in the buffer. Text
14622: outside that part is inaccessible to the user until the boundaries are
14623: widened again, but it is still there, and saving the file saves it
14624: all. @xref{Narrowing}.
14625:
14626: @item Newline
14627: @key{LFD} characters in the buffer terminate lines of text and are
14628: called newlines. @xref{Characters,Newline}.
14629:
14630: @item Numeric Argument
14631: A numeric argument is a number, specified before a command, to change
14632: the effect of the command. Often the numeric argument serves as a
14633: repeat count. @xref{Arguments}.
14634:
14635: @item Option
14636: An option is a variable (q.v.@:) that exists so that you can customize
14637: Emacs by giving it a new value. @xref{Variables}.
14638:
14639: @item Overwrite Mode
14640: Overwrite mode is a minor mode. When it is enabled, ordinary text
14641: characters replace the existing text after point rather than pushing
14642: it to the right. @xref{Minor Modes}.
14643:
14644: @item Page
14645: A page is a unit of text, delimited by formfeed characters (ASCII
14646: Control-L, code 014) coming at the beginning of a line. Some Emacs
14647: commands are provided for moving over and operating on pages.
14648: @xref{Pages}.
14649:
14650: @item Paragraphs
14651: Paragraphs are the medium-size unit of English text. There are
14652: special Emacs commands for moving over and operating on paragraphs.
14653: @xref{Paragraphs}.
14654:
14655: @item Parsing
14656: We say that Emacs parses words or expressions in the text being
14657: edited. Really, all it knows how to do is find the other end of a
14658: word or expression. @xref{Syntax}.
14659:
14660: @item Point
14661: Point is the place in the buffer at which insertion and deletion
14662: occur. Point is considered to be between two characters, not at one
14663: character. The terminal's cursor (q.v.@:) indicates the location of
14664: point. @xref{Basic,Point}.
14665:
14666: @item Prefix Key
14667: A prefix key is a key (q.v.@:) whose sole function is to introduce a
14668: set of multi-character keys. @kbd{Control-x} is an example of prefix
14669: key; thus, any two-character sequence starting with @kbd{C-x} is also
14670: a legitimate key. @xref{Keys}.
14671:
14672: @item Primary Mail File
14673: Your primary mail file is the file named @samp{RMAIL} in your home
14674: directory, where all mail that you receive is stored by Rmail unless you
14675: make arrangements to do otherwise. @xref{Rmail}.
14676:
14677: @item Prompt
14678: A prompt is text printed to ask the user for input. Printing a prompt
14679: is called prompting. Emacs prompts always appear in the echo area
14680: (q.v.@:). One kind of prompting happens when the minibuffer is used
14681: to read an argument (@pxref{Minibuffer}); the echoing which happens
14682: when you pause in the middle of typing a multicharacter key is also a
14683: kind of prompting (@pxref{Echo Area}).
14684:
14685: @item Quitting
14686: Quitting means cancelling a partially typed command or a running
14687: command, using @kbd{C-g}. @xref{Quitting}.
14688:
14689: @item Quoting
14690: Quoting means depriving a character of its usual special significance.
14691: In Emacs this is usually done with @kbd{Control-q}. What constitutes special
14692: significance depends on the context and on convention. For example,
14693: an ``ordinary'' character as an Emacs command inserts itself; so in
14694: this context, a special character is any character that does not
14695: normally insert itself (such as @key{DEL}, for example), and quoting
14696: it makes it insert itself as if it were not special. Not all contexts
14697: allow quoting. @xref{Basic,Quoting,Basic Editing}.
14698:
14699: @item Read-only Buffer
14700: A read-only buffer is one whose text you are not allowed to change.
14701: Normally Emacs makes buffers read-only when they contain text which
14702: has a special significance to Emacs; for example, Dired buffers.
14703: Visiting a file that is write protected also makes a read-only buffer.
14704: @xref{Buffers}.
14705:
14706: @item Recursive Editing Level
14707: A recursive editing level is a state in which part of the execution of
14708: a command involves asking the user to edit some text. This text may
14709: or may not be the same as the text to which the command was applied.
14710: The mode line indicates recursive editing levels with square brackets
14711: (@samp{[} and @samp{]}). @xref{Recursive Edit}.
14712:
14713: @item Redisplay
14714: Redisplay is the process of correcting the image on the screen to
14715: correspond to changes that have been made in the text being edited.
14716: @xref{Screen,Redisplay}.
14717:
14718: @item Regexp
14719: See `regular expression'.
14720:
14721: @item Region
14722: The region is the text between point (q.v.@:) and the mark (q.v.@:).
14723: Many commands operate on the text of the region. @xref{Mark,Region}.
14724:
14725: @item Registers
14726: Registers are named slots in which text or buffer positions or
14727: rectangles can be saved for later use. @xref{Registers}.
14728:
14729: @item Regular Expression
14730: A regular expression is a pattern that can match various text strings;
14731: for example, @samp{l[0-9]+} matches @samp{l} followed by one or more
14732: digits. @xref{Regexps}.
14733:
14734: @item Replacement
14735: See `global substitution'.
14736:
14737: @item Restriction
14738: A buffer's restriction is the amount of text, at the beginning or the
14739: end of the buffer, that is temporarily invisible and inaccessible.
14740: Giving a buffer a nonzero amount of restriction is called narrowing
14741: (q.v.). @xref{Narrowing}.
14742:
14743: @item @key{RET}
14744: @key{RET} is a character than in Emacs runs the command to insert a
14745: newline into the text. It is also used to terminate most arguments
14746: read in the minibuffer (q.v.@:). @xref{Characters,Return}.
14747:
14748: @item Saving
14749: Saving a buffer means copying its text into the file that was visited
14750: (q.v.@:) in that buffer. This is the way text in files actually gets
14751: changed by your Emacs editing. @xref{Saving}.
14752:
14753: @item Scrolling
14754: Scrolling means shifting the text in the Emacs window so as to see a
14755: different part of the buffer. @xref{Display,Scrolling}.
14756:
14757: @item Searching
14758: Searching means moving point to the next occurrence of a specified
14759: string. @xref{Search}.
14760:
14761: @item Selecting
14762: Selecting a buffer means making it the current (q.v.@:) buffer.
14763: @xref{Buffers,Selecting}.
14764:
14765: @item Self-documentation
14766: Self-documentation is the feature of Emacs which can tell you what any
14767: command does, or give you a list of all commands related to a topic
14768: you specify. You ask for self-documentation with the help character,
14769: @kbd{C-h}. @xref{Help}.
14770:
14771: @item Sentences
14772: Emacs has commands for moving by or killing by sentences.
14773: @xref{Sentences}.
14774:
14775: @item Sexp
14776: A sexp (short for `s-expression') is the basic syntactic unit of Lisp
14777: in its textual form: either a list, or Lisp atom. Many Emacs commands
14778: operate on sexps. The term `sexp' is generalized to languages other
14779: than Lisp, to mean a syntactically recognizable expression.
14780: @xref{Lists,Sexps}.
14781:
14782: @item Simultaneous Editing
14783: Simultaneous editing means two users modifying the same file at once.
14784: Simultaneous editing if not detected can cause one user to lose his
14785: work. Emacs detects all cases of simultaneous editing and warns the
14786: user to investigate them. @xref{Interlocking,,Simultaneous Editing}.
14787:
14788: @item String
14789: A string is a kind of Lisp data object which contains a sequence of
14790: characters. Many Emacs variables are intended to have strings as
14791: values. The Lisp syntax for a string consists of the characters in
14792: the string with a @samp{"} before and another @samp{"} after. A
14793: @samp{"} that is part of the string must be written as @samp{\"} and a
14794: @samp{\} that is part of the string must be written as @samp{\\}. All
14795: other characters, including newline, can be included just by writing
14796: them inside the string; however, escape sequences as in C, such as
14797: @samp{\n} for newline or @samp{\241} using an octal character code,
14798: are allowed as well.
14799:
14800: @item String Substitution
14801: See `global substitution'.
14802:
14803: @item Syntax Table
14804: The syntax table tells Emacs which characters are part of a word,
14805: which characters balance each other like parentheses, etc.
14806: @xref{Syntax}.
14807:
14808: @item Tag Table
14809: A tag table is a file that serves as an index to the function
14810: definitions in one or more other files. @xref{Tags}.
14811:
14812: @item Termscript File
14813: A termscript file contains a record of all characters sent by Emacs to
14814: the terminal. It is used for tracking down bugs in Emacs redisplay.
14815: Emacs does not make a termscript file unless you tell it to.
14816: @xref{Bugs}.
14817:
14818: @item Text
14819: Two meanings (@pxref{Text}):
14820:
14821: @itemize @bullet
14822: @item
14823: Data consisting of a sequence of characters, as opposed to binary
14824: numbers, images, graphics commands, executable programs, and the like.
14825: The contents of an Emacs buffer are always text in this sense.
14826: @item
14827: Data consisting of written human language, as opposed to programs,
14828: or following the stylistic conventions of human language.
14829: @end itemize
14830:
14831: @item Top Level
14832: Top level is the normal state of Emacs, in which you are editing the
14833: text of the file you have visited. You are at top level whenever you
14834: are not in a recursive editing level (q.v.@:) or the minibuffer
14835: (q.v.@:), and not in the middle of a command. You can get back to top
14836: level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}.
14837:
14838: @item Transposition
14839: Transposing two units of text means putting each one into the place
14840: formerly occupied by the other. There are Emacs commands to transpose
14841: two adjacent characters, words, sexps (q.v.@:) or lines
14842: (@pxref{Transpose}).
14843:
14844: @item Truncation
14845: Truncating text lines in the display means leaving out any text on a
14846: line that does not fit within the right margin of the window
14847: displaying it. See also `continuation line'.
14848: @xref{Basic,Truncation,Basic Editing}.
14849:
14850: @item Undoing
14851: Undoing means making your previous editing go in reverse, bringing
14852: back the text that existed earlier in the editing session.
14853: @xref{Undo}.
14854:
14855: @item Variable
14856: A variable is an object in Lisp that can store an arbitrary value.
14857: Emacs uses some variables for internal purposes, and has others (known
14858: as `options' (q.v.@:)) just so that you can set their values to
14859: control the behavior of Emacs. The variables used in Emacs that you
14860: are likely to be interested in are listed in the Variables Index in
14861: this manual. @xref{Variables}, for information on variables.
14862:
14863: @item Visiting
14864: Visiting a file means loading its contents into a buffer (q.v.@:)
14865: where they can be edited. @xref{Visiting}.
14866:
14867: @item Whitespace
14868: Whitespace is any run of consecutive formatting characters (space,
14869: tab, newline, and backspace).
14870:
14871: @item Widening
14872: Widening is removing any restriction (q.v.@:) on the current buffer;
14873: it is the opposite of narrowing (q.v.@:). @xref{Narrowing}.
14874:
14875: @item Window
14876: Emacs divides the screen into one or more windows, each of which can
14877: display the contents of one buffer (q.v.@:) at any time.
14878: @xref{Screen}, for basic information on how Emacs uses the screen.
14879: @xref{Windows}, for commands to control the use of windows.
14880:
14881: @item Word Abbrev
14882: Synonymous with `abbrev'.
14883:
14884: @item Word Search
14885: Word search is searching for a sequence of words, considering the
14886: punctuation between them as insignificant. @xref{Word Search}.
14887:
14888: @item Yanking
14889: Yanking means reinserting text previously killed. It can be used to
14890: undo a mistaken kill, or for copying or moving text. Some other
14891: systems call this ``pasting''. @xref{Yanking}.
14892: @end table
14893:
14894: @node Key Index, Command Index, Glossary, Top
14895: @unnumbered Key (Character) Index
14896: @printindex ky
14897:
14898: @node Command Index, Variable Index, Key Index, Top
14899: @unnumbered Command and Function Index
14900: @printindex fn
14901:
14902: @node Variable Index, Concept Index, Command Index, Top
14903: @unnumbered Variable Index
14904: @printindex vr
14905:
14906: @node Concept Index, Screen, Variable Index, Top
14907: @unnumbered Concept Index
14908: @printindex cp
14909:
14910: @summarycontents
14911: @contents
14912: @bye

unix.superglobalmegacorp.com

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.