GNUtools/emacs/man/emacs.texi - annotate

Return to emacs.texi CVS log

Up to [Apple XNU] / GNUtools / emacs / man

Annotation of GNUtools/emacs/man/emacs.texi, revision 1.1.1.1

1.1 root 1: \input texinfo.tex @c -*-texinfo-*-
2: @c %**start of header
3: @setfilename ../info/emacs
4: @settitle GNU Emacs Manual
5: @setchapternewpage odd
6: @smallbook
7: @c %**end of header
8:
9: @finalout
10:
11: @c
12: @tex
13: %%%% This is special for the Emacs Manual %%%%
14: %%%% Robert J. Chassell 10 June 1992
15:
16: %%%% Use less indentation for Table of Contents
17: \global\tocindent = 1.5pc
18: \global\def\labelspace{\hskip.5em \relax}
19: @end tex
20: @c
21:
22: @ifinfo
23: This file documents the GNU Emacs editor.
24:
25: Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman.
26:
27: Permission is granted to make and distribute verbatim copies of
28: this manual provided the copyright notice and this permission notice
29: are preserved on all copies.
30:
31: @ignore
32: Permission is granted to process this file through Tex and print the
33: results, provided the printed document carries copying permission
34: notice identical to this one except for the removal of this paragraph
35: (this paragraph not being relevant to the printed manual).
36:
37: @end ignore
38: Permission is granted to copy and distribute modified versions of this
39: manual under the conditions for verbatim copying, provided also that the
40: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU
41: General Public License'' are included exactly as in the original, and
42: provided that the entire resulting derived work is distributed under the
43: terms of a permission notice identical to this one.
44:
45: Permission is granted to copy and distribute translations of this manual
46: into another language, under the above conditions for modified versions,
47: except that the sections entitled ``The GNU Manifesto'',
48: ``Distribution'' and ``GNU General Public License'' may be included in a
49: translation approved by the author instead of in the original English.
50: @end ifinfo
51: @c
52: @c
53: @titlepage
54: @sp 6
55: @center @titlefont{GNU Emacs Manual}
56: @sp 4
57: @center Seventh Edition, Emacs Version 18.58
58: @sp 1
59: @center for Unix Users
60: @sp 1
61: @center February 1988, revised September 1992
62: @center (General Public License upgraded, January 1991)
63: @sp 5
64: @center Richard M. Stallman
65: @page
66: @vskip 0pt plus 1filll
67: Copyright @copyright{} 1985, 1986, 1988, 1992 Richard M. Stallman.
68:
69: Permission is granted to make and distribute verbatim copies of
70: this manual provided the copyright notice and this permission notice
71: are preserved on all copies.
72:
73: Permission is granted to copy and distribute modified versions of this
74: manual under the conditions for verbatim copying, provided also that the
75: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU
76: General Public License'' are included exactly as in the original, and
77: provided that the entire resulting derived work is distributed under the
78: terms of a permission notice identical to this one.
79:
80: Permission is granted to copy and distribute translations of this manual
81: into another language, under the above conditions for modified versions,
82: except that the sections entitled ``The GNU Manifesto'',
83: ``Distribution'' and ``GNU General Public License'' may be included in a
84: translation approved by the author instead of in the original English.
85: @sp 2
86: Cover art by Etienne Suvasa.
87: @end titlepage
88: @page
89: @ifinfo
90: @node Top, Distrib,, (DIR)
91: @top The Emacs Editor
92:
93: Emacs is the extensible, customizable, self-documenting real-time
94: display editor. This Info file describes how to edit with Emacs
95: and some of how to customize it, but not how to extend it.
96:
97: @end ifinfo
98: @menu
99: * Distrib:: How to get the latest Emacs distribution.
100: * License:: The GNU General Public License gives you permission
101: to redistribute GNU Emacs on certain terms; and also
102: explains that there is no warranty.
103: * Intro:: An introduction to Emacs concepts.
104: * Glossary:: The glossary.
105: * Version 19:: Changes coming in Emacs version 19, to be released.
106: * Manifesto:: What's GNU? Gnu's Not Unix!
107:
108: Indexes, nodes containing large menus
109: * Key Index:: An item for each standard Emacs key sequence.
110: * Command Index:: An item for each command name.
111: * Variable Index:: An item for each documented variable.
112: * Concept Index:: An item for each concept.
113:
114: Important General Concepts
115: * Screen:: How to interpret what you see on the screen.
116: * Characters:: Emacs's character sets for file contents and for keyboard.
117: * Keys:: Key sequences: what you type to request one editing action.
118: * Commands:: Commands: named functions run by key sequences to do editing.
119: * Entering Emacs:: Starting Emacs from the shell.
120: * Command Switches:: Hairy startup options.
121: * Exiting:: Stopping or killing Emacs.
122: * Basic:: The most basic editing commands.
123: * Undo:: Undoing recently made changes in the text.
124: * Minibuffer:: Entering arguments that are prompted for.
125: * M-x:: Invoking commands by their names.
126: * Help:: Commands for asking Emacs about its commands.
127:
128: Important Text-Changing Commands
129: * Mark:: The mark: how to delimit a ``region'' of text.
130: * Killing:: Killing text.
131: * Yanking:: Recovering killed text. Moving text.
132: * Accumulating Text::
133: Other ways of copying text.
134: * Rectangles:: Operating on the text inside a rectangle on the screen.
135: * Registers:: Saving a text string or a location in the buffer.
136: * Display:: Controlling what text is displayed.
137: * Search:: Finding or replacing occurrences of a string.
138: * Fixit:: Commands especially useful for fixing typos.
139:
140: Larger Units of Text
141: * Files:: All about handling files.
142: * Buffers:: Multiple buffers; editing several files at once.
143: * Windows:: Viewing two pieces of text at once.
144:
145: Advanced Features
146: * Major Modes:: Text mode vs. Lisp mode vs. C mode ...
147: * Indentation:: Editing the white space at the beginnings of lines.
148: * Text:: Commands and modes for editing English.
149: * Programs:: Commands and modes for editing programs.
150: * Compiling/Testing::
151: Compiling, running and debugging programs.
152: * Abbrevs:: How to define text abbreviations to reduce
153: the number of characters you must type.
154: * Picture:: Editing pictures made up of characters
155: using the quarter-plane screen model.
156: * Sending Mail::Sending mail in Emacs.
157: * Rmail:: Reading mail in Emacs.
158: * Recursive Edit::
159: A command can allow you to do editing
160: "within the command". This is called a
161: `recursive editing level'.
162: * Narrowing:: Restricting display and editing to a portion
163: of the buffer.
164: * Sorting:: Sorting lines, paragraphs or pages within Emacs.
165: * Shell:: Executing shell commands from Emacs.
166: * Hardcopy:: Printing buffers or regions.
167: * Dissociated Press:: Dissociating text for fun.
168: * Amusements:: Various games and hacks.
169: * Emulation:: Emulating some other editors with Emacs.
170: * Customization:: Modifying the behavior of Emacs.
171:
172: Recovery from Problems.
173: * Quitting:: Quitting and aborting.
174: * Lossage:: What to do if Emacs is hung or malfunctioning.
175: * Bugs:: How and when to report a bug.
176:
177: Here are some other nodes which are really inferiors of the ones
178: already listed, mentioned here so you can get to them in one step:
179:
180: Subnodes of Screen
181: * Point:: The place in the text where editing commands operate.
182: * Echo Area:: Short messages appear at the bottom of the screen.
183: * Mode Line:: Interpreting the mode line.
184:
185: Subnodes of Basic
186: * Blank Lines:: Commands to make or delete blank lines.
187: * Continuation Lines:: Lines too wide for the screen.
188: * Position Info:: What page, line, row, or column is point on?
189: * Arguments:: Giving numeric arguments to commands.
190:
191: Subnodes of Minibuffer
192: * Minibuffer File:: Entering file names with the minibuffer.
193: * Minibuffer Edit:: How to edit in the minibuffer.
194: * Completion:: An abbreviation facility for minibuffer input.
195: * Repetition:: Re-executing previous commands that used the minibuffer.
196:
197: Subnodes of Mark
198: * Setting Mark:: Commands to set the mark.
199: * Using Region:: Summary of ways to operate on contents of the region.
200: * Marking Objects:: Commands to put region around textual units.
201: * Mark Ring:: Previous mark positions saved so you can go back there.
202:
203: Subnodes of Yanking
204: * Kill Ring:: Where killed text is stored. Basic yanking.
205: * Appending Kills:: Several kills in a row all yank together.
206: * Earlier Kills:: Yanking something killed some time ago.
207:
208: Subnodes of Registers
209: * RegPos:: Saving positions in registers.
210: * RegText:: Saving text in registers.
211: * RegRect:: Saving rectangles in registers.
212:
213: Subnodes of Display
214: * Scrolling:: Moving text up and down in a window.
215: * Horizontal Scrolling:: Moving text left and right in a window.
216: * Selective Display:: Hiding lines with lots of indentation.
217: * Display Vars:: Information on variables for customizing display.
218:
219: Subnodes of Search
220: * Incremental Search:: Search happens as you type the string.
221: * Nonincremental Search:: Specify entire string and then search.
222: * Word Search:: Search for sequence of words.
223: * Regexp Search:: Search for match for a regexp.
224: * Regexps:: Syntax of regular expressions.
225: * Search Case:: To ignore case while searching, or not.
226: * Replace:: Search, and replace some or all matches.
227: * Unconditional Replace:: Everything about replacement except for querying.
228: * Query Replace:: How to use querying.
229: * Other Repeating Search:: Operating on all matches for some regexp.
230:
231: Subnodes of Fixit
232: * Kill Errors:: Commands to kill a batch of recently entered text.
233: * Transpose:: Exchanging two characters, words, lines, lists...
234: * Fixing Case:: Correcting case of last word entered.
235: * Spelling:: Apply spelling checker to a word, or a whole file.
236:
237: Subnodes of Files
238: * File Names:: How to type and edit file name arguments.
239: * Visiting:: Visiting a file prepares Emacs to edit the file.
240: * Saving:: Saving makes your changes permanent.
241: * Backup:: How Emacs saves the old version of your file.
242: * Interlocking::How Emacs protects against simultaneous editing
243: of one file by two users.
244: * Reverting:: Reverting cancels all the changes not saved.
245: * Auto Save:: Auto Save periodically protects against loss of data.
246: * ListDir:: Listing the contents of a file directory.
247: * Dired:: ``Editing'' a directory to delete, rename, etc.
248: the files in it.
249: * Misc File Ops:: Other things you can do on files.
250:
251: Subnodes of Buffers
252: * Select Buffer:: Creating a new buffer or reselecting an old one.
253: * List Buffers:: Getting a list of buffers that exist.
254: * Misc Buffer:: Renaming; changing read-only status.
255: * Kill Buffer:: Killing buffers you no longer need.
256: * Several Buffers:: How to go through the list of all buffers
257: and operate variously on several of them.
258:
259: Subnodes of Windows
260: * Basic Window:: Introduction to Emacs windows.
261: * Split Window:: New windows are made by splitting existing windows.
262: * Other Window:: Moving to another window or doing something to it.
263: * Pop Up Window:: Finding a file or buffer in another window.
264: * Change Window:: Deleting windows and changing their sizes.
265:
266: Subnodes of Indentation
267: * Indentation Commands:: Various commands and techniques for indentation.
268: * Tab Stops:: You can set arbitrary "tab stops" and then
269: indent to the next tab stop when you want to.
270: * Just Spaces:: You can request indentation using just spaces.
271:
272: Subnodes of Text
273: * Text Mode:: The major mode for editing text files.
274: * Nroff Mode:: The major mode for editing input to the formatter nroff.
275: * TeX Mode:: The major mode for editing input to the formatter TeX.
276: * Texinfo Mode::The major mode for editing input to the formatter Texinfo.
277: * Outline Mode::The major mode for editing outlines.
278: * Words:: Moving over and killing words.
279: * Sentences:: Moving over and killing sentences.
280: * Paragraphs:: Moving over paragraphs.
281: * Pages:: Moving over pages.
282: * Filling:: Filling or justifying text
283: * Case:: Changing the case of text
284:
285: Subnodes of Programs
286: * Program Modes:: Major modes for editing programs.
287: * Lists:: Expressions with balanced parentheses.
288: There are editing commands to operate on them.
289: * Defuns:: Each program is made up of separate functions.
290: There are editing commands to operate on them.
291: * Grinding:: Adjusting indentation to show the nesting.
292: * Matching:: Insertion of a close-delimiter flashes matching open.
293: * Comments:: Inserting, killing and aligning comments.
294: * Balanced Editing:: Inserting two matching parentheses at once, etc.
295: * Lisp Completion:: Completion on symbol names in Lisp code.
296: * Documentation:: Getting documentation of functions you plan to call.
297: * Change Log:: Maintaining a change history for your program.
298: * Tags:: Go direct to any function in your program in one
299: command. Tags remembers which file it is in.
300: * Fortran:: Fortran mode and its special features.
301:
302: Subnodes of Compiling/Testing
303: * Compilation:: Compiling programs in languages other than Lisp
304: (C, Pascal, etc.)
305: * Lisp Modes:: Various modes for editing Lisp programs, with
306: different facilities for running the Lisp programs.
307: * Lisp Libraries:: Creating Lisp programs to run in Emacs.
308: * Lisp Interaction:: Executing Lisp in an Emacs buffer.
309: * Lisp Eval:: Executing a single Lisp expression in Emacs.
310: * Lisp Debug:: Debugging Lisp programs running in Emacs.
311: * External Lisp:: Communicating through Emacs with a separate Lisp.
312:
313: Subnodes of Abbrevs
314: * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
315: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
316: * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
317: * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
318: * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
319:
320: Subnodes of Picture
321: * Basic Picture:: Basic concepts and simple commands of Picture mode.
322: * Insert in Picture:: Controlling direction of cursor motion
323: after "self-inserting" characters.
324: * Tabs in Picture:: Various features for tab stops and indentation.
325: * Rectangles in Picture:: Clearing and superimposing rectangles.
326:
327: Subnodes of Sending Mail
328: * Mail Format:: Format of the mail being composed.
329: * Mail Headers:: Details of allowed mail header fields.
330: * Mail Mode:: Special commands for editing mail being composed.
331:
332: Subnodes of Rmail
333: * Rmail Scrolling:: Scrolling through a message.
334: * Rmail Motion:: Moving to another message.
335: * Rmail Deletion:: Deleting and expunging messages.
336: * Rmail Inbox:: How mail gets into the Rmail file.
337: * Rmail Files:: Using multiple Rmail files.
338: * Rmail Output:: Copying message out to files.
339: * Rmail Labels:: Classifying messages by labeling them.
340: * Rmail Summary:: Summaries show brief info on many messages.
341: * Rmail Reply:: Sending replies to messages you are viewing.
342: * Rmail Editing:: Editing message text and headers in Rmail.
343: * Rmail Digest:: Extracting the messages from a digest message.
344:
345: Subnodes of Shell
346: * Single Shell:: Commands to run one shell command and return.
347: * Interactive Shell:: Permanent shell taking input via Emacs.
348: * Shell Mode:: Special Emacs commands used with permanent shell.
349:
350: Subnodes of Customization
351: * Minor Modes:: Each minor mode is one feature you can turn on
352: independently of any others.
353: * Variables:: Many Emacs commands examine Emacs variables
354: to decide what to do; by setting variables,
355: you can control their functioning.
356: * Examining:: Examining or setting one variable's value.
357: * Edit Options:: Examining or editing list of all variables' values.
358: * Locals:: Per-buffer values of variables.
359: * File Variables:: How files can specify variable values.
360: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
361: to be replayed with a single command.
362: * Key Bindings:: The keymaps say what command each key runs.
363: By changing them, you can "redefine keys".
364: * Keymaps:: Definition of the keymap data structure.
365: * Rebinding:: How to redefine one key's meaning conveniently.
366: * Disabling:: Disabling a command means confirmation is required
367: before it can be executed. This is done to protect
368: beginners from surprises.
369: * Syntax:: The syntax table controls how words and expressions
370: are parsed.
371: * Init File:: How to write common customizations in the `.emacs' file.
372:
373: Subnodes of Lossage (and recovery)
374: * Stuck Recursive:: `[...]' in mode line around the parentheses.
375: * Screen Garbled:: Garbage on the screen.
376: * Text Garbled:: Garbage in the text.
377: * Unasked-for Search::Spontaneous entry to incremental search.
378: * Emergency Escape:: Emergency escape---
379: What to do if Emacs stops responding.
380: * Total Frustration:: When you are at your wits' end.
381: @end menu
382:
383: @iftex
384: @unnumbered Preface
385:
386: This manual documents the use and simple customization of the
387: Emacs editor. The reader is not expected to be a programmer. Even simple
388: customizations do not require programming skill, but the user who is not
389: interested in customizing can ignore the scattered customization hints.
390:
391: This is primarily a reference manual, but can also be used as a
392: primer. However, I recommend that the newcomer first use the on-line,
393: learn-by-doing tutorial, which you get by running Emacs and typing
394: @kbd{C-h t}. With it, you learn Emacs by using Emacs on a specially
395: designed file which describes commands, tells you when to try them,
396: and then explains the results you see. This gives a more vivid
397: introduction than a printed manual.
398:
399: On first reading, just skim chapters one and two, which describe the
400: notational conventions of the manual and the general appearance of the
401: Emacs display screen. Note which questions are answered in these chapters,
402: so you can refer back later. After reading chapter four you should
403: practice the commands there. The next few chapters describe fundamental
404: techniques and concepts that are used constantly. You need to understand
405: them thoroughly, experimenting with them if necessary.
406:
407: To find the documentation on a particular command, look in the index.
408: Keys (character commands) and command names have separate indexes. There
409: is also a glossary, with a cross reference for each term.
410:
411: @ignore
412: If you know vaguely what the command
413: does, look in the command summary. The command summary contains a line or
414: two about each command, and a cross reference to the section of the
415: manual that describes the command in more detail; related commands
416: are grouped together.
417: @end ignore
418:
419: This manual comes in two forms: the published form and the Info form.
420: The Info form is for on-line perusal with the @code{info} program; it is
421: distributed along with GNU Emacs. Both forms contain substantially the
422: same text and are generated from a common source file, which is also
423: distributed along with GNU Emacs.
424:
425: GNU Emacs is a member of the Emacs editor family. There are many Emacs
426: editors, all sharing common principles of organization. For information on
427: the underlying philosophy of Emacs and the lessons learned from its
428: development, write for a copy of AI memo 519a, ``Emacs, the Extensible,
429: Customizable Self-Documenting Display Editor'', to Publications Department,
430: Artificial Intelligence Lab, 545 Tech Square, Cambridge, MA 02139, USA. At
431: last report they charge $2.25 per copy. Another useful publication is LCS
432: TM-165, ``A Cookbook for an Emacs'', by Craig Finseth, available from
433: Publications Department, Laboratory for Computer Science, 545 Tech Square,
434: Cambridge, MA 02139, USA. The price today is $3.
435:
436: This edition of the manual is intended for use with GNU Emacs installed on
437: Unix systems. GNU Emacs can also be used on VMS systems, which have
438: different file name syntax and do not support all GNU Emacs features. A
439: VMS edition of this manual may appear in the future.
440: @end iftex
441:
442: @node Distrib, License, Top, Top
443: @unnumbered Distribution
444:
445: GNU Emacs is @dfn{free}; this means that everyone is free to use it and
446: free to redistribute it on a free basis. GNU Emacs is not in the public
447: domain; it is copyrighted and there are restrictions on its
448: distribution, but these restrictions are designed to permit everything
449: that a good cooperating citizen would want to do. What is not allowed
450: is to try to prevent others from further sharing any version of GNU
451: Emacs that they might get from you. The precise conditions are found in
452: the GNU General Public License that comes with Emacs and also appears
453: following this section.
454:
455: The easiest way to get a copy of GNU Emacs is from someone else who has it.
456: You need not ask for permission to do so, or tell any one else; just copy
457: it.
458:
459: If you have access to the Internet, you can get the latest distribution
460: version of GNU Emacs from host @file{prep.ai.mit.edu} using anonymous
461: login. See the file @file{/u2/emacs/GETTING.GNU.SOFTWARE} on that host
462: to find out about your options for copying and which files to use.
463:
464: You may also receive GNU Emacs when you buy a computer. Computer
465: manufacturers are free to distribute copies on the same terms that apply to
466: everyone else. These terms require them to give you the full sources,
467: including whatever changes they may have made, and to permit you to
468: redistribute the GNU Emacs received from them under the usual terms of the
469: General Public License. In other words, the program must be free for you
470: when you get it, not just free for the manufacturer.
471:
472: If you cannot get a copy in any of those ways, you can order one from the
473: Free Software Foundation. Though Emacs itself is free, our distribution
474: service is not. An order form is included at the end of manuals printed by
475: the Foundation. It is also included in the file @file{etc/DISTRIB} in the
476: Emacs distribution. For further information, write to
477:
478: @display
479: Free Software Foundation
480: 675 Mass Ave
481: Cambridge, MA 02139
482: USA
483: @end display
484:
485: The income from distribution fees goes to support the foundation's
486: purpose: the development of more free software to distribute just like
487: GNU Emacs.
488:
489: If you find GNU Emacs useful, please @b{send a donation} to the Free
490: Software Foundation. This will help support development of the rest of the
491: GNU system, and other useful software beyond that. Your donation is tax
492: deductible.
493:
494: @node License, Intro, Distrib, Top
495: @unnumbered GNU GENERAL PUBLIC LICENSE
496: @center Version 1, February 1989
497: @cindex license to copy Emacs
498: @cindex General Public License
499:
500: @display
501: Copyright @copyright{} 1989 Free Software Foundation, Inc.
502: 675 Mass Ave, Cambridge, MA 02139, USA
503:
504: Everyone is permitted to copy and distribute verbatim copies
505: of this license document, but changing it is not allowed.
506: @end display
507:
508: @unnumberedsec Preamble
509:
510: The license agreements of most software companies try to keep users
511: at the mercy of those companies. By contrast, our General Public
512: License is intended to guarantee your freedom to share and change free
513: software---to make sure the software is free for all its users. The
514: General Public License applies to the Free Software Foundation's
515: software and to any other program whose authors commit to using it.
516: You can use it for your programs, too.
517:
518: When we speak of free software, we are referring to freedom, not
519: price. Specifically, the General Public License is designed to make
520: sure that you have the freedom to give away or sell copies of free
521: software, that you receive source code or can get it if you want it,
522: that you can change the software or use pieces of it in new free
523: programs; and that you know you can do these things.
524:
525: To protect your rights, we need to make restrictions that forbid
526: anyone to deny you these rights or to ask you to surrender the rights.
527: These restrictions translate to certain responsibilities for you if you
528: distribute copies of the software, or if you modify it.
529:
530: For example, if you distribute copies of a such a program, whether
531: gratis or for a fee, you must give the recipients all the rights that
532: you have. You must make sure that they, too, receive or can get the
533: source code. And you must tell them their rights.
534:
535: We protect your rights with two steps: (1) copyright the software, and
536: (2) offer you this license which gives you legal permission to copy,
537: distribute and/or modify the software.
538:
539: Also, for each author's protection and ours, we want to make certain
540: that everyone understands that there is no warranty for this free
541: software. If the software is modified by someone else and passed on, we
542: want its recipients to know that what they have is not the original, so
543: that any problems introduced by others will not reflect on the original
544: authors' reputations.
545:
546: The precise terms and conditions for copying, distribution and
547: modification follow.
548:
549: @tex
550: \global\baselineskip 11.5pt
551: @end tex
552:
553: @iftex
554: @unnumberedsec TERMS AND CONDITIONS
555: @end iftex
556: @ifinfo
557: @center TERMS AND CONDITIONS
558: @end ifinfo
559:
560: @enumerate
561: @item
562: This License Agreement applies to any program or other work which
563: contains a notice placed by the copyright holder saying it may be
564: distributed under the terms of this General Public License. The
565: ``Program'', below, refers to any such program or work, and a ``work based
566: on the Program'' means either the Program or any work containing the
567: Program or a portion of it, either verbatim or with modifications. Each
568: licensee is addressed as ``you''.
569:
570: @item
571: @cindex Distribution
572: You may copy and distribute verbatim copies of the Program's source
573: code as you receive it, in any medium, provided that you conspicuously and
574: appropriately publish on each copy an appropriate copyright notice and
575: disclaimer of warranty; keep intact all the notices that refer to this
576: General Public License and to the absence of any warranty; and give any
577: other recipients of the Program a copy of this General Public License
578: along with the Program. You may charge a fee for the physical act of
579: transferring a copy.
580:
581: @item
582: You may modify your copy or copies of the Program or any portion of
583: it, and copy and distribute such modifications under the terms of Paragraph
584: 1 above, provided that you also do the following:
585:
586: @itemize @bullet
587: @item
588: cause the modified files to carry prominent notices stating that
589: you changed the files and the date of any change; and
590:
591: @item
592: cause the whole of any work that you distribute or publish, that
593: in whole or in part contains the Program or any part thereof, either
594: with or without modifications, to be licensed at no charge to all
595: third parties under the terms of this General Public License (except
596: that you may choose to grant warranty protection to some or all
597: third parties, at your option).
598:
599: @item
600: If the modified program normally reads commands interactively when
601: run, you must cause it, when started running for such interactive use
602: in the simplest and most usual way, to print or display an
603: announcement including an appropriate copyright notice and a notice
604: that there is no warranty (or else, saying that you provide a
605: warranty) and that users may redistribute the program under these
606: conditions, and telling the user how to view a copy of this General
607: Public License.
608:
609: @item
610: You may charge a fee for the physical act of transferring a
611: copy, and you may at your option offer warranty protection in
612: exchange for a fee.
613: @end itemize
614:
615: Mere aggregation of another independent work with the Program (or its
616: derivative) on a volume of a storage or distribution medium does not bring
617: the other work under the scope of these terms.
618:
619: @item
620: You may copy and distribute the Program (or a portion or derivative of
621: it, under Paragraph 2) in object code or executable form under the terms of
622: Paragraphs 1 and 2 above provided that you also do one of the following:
623:
624: @itemize @bullet
625: @item
626: accompany it with the complete corresponding machine-readable
627: source code, which must be distributed under the terms of
628: Paragraphs 1 and 2 above; or,
629:
630: @item
631: accompany it with a written offer, valid for at least three
632: years, to give any third party free (except for a nominal charge
633: for the cost of distribution) a complete machine-readable copy of the
634: corresponding source code, to be distributed under the terms of
635: Paragraphs 1 and 2 above; or,
636:
637: @item
638: accompany it with the information you received as to where the
639: corresponding source code may be obtained. (This alternative is
640: allowed only for noncommercial distribution and only if you
641: received the program in object code or executable form alone.)
642: @end itemize
643:
644: Source code for a work means the preferred form of the work for making
645: modifications to it. For an executable file, complete source code means
646: all the source code for all modules it contains; but, as a special
647: exception, it need not include source code for modules which are standard
648: libraries that accompany the operating system on which the executable
649: file runs, or for standard header files or definitions files that
650: accompany that operating system.
651:
652: @item
653: You may not copy, modify, sublicense, distribute or transfer the
654: Program except as expressly provided under this General Public License.
655: Any attempt otherwise to copy, modify, sublicense, distribute or transfer
656: the Program is void, and will automatically terminate your rights to use
657: the Program under this License. However, parties who have received
658: copies, or rights to use copies, from you under this General Public
659: License will not have their licenses terminated so long as such parties
660: remain in full compliance.
661:
662: @item
663: By copying, distributing or modifying the Program (or any work based
664: on the Program) you indicate your acceptance of this license to do so,
665: and all its terms and conditions.
666:
667: @item
668: Each time you redistribute the Program (or any work based on the
669: Program), the recipient automatically receives a license from the original
670: licensor to copy, distribute or modify the Program subject to these
671: terms and conditions. You may not impose any further restrictions on the
672: recipients' exercise of the rights granted herein.
673:
674: @item
675: The Free Software Foundation may publish revised and/or new versions
676: of the General Public License from time to time. Such new versions will
677: be similar in spirit to the present version, but may differ in detail to
678: address new problems or concerns.
679:
680: Each version is given a distinguishing version number. If the Program
681: specifies a version number of the license which applies to it and ``any
682: later version'', you have the option of following the terms and conditions
683: either of that version or of any later version published by the Free
684: Software Foundation. If the Program does not specify a version number of
685: the license, you may choose any version ever published by the Free Software
686: Foundation.
687:
688: @item
689: If you wish to incorporate parts of the Program into other free
690: programs whose distribution conditions are different, write to the author
691: to ask for permission. For software which is copyrighted by the Free
692: Software Foundation, write to the Free Software Foundation; we sometimes
693: make exceptions for this. Our decision will be guided by the two goals
694: of preserving the free status of all derivatives of our free software and
695: of promoting the sharing and reuse of software generally.
696:
697: @iftex
698: @heading NO WARRANTY
699: @end iftex
700: @ifinfo
701: @center NO WARRANTY
702: @end ifinfo
703:
704: @item
705: BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
706: FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
707: OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
708: PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
709: OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
710: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
711: TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
712: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
713: REPAIR OR CORRECTION.
714:
715: @item
716: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
717: ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
718: REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
719: INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
720: ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
721: LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
722: SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
723: WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
724: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
725: @end enumerate
726:
727: @iftex
728: @heading END OF TERMS AND CONDITIONS
729: @end iftex
730: @ifinfo
731: @center END OF TERMS AND CONDITIONS
732: @end ifinfo
733:
734: @tex
735: \global\baselineskip 12pt
736: @end tex
737:
738: @page
739: @unnumberedsec How to Apply These Terms to Your New Programs
740:
741: If you develop a new program, and you want it to be of the greatest
742: possible use to humanity, the best way to achieve this is to make it
743: free software which everyone can redistribute and change under these
744: terms.
745:
746: To do so, attach the following notices to the program. It is safest to
747: attach them to the start of each source file to most effectively convey
748: the exclusion of warranty; and each file should have at least the
749: ``copyright'' line and a pointer to where the full notice is found.
750:
751: @smallexample
752: @var{one line to give the program's name and a brief idea of what it does.}
753: Copyright (C) 19@var{yy} @var{name of author}
754:
755: This program is free software; you can redistribute it and/or modify
756: it under the terms of the GNU General Public License as published by
757: the Free Software Foundation; either version 1, or (at your option)
758: any later version.
759:
760: This program is distributed in the hope that it will be useful,
761: but WITHOUT ANY WARRANTY; without even the implied warranty of
762: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
763: GNU General Public License for more details.
764:
765: You should have received a copy of the GNU General Public License
766: along with this program; if not, write to the Free Software
767: Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
768: @end smallexample
769:
770: Also add information on how to contact you by electronic and paper mail.
771:
772: If the program is interactive, make it output a short notice like this
773: when it starts in an interactive mode:
774:
775: @smallexample
776: Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
777: Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
778: type `show w'. This is free software, and you are welcome
779: to redistribute it under certain conditions; type `show c'
780: for details.
781: @end smallexample
782:
783: The hypothetical commands `show w' and `show c' should show the
784: appropriate parts of the General Public License. Of course, the
785: commands you use may be called something other than `show w' and `show
786: c'; they could even be mouse-clicks or menu items---whatever suits your
787: program.
788:
789: You should also get your employer (if you work as a programmer) or your
790: school, if any, to sign a ``copyright disclaimer'' for the program, if
791: necessary. Here is a sample; alter the names:
792:
793: @example
794: Yoyodyne, Inc., hereby disclaims all copyright
795: interest in the program `Gnomovision'
796: (a program to direct compilers to make passes
797: at assemblers) written by James Hacker.
798:
799: @group
800: @var{signature of Ty Coon}, 1 April 1989
801: Ty Coon, President of Vice
802: @end group
803: @end example
804:
805: That's all there is to it!
806:
807: @node Intro, Glossary, License, Top
808: @unnumbered Introduction
809:
810: You are reading about GNU Emacs, the GNU incarnation of the advanced,
811: self-documenting, customizable, extensible real-time display editor Emacs.
812: (The `G' in `GNU' is not silent.)
813:
814: We say that Emacs is a @dfn{display} editor because normally the text
815: being edited is visible on the screen and is updated automatically as you
816: type your commands. @xref{Screen,Display}.
817:
818: We call it a @dfn{real-time} editor because the display is updated very
819: frequently, usually after each character or pair of characters you
820: type. This minimizes the amount of information you must keep in your
821: head as you edit. @xref{Basic,Real-time,Basic Editing}.
822:
823: We call Emacs advanced because it provides facilities that go beyond
824: simple insertion and deletion: filling of text; automatic indentation of
825: programs; viewing two or more files at once; and dealing in terms of
826: characters, words, lines, sentences, paragraphs, and pages, as well as
827: expressions and comments in several different programming languages. It is
828: much easier to type one command meaning ``go to the end of the paragraph''
829: than to find that spot with simple cursor keys.
830:
831: @dfn{Self-documenting} means that at any time you can type a special
832: character, @kbd{Control-h}, to find out what your options are. You can
833: also use it to find out what any command does, or to find all the commands
834: that pertain to a topic. @xref{Help}.
835:
836: @dfn{Customizable} means that you can change the definitions of Emacs
837: commands in little ways. For example, if you use a programming language in
838: which comments start with @samp{<**} and end with @samp{**>}, you can tell
839: the Emacs comment manipulation commands to use those strings
840: (@pxref{Comments}). Another sort of customization is rearrangement of the
841: command set. For example, if you prefer the four basic cursor motion
842: commands (up, down, left and right) on keys in a diamond pattern on the
843: keyboard, you can have it. @xref{Customization}.
844:
845: @dfn{Extensible} means that you can go beyond simple customization and
846: write entirely new commands, programs in the Lisp language to be run by
847: Emacs's own Lisp interpreter. Emacs is an ``on-line extensible'' system,
848: which means that it is divided into many functions that call each other,
849: any of which can be redefined in the middle of an editing session. Any
850: part of Emacs can be replaced without making a separate copy of all of
851: Emacs. Most of the editing commands of Emacs are written in Lisp already;
852: the few exceptions could have been written in Lisp but are written in C for
853: efficiency. Although only a programmer can write an extension, anybody can
854: use it afterward.
855:
856: @node Screen, Characters, Concept Index, Top
857: @chapter The Organization of the Screen
858: @cindex screen
859:
860: Emacs divides the screen into several areas, each of which contains
861: its own sorts of information. The biggest area, of course, is the one
862: in which you usually see the text you are editing.
863:
864: When you are using Emacs, the screen is divided into a number of
865: @dfn{windows}. Initially there is one text window occupying all but the
866: last line, plus the special @dfn{echo area} or @dfn{minibuffer window} in
867: the last line. The text window can be subdivided horizontally or
868: vertically into multiple text windows, each of which can be used for a
869: different file (@pxref{Windows}). The window that the cursor is in is the
870: @dfn{selected window}, in which editing takes place. The other windows are
871: just for reference unless you select one of them.
872:
873: Each text window's last line is a @dfn{mode line} which describes what is
874: going on in that window. It is in inverse video if the terminal supports
875: that, and contains text that starts like @samp{-----Emacs:@: @var{something}}. Its
876: purpose is to indicate what buffer is being displayed above it in the
877: window; what major and minor modes are in use; and whether the buffer's
878: text has been changed.
879:
880: @menu
881: * Point:: The place in the text where editing commands operate.
882: * Echo Area:: Short messages appear at the bottom of the screen.
883: * Mode Line:: Interpreting the mode line.
884: @end menu
885:
886: @node Point, Echo Area, Screen, Screen
887: @section Point
888: @cindex point
889: @cindex cursor
890:
891: When Emacs is running, the terminal's cursor shows the location at
892: which editing commands will take effect. This location is called
893: @dfn{point}. Other commands move point through the text, so that you
894: can edit at different places in it.
895:
896: While the cursor appears to point @var{at} a character, point should be
897: thought of as @var{between} two characters; it points @var{before} the character
898: that the cursor appears on top of. Sometimes people speak of ``the
899: cursor'' when they mean ``point'', or speak of commands that move point as
900: ``cursor motion'' commands.
901:
902: Terminals have only one cursor, and when output is in progress it must
903: appear where the typing is being done. This does not mean that point is
904: moving. It is only that Emacs has no way to show you the location of point
905: except when the terminal is idle.
906:
907: If you are editing several files in Emacs, each file has its own point
908: location. A file that is not being displayed remembers where point is so
909: that it can be seen when you look at that file again.
910:
911: When there are multiple text windows, each window has its own point
912: location. The cursor shows the location of point in the selected window.
913: This also is how you can tell which window is selected. If the same buffer
914: appears in more than one window, point can be moved in each window
915: independently.
916:
917: The term `point' comes from the character @samp{.}, which was the
918: command in @sc{teco} (the language in which the original Emacs was written)
919: for accessing the value now called `point'.
920:
921: @node Echo Area, Mode Line, Point, Screen
922: @section The Echo Area
923: @cindex echo area
924:
925: The line at the bottom of the screen (below the mode line) is the
926: @dfn{echo area}. It is used to display small amounts of text for several
927: purposes.
928:
929: @dfn{Echoing} means printing out the characters that you type. Emacs
930: never echoes single-character commands, and multi-character commands are
931: echoed only if you pause while typing them. As soon as you pause for more
932: than a second in the middle of a command, all the characters of the command
933: so far are echoed. This is intended to @dfn{prompt} you for the rest of
934: the command. Once echoing has started, the rest of the command is echoed
935: immediately when you type it. This behavior is designed to give confident
936: users fast response, while giving hesitant users maximum feedback. You
937: can change this behavior by setting a variable (@pxref{Display Vars}).
938:
939: If a command cannot be executed, it may print an @dfn{error message} in
940: the echo area. Error messages are accompanied by a beep or by flashing the
941: screen. Also, any input you have typed ahead is thrown away when an error
942: happens.
943:
944: Some commands print informative messages in the echo area. These
945: messages look much like error messages, but they are not announced with a
946: beep and do not throw away input. Sometimes the message tells you what the
947: command has done, when this is not obvious from looking at the text being
948: edited. Sometimes the sole purpose of a command is to print a message
949: giving you specific information. For example, the command @kbd{C-x =} is
950: used to print a message describing the character position of point in the
951: text and its current column in the window. Commands that take a long time
952: often display messages ending in @samp{...} while they are working, and
953: add @samp{done} at the end when they are finished.
954:
955: The echo area is also used to display the @dfn{minibuffer}, a window that
956: is used for reading arguments to commands, such as the name of a file to be
957: edited. When the minibuffer is in use, the echo area begins with a prompt
958: string that usually ends with a colon; also, the cursor appears in that line
959: because it is the selected window. You can always get out of the
960: minibuffer by typing @kbd{C-g}. @xref{Minibuffer}.
961:
962: @node Mode Line,, Echo Area, Screen
963: @section The Mode Line
964: @cindex mode line
965: @cindex top level
966:
967: Each text window's last line is a @dfn{mode line} which describes what is
968: going on in that window. When there is only one text window, the mode line
969: appears right above the echo area. The mode line is in inverse video if
970: the terminal supports that, starts and ends with dashes, and contains text
971: like @samp{Emacs:@: @var{something}}.
972:
973: If a mode line has something else in place of @samp{Emacs:@: @var{something}},
974: then the window above it is in a special subsystem such as Dired. The mode
975: line then indicates the status of the subsystem.
976:
977: Normally, the mode line has the following appearance:
978:
979: @example
980: --@var{ch}-Emacs: @var{buf} (@var{major} @var{minor})----@var{pos}------
981: @end example
982:
983: @noindent
984: This gives information about the buffer being displayed in the window: the
985: buffer's name, what major and minor modes are in use, whether the buffer's
986: text has been changed, and how far down the buffer you are currently
987: looking.
988:
989: @var{ch} contains two stars @samp{**} if the text in the buffer has been
990: edited (the buffer is ``modified''), or @samp{--} if the buffer has not been
991: edited. Exception: for a read-only buffer, it is @samp{%%}.
992:
993: @var{buf} is the name of the window's chosen @dfn{buffer}. The chosen buffer
994: in the selected window (the window that the cursor is in) is also Emacs's
995: selected buffer, the one that editing takes place in. When we speak of
996: what some command does to ``the buffer'', we are talking about the
997: currently selected buffer. @xref{Buffers}.
998:
999: @var{pos} tells you whether there is additional text above the top of the
1000: screen, or below the bottom. If your file is small and it is all on the
1001: screen, @var{pos} is @samp{All}. Otherwise, it is @samp{Top} if you are
1002: looking at the beginning of the file, @samp{Bot} if you are looking at the
1003: end of the file, or @samp{@var{nn}%}, where @var{nn} is the percentage of
1004: the file above the top of the screen.@refill
1005:
1006: @var{major} is the name of the @dfn{major mode} in effect in the buffer. At
1007: any time, each buffer is in one and only one of the possible major modes.
1008: The major modes available include Fundamental mode (the least specialized),
1009: Text mode, Lisp mode, and C mode. @xref{Major Modes}, for details
1010: of how the modes differ and how to select one.@refill
1011:
1012: @var{minor} is a list of some of the @dfn{minor modes} that are turned on
1013: at the moment in the window's chosen buffer. @samp{Fill} means that Auto
1014: Fill mode is on. @samp{Abbrev} means that Word Abbrev mode is on.
1015: @samp{Ovwrt} means that Overwrite mode is on. @xref{Minor Modes}, for more
1016: information. @samp{Narrow} means that the buffer being displayed has
1017: editing restricted to only a portion of its text. This is not really a
1018: minor mode, but is like one. @xref{Narrowing}. @samp{Def} means that a
1019: keyboard macro is being defined. @xref{Keyboard Macros}.
1020:
1021: Some buffers display additional information after the minor modes. For
1022: example, Rmail buffers display the current message number and the total
1023: number of messages. Compilation buffers and Shell mode display the status
1024: of the subprocess.
1025:
1026: In addition, if Emacs is currently inside a recursive editing level,
1027: square brackets (@samp{[@dots{}]}) appear around the parentheses that
1028: surround the modes. If Emacs is in one recursive editing level within
1029: another, double square brackets appear, and so on. Since this information
1030: pertains to Emacs in general and not to any one buffer, the square brackets
1031: appear in every mode line on the screen or not in any of them.
1032: @xref{Recursive Edit}.@refill
1033:
1034: @cindex display time
1035: @cindex time displayed in mode line
1036: @findex display-time
1037: Emacs can optionally display the time and system load in all mode lines.
1038: To enable this feature, type @kbd{M-x display-time}. The information added
1039: to the mode line usually appears after the file name, before the mode names
1040: and their parentheses. It looks like this:
1041:
1042: @example
1043: @var{hh}:@var{mm}pm @var{l.ll} [@var{d}]
1044: @end example
1045:
1046: @noindent
1047: (Some fields may be missing if your operating system cannot support them.)
1048: @var{hh} and @var{mm} are the hour and minute, followed always by @samp{am}
1049: or @samp{pm}. @var{l.ll} is the average number of running processes in the
1050: whole system recently. @var{d} is an approximate index of the ratio of
1051: disk activity to cpu activity for all users.
1052:
1053: @cindex mail arrival
1054: The word @samp{Mail} appears after the load level if there is mail for
1055: you that you have not read yet.
1056:
1057: @vindex mode-line-inverse-video
1058: Customization note: the user variable @code{mode-line-inverse-video} controls
1059: whether the mode line is displayed in inverse video (assuming the
1060: terminal supports it); @code{nil} means no inverse video. The default
1061: is @code{t}.
1062:
1063: @iftex
1064: @chapter Characters, Keys and Commands
1065:
1066: This chapter explains the character set used by Emacs for input commands
1067: and for the contents of files, and also explains the concepts of
1068: @dfn{keys} and @dfn{commands} which are necessary for understanding how
1069: your keyboard input is understood by Emacs.
1070: @end iftex
1071:
1072: @node Characters, Keys, Screen, Top
1073: @section The Emacs Character Set
1074: @cindex character set
1075: @cindex ASCII
1076:
1077: GNU Emacs uses the @sc{ascii} character set, which defines 128 different
1078: character codes. Some of these codes are assigned graphic symbols such
1079: as @samp{a} and @samp{=}; the rest are control characters, such as
1080: @kbd{Control-a} (also called @kbd{C-a} for short). @kbd{C-a} gets its name
1081: from the fact that you type it by holding down the @key{CTRL} key and
1082: then pressing @kbd{a}. There is no distinction between @kbd{C-a} and
1083: @kbd{C-A}; they are the same character.@refill
1084:
1085: Some control characters have special names, and special keys you can
1086: type them with: @key{RET}, @key{TAB}, @key{LFD}, @key{DEL} and @key{ESC}.
1087: The space character is usually referred to below as @key{SPC}, even though
1088: strictly speaking it is a graphic character whose graphic happens to be
1089: blank.@refill
1090:
1091: Emacs extends the 7-bit @sc{ascii} code to an 8-bit code by adding an extra
1092: bit to each character. This makes 256 possible command characters. The
1093: additional bit is called Meta. Any @sc{ascii} character can be made Meta;
1094: examples of Meta characters include @kbd{Meta-a} (@kbd{M-a}, for short),
1095: @kbd{M-A} (not the same character as @kbd{M-a}, but those two characters
1096: normally have the same meaning in Emacs), @kbd{M-@key{RET}}, and
1097: @kbd{M-C-a}. For traditional reasons, @kbd{M-C-a} is usually called
1098: @kbd{C-M-a}; logically speaking, the order in which the modifier keys
1099: @key{CTRL} and @key{META} are mentioned does not matter.@refill
1100:
1101: @cindex Control
1102: @cindex Meta
1103: @cindex C-
1104: @cindex M-
1105: @cindex ESC replacing META key
1106: Some terminals have a @key{META} key, and allow you to type Meta
1107: characters by holding this key down. Thus, @kbd{Meta-a} is typed by
1108: holding down @key{META} and pressing @kbd{a}. The @key{META} key works
1109: much like the @key{SHIFT} key. Such a key is not always labeled
1110: @key{META}, however, as this function is often a special option for a key
1111: with some other primary purpose.@refill
1112:
1113: If there is no @key{META} key, you
1114: can still type Meta characters using two-character sequences starting with
1115: @key{ESC}. Thus, to enter @kbd{M-a}, you could type @kbd{@key{ESC} a}. To
1116: enter @kbd{C-M-a}, you would type @kbd{@key{ESC} C-a}. @key{ESC} is
1117: allowed on terminals with Meta keys, too, in case you have formed a habit
1118: of using it.@refill
1119:
1120: @vindex meta-flag
1121: Emacs believes the terminal has a @key{META} key if the variable
1122: @code{meta-flag} is non-@code{nil}. Normally this is set automatically
1123: according to the termcap entry for your terminal type. However, sometimes
1124: the termcap entry is wrong, and then it is useful to set this variable
1125: yourself. @xref{Variables}, for how to do this.
1126:
1127: Emacs buffers also use an 8-bit character set, because bytes have 8 bits,
1128: but only the @sc{ascii} characters are considered meaningful.
1129: @sc{ascii} graphic characters in Emacs buffers are displayed with
1130: their graphics. @key{LFD} is the same as a newline character; it is
1131: displayed by starting a new line. @key{TAB} is displayed by moving to
1132: the next tab stop column (usually every 8 columns). Other control
1133: characters are displayed as a caret (@samp{^}) followed by the
1134: non-control version of the character; thus, @kbd{C-a} is displayed as
1135: @samp{^A}. Non-@sc{ascii} characters 128 and up are displayed with octal
1136: escape sequences; thus, character code 243 (octal), also called
1137: @kbd{M-#} when used as an input character, is displayed as
1138: @samp{\243}.
1139: @c !! need glossary definition of octal escape sequence
1140:
1141: @node Keys, Commands, Characters, Top
1142: @section Keys
1143:
1144: @cindex key
1145: @cindex prefix key
1146: A @dfn{complete key}---where `key' is short for @dfn{key sequence}---is a
1147: sequence of keystrokes that are understood by Emacs as a unit, as a single
1148: command (possibly undefined). Most single characters constitute complete
1149: keys in the standard Emacs command set; there are also some multi-character
1150: keys. Examples of complete keys are @kbd{C-a}, @kbd{X}, @key{RET},
1151: @kbd{C-x C-f} and @kbd{C-x 4 C-f}.@refill
1152:
1153: @kindex C-c
1154: @kindex C-x
1155: @kindex C-h
1156: @kindex ESC
1157: A @dfn{prefix key} is a sequence of keystrokes that are the beginning of
1158: a complete key, but not a whole one. Prefix keys and complete keys are
1159: collectively called @dfn{keys}.
1160:
1161: A prefix key is the beginning of a series of longer sequences that are
1162: valid keys; adding any single character to the end of the prefix gives a
1163: valid key, which could be defined as an Emacs command, or could be a prefix
1164: itself. For example, @kbd{C-x} is standardly defined as a prefix, so
1165: @kbd{C-x} and the next input character combine to make a two-character key.
1166: There are 256 different two-character keys starting with @kbd{C-x}, one for
1167: each possible second character. Many of these two-character keys starting
1168: with @kbd{C-x} are standardly defined as Emacs commands. Notable examples
1169: include @kbd{C-x C-f} and @kbd{C-x s} (@pxref{Files}).
1170:
1171: Adding one character to a prefix key does not have to form a complete
1172: key. It could make another, longer prefix. For example, @kbd{C-x 4} is
1173: itself a prefix that leads to 256 different three-character keys, including
1174: @kbd{C-x 4 f}, @w{@kbd{C-x 4 b}} and so on. It would be possible to define one
1175: of those three-character sequences as a prefix, creating a series of
1176: four-character keys, but we did not define any of them this way.
1177:
1178: By contrast, the two-character sequence @kbd{C-f C-k} is not a key,
1179: because the @kbd{C-f} is a complete key in itself. It's impossible to give
1180: @kbd{C-f C-k} an independent meaning as a command as long as @kbd{C-f}
1181: retains its meaning. @kbd{C-f C-k} is two commands.@refill
1182:
1183: All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
1184: @kbd{C-x 4}, and @key{ESC}. But this is not built in; it is just a matter
1185: of Emacs's standard key bindings. In customizing Emacs, you could make
1186: new prefix keys, or eliminate these. @xref{Key Bindings}.@refill
1187:
1188: Whether a sequence is a key can be changed by customization. For
1189: example, if you redefine @kbd{C-f} as a prefix, @kbd{C-f C-k} automatically
1190: becomes a key (complete, unless you define it too as a prefix).
1191: Conversely, if you remove the prefix definition of @kbd{C-x 4}, then
1192: @kbd{C-x 4 f} (or @kbd{C-x 4 @var{anything}}) is no longer a key.
1193:
1194: @node Commands, Entering Emacs, Keys, Top
1195: @section Keys and Commands
1196:
1197: @cindex binding
1198: @cindex customization
1199: @cindex keymap
1200: @cindex function
1201: @cindex command
1202: This manual is full of passages that tell you what particular keys do.
1203: But Emacs does not assign meanings to keys directly. Instead, Emacs
1204: assigns meanings to @dfn{functions}, and then gives keys their meanings by
1205: @dfn{binding} them to functions.
1206:
1207: A function is a Lisp object that can be executed as a program. Usually
1208: it is a Lisp symbol which has been given a function definition; every
1209: symbol has a name, usually made of a few English words separated by
1210: dashes, such as @code{next-line} or @code{forward-word}. It also has a
1211: @dfn{definition} which is a Lisp program; this is what makes the
1212: function do what it does. Only some functions can be the bindings of
1213: keys; these are functions whose definitions use @code{interactive} to
1214: specify how to call them interactively. Such functions are called
1215: @dfn{commands}, and their names are @dfn{command names}.
1216: @xref{Defining Commands, , Defining Commands, elisp, The GNU Emacs Lisp
1217: Manual}, for more information.
1218:
1219: The bindings between keys and functions are recorded in various tables
1220: called @dfn{keymaps}. @xref{Keymaps}.
1221:
1222: When we say that ``@kbd{C-n} moves down vertically one line'' we are
1223: glossing over a distinction that is irrelevant in ordinary use but is vital
1224: in understanding how to customize Emacs. It is the function
1225: @code{next-line} that is programmed to move down vertically. @kbd{C-n} has
1226: this effect @i{because} it is bound to that function. If you rebind
1227: @kbd{C-n} to the function @code{forward-word} then @kbd{C-n} will move
1228: forward by words instead. Rebinding keys is a common method of
1229: customization.@refill
1230:
1231: In the rest of this manual, we usually ignore this subtlety to keep
1232: things simple. To give the customizer the information he needs, we
1233: state the name of the command which really does the work in parentheses
1234: after mentioning the key that runs it. For example, we will say that
1235: ``The command @kbd{C-n} (@code{next-line}) moves point vertically down,''
1236: meaning that @code{next-line} is a command that moves vertically down
1237: and @kbd{C-n} is a key that is standardly bound to it.
1238:
1239: While we are on the subject of information for customization only, it's a
1240: good time to tell you about @dfn{variables}. Often the description of a
1241: command will say, ``To change this, set the variable @code{mumble-foo}.''
1242: A variable is a name used to remember a value. Most of the variables
1243: documented in this manual exist just to facilitate customization: some
1244: command or other part of Emacs examines the variable and behaves
1245: differently accordingly. Until you are interested in customizing, you can
1246: ignore the information about variables. When you are ready to be
1247: interested, read the basic information on variables, and then the
1248: information on individual variables will make sense. @xref{Variables}.
1249:
1250: @node Entering Emacs, Exiting, Commands, Top
1251: @chapter Entering and Exiting Emacs
1252: @cindex entering Emacs
1253:
1254: The usual way to invoke Emacs is just to type @kbd{emacs @key{RET}} at
1255: the shell. Emacs clears the screen and then displays an initial advisor
1256: message and copyright notice. You can begin typing Emacs commands
1257: immediately afterward.
1258:
1259: Some operating systems insist on discarding all type-ahead when Emacs
1260: starts up; they give Emacs no way to prevent this. Therefore, it is
1261: wise to wait until Emacs clears the screen before typing your first
1262: editing command.
1263:
1264: @vindex initial-major-mode
1265: Before Emacs reads the first command, you have not had a chance to give a
1266: command to specify a file to edit. But Emacs must always have a current
1267: buffer for editing. In an attempt to do something useful, Emacs presents a
1268: buffer named @samp{*scratch*} which is in Lisp Interaction mode; you can
1269: use it to type Lisp expressions and evaluate them, or you can ignore that
1270: capability and simply doodle. (You can specify a different major mode for
1271: this buffer by setting the variable @code{initial-major-mode} in your init
1272: file. @xref{Init File}.)
1273:
1274: It is also possible to specify files to be visited, Lisp files to be
1275: loaded, and functions to be called, by giving Emacs arguments in the
1276: shell command line. @xref{Command Switches}.
1277:
1278: @node Exiting, Command Switches, Entering Emacs, Top
1279: @section Exiting Emacs
1280: @cindex exiting
1281: @cindex killing Emacs
1282: @cindex suspending
1283:
1284: There are two commands for exiting Emacs because there are two kinds of
1285: exiting: @dfn{suspending} Emacs and @dfn{killing} Emacs. @dfn{Suspending} means
1286: stopping Emacs temporarily and returning control to its superior (usually
1287: the shell), allowing you to resume editing later in the same Emacs job,
1288: with the same files, same kill ring, same undo history, and so on. This is
1289: the usual way to exit. @dfn{Killing} Emacs means destroying the Emacs job.
1290: You can run Emacs again later, but you will get a fresh Emacs; there is no
1291: way to resume the same editing session after it has been killed.
1292:
1293: @table @kbd
1294: @item C-z
1295: Suspend Emacs (@code{suspend-emacs}).
1296: @item C-x C-c
1297: Kill Emacs (@code{save-buffers-kill-emacs}).
1298: @end table
1299:
1300: @kindex C-z
1301: @findex suspend-emacs
1302: To suspend Emacs, type @kbd{C-z} (@code{suspend-emacs}). This takes
1303: you back to the shell from which you invoked Emacs. You can resume
1304: Emacs with the command @code{%emacs} if you are using the C shell or the
1305: Bourne-Again shell.
1306:
1307: On systems that do not permit programs to be suspended, @kbd{C-z} runs an
1308: inferior shell that communicates directly with the terminal, and Emacs
1309: waits until you exit the subshell. The only way on these systems to get
1310: back to the shell from which Emacs was run (to log out, for example) is to
1311: kill Emacs. @kbd{C-d} or @code{exit} are typical commands to exit a
1312: subshell.
1313:
1314: @kindex C-x C-c
1315: @findex save-buffers-kill-emacs
1316: To kill Emacs, type @kbd{C-x C-c} (@code{save-buffers-kill-emacs}). A
1317: two-character key is used for this to make it harder to type. Unless a
1318: numeric argument is used, this command first offers to save any modified
1319: buffers. If you do not save them all, it asks for reconfirmation with
1320: @kbd{yes} before killing Emacs, since any changes not saved before that will be
1321: lost forever. Also, if any subprocesses are still running, @kbd{C-x C-c}
1322: asks for confirmation about them, since killing Emacs will kill the
1323: subprocesses immediately.
1324:
1325: In most programs running on Unix, certain characters may instantly
1326: suspend or kill the program. (In Berkeley Unix these characters are
1327: normally @kbd{C-z} and @kbd{C-c}.) @b{This Unix feature is turned off
1328: while you are in Emacs.} The meanings of @kbd{C-z} and @kbd{C-x C-c} as
1329: keys in Emacs were inspired by the standard Berkeley Unix meanings of
1330: @kbd{C-z} and @kbd{C-c}, but that is their only relationship with
1331: Unix. You could customize these keys to do anything (@pxref{Keymaps}).
1332:
1333: @node Command Switches, Basic, Exiting, Top
1334: @section Command Line Switches and Arguments
1335: @cindex command line arguments
1336: @cindex arguments (from shell)
1337:
1338:
1339: GNU Emacs supports command line arguments to request various actions
1340: when invoking Emacs. These are for compatibility with other editors and
1341: for sophisticated activities. They are not needed for ordinary editing
1342: with Emacs, so new users can skip this section.
1343:
1344: You may be used to using command line arguments with other editors
1345: to specify which file to edit. That's because many other editors are
1346: designed to be started afresh each time you want to edit. You
1347: edit one file and then exit the editor. The next time you want to edit
1348: either another file or the same one, you must run the editor again.
1349: With these editors, it makes sense to use a command line argument
1350: to say which file to edit.
1351:
1352: The recommended way to use GNU Emacs is to start it only once, just after
1353: you log in, and do all your editing in the same Emacs process. Each time
1354: you want to edit a different file, you visit it with the existing Emacs,
1355: which eventually comes to have many files in it ready for editing. Usually
1356: you do not kill the Emacs until you are about to log out.
1357:
1358: In the usual style of Emacs use, files are nearly always read by
1359: typing commands to an editor that is already running. So command line
1360: arguments for specifying a file when the editor is started are seldom
1361: used.
1362:
1363: Emacs accepts command-line arguments that specify files to visit,
1364: functions to call, and other activities and operating modes.
1365:
1366: The command arguments are processed in the order they appear in the
1367: command argument list; however, certain arguments (the ones in the second
1368: table) must be at the front of the list if they are used.
1369:
1370: Here are the arguments allowed:
1371:
1372: @table @samp
1373: @item @var{file}
1374: Visit @var{file} using @code{find-file}. @xref{Visiting}.
1375:
1376: @item +@var{linenum} @var{file}
1377: Visit @var{file} using @code{find-file}, then go to line number
1378: @var{linenum} in it.
1379:
1380: @item -l @var{file}
1381: @itemx -load @var{file}
1382: Load a file @var{file} of Lisp code with the function @code{load}.
1383: @xref{Lisp Libraries}.
1384:
1385: @item -f @var{function}
1386: @itemx -funcall @var{function}
1387: Call Lisp function @var{function} with no arguments.
1388:
1389: @item -i @var{file}
1390: @itemx -insert @var{file}
1391: Insert the contents of @var{file} into the current buffer.
1392: This is like what @kbd{M-x insert-buffer} does; see @ref{Misc File Ops}.
1393:
1394: @item -kill
1395: Exit from Emacs without asking for confirmation.
1396: @end table
1397:
1398: The following switches are recognized only at the beginning of the
1399: command line. If more than one of them appears, they must appear in the
1400: order that they appear in this table.
1401:
1402: @table @samp
1403: @item -t @var{device}
1404: Use @var{device} as the device for terminal input and output.
1405:
1406: @item -d @var{display}
1407: When running with the X window system, use the display named
1408: @var{display} to make Emacs's X window.
1409:
1410: @item -nw
1411: Don't use a window system; display text only, using an ordinary terminal
1412: device. Thus, if you run an X-capable Emacs in an Xterm with
1413: @samp{emacs -nw}, it displays in the Xterm's own window instead of
1414: making its own.
1415:
1416: @cindex batch mode
1417: @item -batch
1418: Run Emacs in @dfn{batch mode}, which means that the text being edited is
1419: not displayed and the standard Unix interrupt characters such as @kbd{C-z}
1420: and @kbd{C-c} continue to have their normal effect. Emacs in batch mode
1421: outputs to @code{stdout} only what would normally be printed in the echo
1422: area under program control.
1423:
1424: Batch mode is used for running programs written in Emacs Lisp from
1425: shell scripts, makefiles, and so on. Normally the @samp{-l} switch
1426: or @samp{-f} switch will be used as well, to invoke a Lisp program
1427: to do the batch processing.
1428:
1429: @samp{-batch} implies @samp{-q} (do not load an init file). It also
1430: causes Emacs to exit after all command switches have been processed. In
1431: addition, auto-saving is not done except in buffers for which it has
1432: been explicitly requested.
1433:
1434: @item -q
1435: @itemx -no-init-file
1436: Do not load your Emacs init file @file{~/.emacs}.
1437:
1438: @item -u @var{user}
1439: @itemx -user @var{user}
1440: Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
1441: your own.
1442: @end table
1443:
1444: With X Windows, you can use these additional options to specify how to
1445: display the window. Each option has a corresponding resource name (used
1446: with @samp{emacs} unless you specify another name with @samp{-rn
1447: @var{name}}), listed with the option, which lets you specify the same
1448: parameter using the usual X Windows defaulting mechanism. The
1449: corresponding generic resource name (used with @samp{Emacs}) is usually
1450: made by capitalizing the first letter of the individual resource name,
1451: but in some cases it is a completely different string (which is listed
1452: below).
1453:
1454: @table @code
1455: @item -rn @var{name}
1456: Use @var{name} instead of @samp{emacs} when looking for X resources.
1457:
1458: @item -font @var{fontname}
1459: @itemx -fn @var{fontname}
1460: Use font @var{fontname}.@*
1461: (Resource @samp{font}.)
1462:
1463: @item -wn @var{name}
1464: Name the window @var{name}.@*
1465: (Resource @samp{title}.)
1466:
1467: @item -i
1468: Use a bitmap icon (showing the kitchen sink)
1469: rather than a textual icon.@*
1470: (Resource @samp{bitmapIcon}.)
1471:
1472: @item -in @var{name}
1473: Name the icon @var{name}. (Resource @samp{iconName}; @samp{Title}).
1474:
1475: @item -geometry @var{coords}
1476: @itemx -w @var{coords}
1477: Specify the shape and optionally the position
1478: of the Emacs window in the usual X way.@*
1479: (Resource @samp{geometry}.)
1480:
1481: @item -b @var{width}
1482: Specify that the window border is @var{width} pixels thick.@*
1483: (Resource @samp{borderWidth}.)
1484:
1485: @item -ib @var{width}
1486: Leave @var{width} blank pixels between the border
1487: and the window contents.@*
1488: (Resource @samp{internalBorder}; @samp{BorderWidth}.)
1489:
1490: @item -r
1491: Use reverse video.@*
1492: (Resource @samp{reverseVideo}.)
1493:
1494: @item -fg @var{color}
1495: Use color @var{color} for text in the window.@*
1496: (Resource @samp{foreground}.)
1497:
1498: @item -bg @var{color}
1499: Use the color @var{color} for the background of the window.@*
1500: (Resource @samp{background}.)
1501:
1502: @item -bd @var{color}
1503: Use color @var{color} for the window border.@*
1504: (Resource @samp{borderColor}.)
1505:
1506: @item -cr @var{color}
1507: Specify the color, @var{color}, to use for the cursor.@*
1508: (Resource @samp{cursorColor}; @samp{Foreground}.)
1509:
1510: @item -ms @var{color}
1511: Use color @var{color} for the mouse cursor.@*
1512: (Resource @samp{pointerColor}; @samp{Foreground}.)
1513: @end table
1514:
1515: @vindex command-line-args
1516: The init file can get access to the command line argument values as
1517: the elements of a list in the variable @code{command-line-args}. (The
1518: arguments in the second table above will already have been processed and
1519: will not be in the list.) The init file can override the normal
1520: processing of the other arguments by setting this variable.
1521:
1522: One way to use command arguments is to visit many files automatically:
1523:
1524: @example
1525: emacs *.c
1526: @end example
1527:
1528: @noindent
1529: passes each @code{.c} file as a separate argument to Emacs, so that Emacs
1530: visits each file (@pxref{Visiting}).
1531:
1532: Here is an advanced example that assumes you have a Lisp program
1533: file called @file{hack-c-program.el} which, when loaded, performs some
1534: useful operation on current buffer, expected to be a C program.
1535:
1536: @smallexample
1537: emacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
1538: @end smallexample
1539:
1540: @noindent
1541: This says to visit @file{foo.c}, load @file{hack-c-program.el} (which
1542: makes changes in the visited file), save @file{foo.c} (note that
1543: @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
1544: then exit to the shell that this command was done with. @samp{-batch}
1545: guarantees there will be no problem redirecting output to @file{log},
1546: because Emacs will not assume that it has a display terminal to work
1547: with.
1548:
1549: @node Basic, Undo, Command Switches, Top
1550: @chapter Basic Editing Commands
1551:
1552: @kindex C-h t
1553: @findex help-with-tutorial
1554: We now give the basics of how to enter text, make corrections, and
1555: save the text in a file. If this material is new to you, you might
1556: learn it more easily by running the Emacs learn-by-doing tutorial. To
1557: do this, type @w{@kbd{Control-h t}} (@code{help-with-tutorial}).
1558:
1559: @section Inserting Text
1560:
1561: @cindex insertion
1562: @cindex point
1563: @cindex cursor
1564: @cindex graphic characters
1565: To insert printing characters into the text you are editing, just type
1566: them. This inserts the character into the buffer at the cursor (that is,
1567: at @dfn{point}; @pxref{Point}). The cursor moves forward. Any characters
1568: after the cursor move forward too. If the text in the buffer is
1569: @samp{FOOBAR}, with the cursor before the @samp{B}, then if you type
1570: @kbd{XX}, you get @samp{FOOXXBAR}, with the cursor still before the
1571: @samp{B}.
1572:
1573: @kindex DEL
1574: @cindex deletion
1575: To @dfn{delete} text you have just inserted, use @key{DEL}. @key{DEL}
1576: deletes the character @var{before} the cursor (not the one that the cursor
1577: is on top of or under; that is the character @var{after} the cursor). The
1578: cursor and all characters after it move backwards. Therefore, if you type
1579: a printing character and then type @key{DEL}, they cancel out.
1580:
1581: @kindex RET
1582: @cindex newline
1583: To end a line and start typing a new one, type @key{RET}. This inserts
1584: a newline character in the buffer. If point is in the middle of a line,
1585: @key{RET} splits the line. Typing @key{DEL} when the cursor is at the
1586: beginning of a line rubs out the newline before the line, thus joining the
1587: line with the preceding line.
1588:
1589: Emacs will split lines automatically when they become too long, if you
1590: turn on a special mode called @dfn{Auto Fill} mode. @xref{Filling}, for
1591: how to use Auto Fill mode.
1592:
1593: @findex delete-backward-char
1594: @findex newline
1595: @findex self-insert
1596: Customization information: @key{DEL} in most modes runs the command named
1597: @code{delete-backward-char}; @key{RET} runs the command @code{newline}, and
1598: self-inserting printing characters run the command @code{self-insert},
1599: which inserts whatever character was typed to invoke it. Some major modes
1600: rebind @key{DEL} to other commands.
1601:
1602: @cindex quoting
1603: @kindex C-q
1604: @findex quoted-insert
1605: Direct insertion works for printing characters and @key{SPC}, but other
1606: characters act as editing commands and do not insert themselves. If you
1607: need to insert a control character or a character whose code is above 200
1608: octal, you must @dfn{quote} it by typing the character @kbd{control-q}
1609: (@code{quoted-insert}) first. There are two ways to use @kbd{C-q}:@refill
1610:
1611: @itemize @bullet
1612: @item
1613: @kbd{Control-q} followed by any non-graphic character (even @kbd{C-g})
1614: inserts that character.
1615: @item
1616: @kbd{Control-q} followed by three octal digits inserts the character
1617: with the specified character code.
1618: @end itemize
1619:
1620: @noindent
1621: A numeric argument to @kbd{C-q} specifies how many copies of the
1622: quoted character should be inserted (@pxref{Arguments}).
1623:
1624: If you prefer to have text characters replace (overwrite) existing
1625: text rather than shove it to the right, you can enable Overwrite mode,
1626: a minor mode. @xref{Minor Modes}.
1627:
1628: @section Changing the Location of Point
1629:
1630: To do more than insert characters, you have to know how to move
1631: point (@pxref{Point}). Here are a few of the commands for doing that.
1632:
1633: @kindex C-a
1634: @kindex C-e
1635: @kindex C-f
1636: @kindex C-b
1637: @kindex C-n
1638: @kindex C-p
1639: @kindex C-l
1640: @kindex C-t
1641: @kindex M->
1642: @kindex M-<
1643: @kindex M-r
1644: @findex beginning-of-line
1645: @findex end-of-line
1646: @findex forward-char
1647: @findex backward-char
1648: @findex next-line
1649: @findex previous-line
1650: @findex recenter
1651: @findex transpose-chars
1652: @findex beginning-of-buffer
1653: @findex end-of-buffer
1654: @findex goto-char
1655: @findex goto-line
1656: @findex move-to-window-line
1657: @table @kbd
1658: @item C-a
1659: Move to the beginning of the line (@code{beginning-of-line}).
1660: @item C-e
1661: Move to the end of the line (@code{end-of-line}).
1662: @item C-f
1663: Move forward one character (@code{forward-char}).
1664: @item C-b
1665: Move backward one character (@code{backward-char}).
1666: @item M-f
1667: Move forward one word (@code{forward-word}).
1668: @item M-b
1669: Move backward one word (@code{backward-word}).
1670: @item C-n
1671: Move down one line, vertically (@code{next-line}). This command
1672: attempts to keep the horizontal position unchanged, so if you start in
1673: the middle of one line, you end in the middle of the next. When on
1674: the last line of text, @kbd{C-n} creates a new line and moves onto it.
1675: @item C-p
1676: Move up one line, vertically (@code{previous-line}).
1677: @item C-l
1678: Clear the screen and reprint everything (@code{recenter}). Text moves
1679: on the screen to bring point to the center of the window.
1680: @item M-r
1681: Move point to left margin on the line halfway down the screen or
1682: window (@code{move-to-window-line}). Text does not move on the
1683: screen. A numeric argument says how many screen lines down from the
1684: top of the window (zero for the top). A negative argument counts from
1685: the bottom (@minus{}1 for the bottom).
1686: @item C-t
1687: Transpose two characters, the ones before and after the cursor
1688: (@code{transpose-chars}).
1689: @item M-<
1690: Move to the top of the buffer (@code{beginning-of-buffer}). With
1691: numeric argument @var{n}, move to @var{n}/10 of the way from the top.
1692: @xref{Arguments}, for more information on numeric arguments.@refill
1693: @item M->
1694: Move to the end of the buffer (@code{end-of-buffer}).
1695: @item M-x goto-char
1696: Read a number @var{n} and move cursor to character number @var{n}.
1697: Position 1 is the beginning of the buffer.
1698: @item M-x goto-line
1699: Read a number @var{n} and move cursor to line number @var{n}. Line 1
1700: is the beginning of the buffer.
1701: @item C-x C-n
1702: @findex set-goal-column
1703: @cindex goal column
1704: Use the current column of point as the @dfn{semipermanent goal column} for
1705: @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). Henceforth, those
1706: commands always move to this column in each line moved into, or as
1707: close as possible given the contents of the line. This goal column remains
1708: in effect until canceled.
1709: @item C-u C-x C-n
1710: Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} once
1711: again try to avoid changing the horizontal position, as usual.
1712: @end table
1713:
1714: @vindex track-eol
1715: If you set the variable @code{track-eol} to a non-@code{nil} value, then
1716: @kbd{C-n} and @kbd{C-p} when at the end of the starting line move to the
1717: end of the line. Normally, @code{track-eol} is @code{nil}.
1718:
1719: @section Erasing Text
1720:
1721: @table @kbd
1722: @item @key{DEL}
1723: Delete the character before the cursor (@code{delete-backward-char}).
1724: @item C-d
1725: Delete the character after the cursor (@code{delete-char}).
1726: @item C-k
1727: Kill to the end of the line (@code{kill-line}).
1728: @item M-d
1729: Kill forward to the end of the next word (@code{kill-word}).
1730: @item M-@key{DEL}
1731: Kill back to the beginning of the previous word
1732: (@code{backward-kill-word}).
1733: @end table
1734:
1735: You already know about the @key{DEL} key which deletes the character
1736: before the cursor. Another key, @kbd{Control-d}, deletes the character
1737: after the cursor, causing the rest of the text on the line to shift left.
1738: If @kbd{Control-d} is typed at the end of a line, that line and the next
1739: line are joined together.
1740:
1741: To erase a larger amount of text, use the @kbd{Control-k} key, which
1742: kills a line at a time. If @kbd{C-k} is done at the beginning or middle of
1743: a line, it kills all the text up to the end of the line. If @kbd{C-k} is
1744: done at the end of a line, it joins that line and the next line.
1745:
1746: @xref{Killing}, for more flexible ways of killing text.
1747:
1748: @section Files
1749:
1750: @cindex files
1751: The commands above are sufficient for creating and altering text in an
1752: Emacs buffer; the more advanced Emacs commands just make things easier.
1753: But to keep any text permanently you must put it in a @dfn{file}. Files
1754: are named units of text which are stored by the operating system for you to
1755: retrieve later by name. To look at or use the contents of a file in any
1756: way, including editing the file with Emacs, you must specify the file name.
1757:
1758: Consider a file named @file{/usr/rms/foo.c}. In Emacs, to begin editing
1759: this file, type
1760:
1761: @example
1762: C-x C-f /usr/rms/foo.c @key{RET}
1763: @end example
1764:
1765: @noindent
1766: Here the file name is given as an @dfn{argument} to the command @kbd{C-x
1767: C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to
1768: read the argument, and you type @key{RET} to terminate the argument
1769: (@pxref{Minibuffer}).@refill
1770:
1771: Emacs obeys the command by @dfn{visiting} the file: creating a buffer,
1772: copying the contents of the file into the buffer, and then displaying the
1773: buffer for you to edit. You can make changes in it, and then @dfn{save}
1774: the file by typing @kbd{C-x C-s} (@code{save-buffer}). This makes the
1775: changes permanent by copying the altered contents of the buffer back into
1776: the file @file{/usr/rms/foo.c}. Until then, the changes are only inside
1777: your Emacs, and the file @file{foo.c} is not changed.@refill
1778:
1779: To create a file, just visit the file with @kbd{C-x C-f} as if it already
1780: existed. Emacs will make an empty buffer in which you can insert the text
1781: you want to put in the file. When you save your text with @kbd{C-x C-s},
1782: the file will be created.
1783:
1784: Of course, there is a lot more to learn about using files. @xref{Files}.
1785:
1786: @section Help
1787:
1788: If you forget what a key does, you can find out with the Help character,
1789: which is @kbd{C-h}. Type @kbd{C-h k} followed by the key you want to know
1790: about; for example, @kbd{C-h k C-n} tells you all about what @kbd{C-n}
1791: does. @kbd{C-h} is a prefix key; @kbd{C-h k} is just one of its
1792: subcommands (the command @code{describe-key}). The other subcommands of
1793: @kbd{C-h} provide different kinds of help. Type @kbd{C-h} three times
1794: to get a description of all the help facilities. @xref{Help}.@refill
1795:
1796: @menu
1797: * Blank Lines:: Commands to make or delete blank lines.
1798: * Continuation Lines:: Lines too wide for the screen.
1799: * Position Info:: What page, line, row, or column is point on?
1800: * Arguments:: Numeric arguments for repeating a command.
1801: @end menu
1802:
1803: @page
1804: @node Blank Lines, Continuation Lines, Basic, Basic
1805: @section Blank Lines
1806:
1807: Here are special commands and techniques for putting in and taking out
1808: blank lines.
1809:
1810: @c widecommands
1811: @table @kbd
1812: @item C-o
1813: Insert one or more blank lines after the cursor (@code{open-line}).
1814: @item C-x C-o
1815: Delete all but one of many consecutive blank lines
1816: (@code{delete-blank-lines}).
1817: @end table
1818:
1819: @kindex C-o
1820: @kindex C-x C-o
1821: @cindex blank lines
1822: @findex open-line
1823: @findex delete-blank-lines
1824: When you want to insert a new line of text before an existing line, you
1825: can do it by typing the new line of text, followed by @key{RET}. However,
1826: it may be easier to see what you are doing if you first make a blank line
1827: and then insert the desired text into it. This is easy to do using the key
1828: @kbd{C-o} (@code{open-line}), which inserts a newline after point but leaves
1829: point in front of the newline. After @kbd{C-o}, type the text for the new
1830: line. @kbd{C-o F O O} has the same effect as @w{@kbd{F O O @key{RET}},} except for
1831: the final location of point.
1832:
1833: You can make several blank lines by typing @kbd{C-o} several times, or by
1834: giving it an argument to tell it how many blank lines to make.
1835: @xref{Arguments}, for how.
1836:
1837: If you have many blank lines in a row and want to get rid of them, use
1838: @kbd{C-x C-o} (@code{delete-blank-lines}). When point is on a blank line which
1839: is adjacent to at least one other blank line, @kbd{C-x C-o} deletes all but
1840: one of the consecutive blank lines, leaving exactly one. With point on a
1841: blank line with no other blank line adjacent to it, the sole blank line is
1842: deleted, leaving none. When point is on a nonblank line, @kbd{C-x C-o}
1843: deletes any blank lines following that nonblank line.
1844:
1845: @node Continuation Lines, Position Info, Blank Lines, Basic
1846: @section Continuation Lines
1847:
1848: @cindex continuation line
1849: If you add too many characters to one line, without breaking it with a
1850: @key{RET}, the line will grow to occupy two (or more) lines on the screen,
1851: with a @samp{\} at the extreme right margin of all but the last of them.
1852: The @samp{\} says that the following screen line is not really a distinct
1853: line in the text, but just the @dfn{continuation} of a line too long to fit
1854: the screen. Sometimes it is nice to have Emacs insert newlines
1855: automatically when a line gets too long; for this, use Auto Fill mode
1856: (@pxref{Filling}).
1857:
1858: @vindex truncate-lines
1859: @cindex truncation
1860: Instead of continuation, long lines can be displayed by @dfn{truncation}.
1861: This means that all the characters that do not fit in the width of the
1862: screen or window do not appear at all. They remain in the buffer,
1863: temporarily invisible. @samp{$} is used in the last column instead of
1864: @samp{\} to inform you that truncation is in effect.
1865:
1866: Continuation can be turned off for a particular buffer by setting the
1867: variable @code{truncate-lines} to non-@code{nil} in that buffer.
1868: Truncation instead of continuation also happens whenever horizontal
1869: scrolling is in use, and optionally whenever side-by-side windows are in
1870: use (@pxref{Windows}). Altering the value of @code{truncate-lines} makes
1871: it local to the current buffer; until that time, the default value is in
1872: effect. The default is initially @code{nil}. @xref{Locals}.@refill
1873:
1874: @node Position Info, Arguments, Continuation Lines, Basic
1875: @section Cursor Position Information
1876:
1877: If you are accustomed to other display editors, you may be surprised that
1878: Emacs does not always display the page number or line number of point in
1879: the mode line. This is because the text is stored in a way that makes it
1880: difficult to compute this information. Displaying them all the time would
1881: be intolerably slow. They are not needed very often in Emacs anyway,
1882: but there are commands to compute them and print them.
1883:
1884: @table @kbd
1885: @item M-x what-page
1886: Print page number of point, and line number within page.
1887: @item M-x what-line
1888: Print line number of point in the buffer.
1889: @item M-=
1890: Print number of lines in the current region (@code{count-lines-region}).
1891: @item C-x =
1892: Print character code of character after point, character position of
1893: point, and column of point (@code{what-cursor-position}).
1894: @end table
1895:
1896: @findex what-page
1897: @findex what-line
1898: @cindex line number
1899: There are two commands for printing line numbers. @kbd{M-x what-line}
1900: counts lines from the beginning of the file and prints the line number
1901: point is on. The first line of the file is line number 1. These numbers
1902: can be used as arguments to @kbd{M-x goto-line}. By contrast, @kbd{M-x
1903: what-page} counts pages from the beginning of the file, and counts lines
1904: within the page, printing both of them. @xref{Pages}.
1905:
1906: @kindex M-=
1907: @findex count-lines-region
1908: While on this subject, we might as well mention @kbd{M-=} (@code{count-lines-region}),
1909: which prints the number of lines in the region (@pxref{Mark}).
1910: @xref{Pages}, for the command @kbd{C-x l} which counts the lines in the
1911: current page.
1912:
1913: @kindex C-x =
1914: @findex what-cursor-position
1915: The command @kbd{C-x =} (@code{what-cursor-position}) can be used to find out
1916: the column that the cursor is in, and other miscellaneous information about
1917: point. It prints a line in the echo area that looks like this:
1918:
1919: @example
1920: Char: x (0170) point=65986 of 563027(12%) x=44
1921: @end example
1922:
1923: @noindent
1924: (In fact, this is the output produced when point is before the @samp{x=44}
1925: in the example.)
1926:
1927: The two values after @samp{Char:} describe the character following point,
1928: first by showing it and second by giving its octal character code.
1929:
1930: @samp{point=} is followed by the position of point expressed as a character
1931: count. The front of the buffer counts as position 1, one character later
1932: as 2, and so on. The next, larger number is the total number of characters
1933: in the buffer. Afterward in parentheses comes the position expressed as a
1934: percentage of the total size.
1935:
1936: @samp{x=} is followed by the horizontal position of point, in columns from the
1937: left edge of the window.
1938:
1939: If the buffer has been narrowed, making some of the text at the beginning and
1940: the end temporarily invisible, @kbd{C-x =} prints additional text describing the
1941: current visible range. For example, it might say
1942:
1943: @smallexample
1944: Char: x (0170) point=65986 of 563025(12%) <65102 - 68533> x=44
1945: @end smallexample
1946:
1947: @noindent
1948: where the two extra numbers give the smallest and largest character position
1949: that point is allowed to assume. The characters between those two positions
1950: are the visible ones. @xref{Narrowing}.
1951:
1952: If point is at the end of the buffer (or the end of the visible part),
1953: @kbd{C-x =} omits any description of the character after point.
1954: The output looks like
1955:
1956: @smallexample
1957: point=563026 of 563025(100%) x=0
1958: @end smallexample
1959:
1960: @node Arguments,, Position Info, Basic
1961: @section Numeric Arguments
1962: @cindex numeric arguments
1963: @cindex prefix arguments
1964: @cindex arguments, prefix and numeric
1965:
1966: Any Emacs command can be given a @dfn{numeric argument}. Some commands
1967: interpret the argument as a repetition count. For example, giving an
1968: argument of ten to the key @kbd{C-f} (the command @code{forward-char}, move
1969: forward one character) moves forward ten characters. With these commands,
1970: no argument is equivalent to an argument of one. Negative arguments are
1971: allowed. Often they tell a command to move or act backwards.
1972:
1973: @kindex M-1
1974: @kindex M-@t{-}
1975: @findex digit-argument
1976: @findex negative-argument
1977: If your terminal keyboard has a @key{META} key, the easiest way to
1978: specify a numeric argument is to type digits and/or a minus sign while
1979: holding down the @key{META} key. For example,
1980: @example
1981: M-5 C-n
1982: @end example
1983: @noindent
1984: would move down five lines. The characters @kbd{Meta-1}, @kbd{Meta-2}, and
1985: so on, as well as @kbd{Meta--}, do this because they are keys bound to
1986: commands (@code{digit-argument} and @code{negative-argument}) that are
1987: defined to contribute to an argument for the next command.
1988:
1989: @kindex C-u
1990: @findex universal-argument
1991: @cindex universal argument
1992: Another way of specifying an argument is to use the @kbd{C-u}
1993: (@code{universal-argument}) command followed by the digits of the argument.
1994: With @kbd{C-u}, you can type the argument digits without holding
1995: down shift keys. To type a negative argument, start with a minus sign.
1996: Just a minus sign normally means @minus{}1. @kbd{C-u} works on all terminals.
1997:
1998: @kbd{C-u} followed by a character which is neither a digit nor a minus
1999: sign has the special meaning of ``multiply by four''. It multiplies the
2000: argument for the next command by four. @kbd{C-u} twice multiplies it by
2001: sixteen. Thus, @kbd{C-u C-u C-f} moves forward sixteen characters. This
2002: is a good way to move forward ``fast'', since it moves about 1/5 of a line
2003: in the usual size screen. Other useful combinations are @kbd{C-u C-n},
2004: @kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u C-u
2005: C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four
2006: lines).@refill
2007:
2008: Some commands care only about whether there is an argument, and not about
2009: its value. For example, the command @kbd{M-q} (@code{fill-paragraph}) with
2010: no argument fills text; with an argument, it justifies the text as well.
2011: (@xref{Filling}, for more information on @kbd{M-q}.) Just @kbd{C-u} is a
2012: handy way of providing an argument for such commands.
2013:
2014: Some commands use the value of the argument as a repeat count, but do
2015: something peculiar when there is no argument. For example, the command
2016: @kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines,
2017: including their terminating newlines. But @kbd{C-k} with no argument is
2018: special: it kills the text up to the next newline, or, if point is right at
2019: the end of the line, it kills the newline itself. Thus, two @kbd{C-k}
2020: commands with no arguments can kill a nonblank line, just like @kbd{C-k}
2021: with an argument of one. (@xref{Killing}, for more information on
2022: @kbd{C-k}.)@refill
2023:
2024: A few commands treat a plain @kbd{C-u} differently from an ordinary
2025: argument. A few others may treat an argument of just a minus sign
2026: differently from an argument of @minus{}1. These unusual cases will be
2027: described when they come up; they are always for reasons of convenience
2028: of use of the individual command.
2029:
2030: To insert multiple copies of a digit, you can type @kbd{C-u
2031: @var{count} C-u @var{digit}}. The second @kbd{C-u} ends the numeric
2032: argument, so that the following character always acts a key sequence
2033: to be executed.
2034:
2035: @c section Autoarg Mode
2036: @ignore
2037: @cindex Autoarg mode
2038: Users of @sc{ascii} keyboards may prefer to use Autoarg mode. Autoarg mode
2039: means that you don't need to type C-U to specify a numeric argument.
2040: Instead, you type just the digits. Digits followed by an ordinary
2041: inserting character are themselves inserted, but digits followed by an
2042: Escape or Control character serve as an argument to it and are not
2043: inserted. A minus sign can also be part of an argument, but only at the
2044: beginning. If you type a minus sign following some digits, both the digits
2045: and the minus sign are inserted.
2046:
2047: To use Autoarg mode, set the variable @code{autoarg-mode} nonzero.
2048: @xref{Variables}.
2049:
2050: Autoargument digits echo at the bottom of the screen; the first nondigit
2051: causes them to be inserted or uses them as an argument. To insert some
2052: digits and nothing else, you must follow them with a Space and then rub it
2053: out. C-G cancels the digits, while Delete inserts them all and then rubs
2054: out the last.
2055: @end ignore
2056:
2057: @node Undo, Minibuffer, Basic, Top
2058: @chapter Undoing Changes
2059: @cindex undo
2060: @cindex mistakes, correcting
2061:
2062: Emacs allows all changes made in the text of a buffer to be undone,
2063: up to a certain amount of change (8000 characters). Each buffer records
2064: changes individually, and the undo command always applies to the
2065: current buffer. Usually each editing command makes a separate entry
2066: in the undo records, but some commands such as @code{query-replace}
2067: make many entries, and very simple commands such as self-inserting
2068: characters are often grouped to make undoing less tedious.
2069:
2070: @table @kbd
2071: @item C-x u
2072: Undo one batch of changes (usually, one command worth) (@code{undo}).
2073: @item C-_
2074: The same.
2075: @end table
2076:
2077: @kindex C-x u
2078: @kindex C-_
2079: @findex undo
2080: The command @kbd{C-x u} or @kbd{C-_} is how you undo. The first time you give
2081: this command, it undoes the last change. Point moves to the text
2082: affected by the undo, so you can see what was undone.
2083:
2084: Consecutive repetitions of the @kbd{C-_} or @kbd{C-x u} commands undo earlier
2085: and earlier changes, back to the limit of what has been recorded. If all
2086: recorded changes have already been undone, the undo command prints an error
2087: message and does nothing.
2088:
2089: Any command other than an undo command breaks the sequence of undo
2090: commands. Starting at this moment, the previous undo commands are
2091: considered ordinary changes that can themselves be undone. Thus, to
2092: redo changes you have undone, type @kbd{C-f} or any other command that
2093: will have no important effect, and then give more undo commands.
2094:
2095: If you notice that a buffer has been modified accidentally, the easiest
2096: way to recover is to type @kbd{C-_} repeatedly until the stars disappear
2097: from the front of the mode line. At this time, all the modifications you
2098: made have been cancelled. If you do not remember whether you changed the
2099: buffer deliberately, type @kbd{C-_} once, and when you see the last change
2100: you made undone, you will remember why you made it. If it was an accident,
2101: leave it undone. If it was deliberate, redo the change as described in the
2102: preceding paragraph.
2103:
2104: Whenever an undo command makes the stars disappear from the mode line,
2105: it means that the buffer contents are the same as they were when the
2106: file was last read in or saved.
2107:
2108: @findex buffer-enable-undo
2109: Not all buffers record undo information. Buffers whose names start with
2110: spaces don't; these buffers are used internally by Emacs and its extensions
2111: to hold text that users don't normally look at or edit. Also, minibuffers,
2112: help buffers and documentation buffers don't record undo information.
2113: Use the command @code{buffer-enable-undo} to enable recording undo information
2114: in the current buffer.
2115:
2116: As editing continues, undo lists get longer and longer. To prevent
2117: them from using up all available memory space, garbage collection trims
2118: back their sizes to thresholds you can set. (For this purpose, the
2119: ``size'' of an undo list measures the cons cells that make up the list,
2120: plus the strings of deleted text.)
2121:
2122: @vindex undo-limit
2123: @vindex undo-strong-limit
2124: Two variables control the range of acceptable sizes: @code{undo-limit}
2125: and @code{undo-strong-limit}. Normally, the most recent changes are
2126: kept until their size exceeds @code{undo-limit}; all older changes are
2127: discarded. But if a change pushes the size above
2128: @code{undo-strong-limit}, it is discarded as well as all older changes.
2129: One exception: the most recent set of changes is sacred; garbage
2130: collection never discards that. (In Emacs versions 18.57 and 18.58,
2131: these variables are called @code{undo-threshold} and
2132: @code{undo-high-threshold}.)
2133:
2134: The reason the @code{undo} command has two keys, @kbd{C-x u} and
2135: @kbd{C-_}, set up to run it is that it is worthy of a single-character
2136: key, but the way to type @kbd{C-_} on some keyboards is not obvious.
2137: @kbd{C-x u} is an alternative you can type in the same fashion on any
2138: terminal.
2139:
2140: @node Minibuffer, M-x, Undo, Top
2141: @chapter The Minibuffer
2142: @cindex minibuffer
2143:
2144: The @dfn{minibuffer} is the facility used by Emacs commands to read
2145: arguments more complicated than a single number. Minibuffer arguments can
2146: be file names, buffer names, Lisp function names, Emacs command names, Lisp
2147: expressions, and many other things, depending on the command reading the
2148: argument. The usual Emacs editing commands can be used in the minibuffer
2149: to edit the argument.
2150:
2151: @cindex prompt
2152: When the minibuffer is in use, it appears in the echo area, and the
2153: terminal's cursor moves there. The beginning of the minibuffer line
2154: displays a @dfn{prompt} which says what kind of input you should supply and
2155: how it will be used. Often this prompt is derived from the name of the
2156: command that the argument is for. The prompt normally ends with a colon.
2157:
2158: @cindex default argument
2159: Sometimes a @dfn{default argument} appears in parentheses after the
2160: colon; it too is part of the prompt. The default will be used as the
2161: argument value if you enter an empty argument (e.g., just type @key{RET}).
2162: For example, commands that read buffer names always show a default, which
2163: is the name of the buffer that will be used if you type just @key{RET}.
2164:
2165: @kindex C-g
2166: The simplest way to give a minibuffer argument is to type the text you
2167: want, terminated by @key{RET} which exits the minibuffer. You can get out
2168: of the minibuffer, canceling the command that it was for, by typing
2169: @kbd{C-g}.
2170:
2171: Since the minibuffer uses the screen space of the echo area, it can
2172: conflict with other ways Emacs customarily uses the echo area. Here is how
2173: Emacs handles such conflicts:
2174:
2175: @itemize @bullet
2176: @item
2177: If a command gets an error while you are in the minibuffer, this does
2178: not cancel the minibuffer. However, the echo area is needed for the
2179: error message and therefore the minibuffer itself is hidden for a
2180: while. It comes back after a few seconds, or as soon as you type
2181: anything.
2182:
2183: @item
2184: If in the minibuffer you use a command whose purpose is to print a
2185: message in the echo area, such as @kbd{C-x =}, the message is printed
2186: normally, and the minibuffer is hidden for a while. It comes back
2187: after a few seconds, or as soon as you type anything.
2188:
2189: @item
2190: Echoing of keystrokes does not take place while the minibuffer is in
2191: use.
2192: @end itemize
2193:
2194: @menu
2195: * File: Minibuffer File. Entering file names with the minibuffer.
2196: * Edit: Minibuffer Edit. How to edit in the minibuffer.
2197: * Completion:: An abbreviation facility for minibuffer input.
2198: * Repetition:: Re-executing commands that used the minibuffer.
2199: @end menu
2200:
2201: @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer
2202: @section Minibuffers for File Names
2203:
2204: Sometimes the minibuffer starts out with text in it. For example, when
2205: you are supposed to give a file name, the minibuffer starts out containing
2206: the @dfn{default directory}, which ends with a slash. This is to inform
2207: you which directory the file will be found in if you do not specify a
2208: directory. For example, the minibuffer might start out with
2209:
2210: @example
2211: Find File: /u2/emacs/src/
2212: @end example
2213:
2214: @noindent
2215: where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c} specifies
2216: the file @file{/u2/emacs/src/buffer.c}. To find files in nearby
2217: directories, use @kbd{..}; thus, if you type @kbd{../lisp/simple.el}, the
2218: file that you visit will be the one named @file{/u2/emacs/lisp/simple.el}.
2219: Alternatively, you can kill with @kbd{M-@key{DEL}} the directory names you
2220: don't want (@pxref{Words}).@refill
2221:
2222: You can also type an absolute file name, one starting with a slash or a
2223: tilde, ignoring the default directory. For example, to find the file
2224: @file{/etc/termcap}, just type the name, giving
2225:
2226: @example
2227: Find File: /u2/emacs/src//etc/termcap
2228: @end example
2229:
2230: @noindent
2231: Two slashes in a row are not normally meaningful in Unix file names, but
2232: they are allowed in GNU Emacs. They mean, ``ignore everything before the
2233: second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored, and
2234: you get the file @file{/etc/termcap}.
2235:
2236: @vindex insert-default-directory
2237: If you set @code{insert-default-directory} to @code{nil}, the default directory
2238: is not inserted in the minibuffer. This way, the minibuffer starts out
2239: empty. But the name you type, if relative, is still interpreted with
2240: respect to the same default directory.
2241:
2242: @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer
2243: @section Editing in the Minibuffer
2244:
2245: The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual
2246: Emacs commands are available for editing the text of an argument you are
2247: entering.
2248:
2249: Since @key{RET} in the minibuffer is defined to exit the minibuffer,
2250: inserting a newline into the minibuffer must be done with @kbd{C-o} or with
2251: @kbd{C-q @key{LFD}}. (Recall that a newline is really the @key{LFD}
2252: character.)
2253:
2254: The minibuffer has its own window which always has space on the screen
2255: but acts as if it were not there when the minibuffer is not in use. When
2256: the minibuffer is in use, its window is just like the others; you can
2257: switch to another window with @kbd{C-x o}, edit text in other windows and
2258: perhaps even visit more files, before returning to the minibuffer to submit
2259: the argument. You can kill text in another window, return to the
2260: minibuffer window, and then yank the text to use it in the argument.
2261: @xref{Windows}.
2262:
2263: There are some restrictions on the use of the minibuffer window, however.
2264: You cannot switch buffers in it---the minibuffer and its window are
2265: permanently attached. Also, you cannot split or kill the minibuffer
2266: window. But you can make it taller in the normal fashion with
2267: @kbd{C-x ^} (@pxref{Change Window}).
2268:
2269: @kindex C-M-v
2270: If while in the minibuffer you issue a command that displays help text
2271: of any sort in another window, then that window is identified as the
2272: one to scroll if you type @kbd{C-M-v} while in the minibuffer. This
2273: lasts until you exit the minibuffer. This feature comes into play
2274: if a completing minibuffer gives you a list of possible completions.
2275:
2276: @cindex recursive minibuffer
2277: Recursive use of the minibuffer is supported by Emacs. However, it is
2278: easy to do this by accident (because of autorepeating keyboards, for
2279: example) and get confused. Therefore, most Emacs commands that use the
2280: minibuffer refuse to operate if the minibuffer window is selected. If the
2281: minibuffer is active but you have switched to a different window, recursive
2282: use of the minibuffer is allowed---if you know enough to try to do this,
2283: you probably will not get confused.
2284:
2285: @vindex enable-recursive-minibuffers
2286: If you set the variable @code{enable-recursive-minibuffers} to be
2287: non-@code{nil}, recursive use of the minibuffer is always allowed.
2288:
2289: @node Completion, Repetition, Minibuffer Edit, Minibuffer
2290: @section Completion
2291: @cindex completion
2292:
2293: When appropriate, the minibuffer provides a @dfn{completion} facility.
2294: This means that you type enough of the argument to determine the rest,
2295: based on Emacs's knowledge of which arguments make sense, and Emacs visibly
2296: fills in the rest, or as much as can be determined from the part you have
2297: typed.
2298:
2299: When completion is available, certain keys---@key{TAB}, @key{RET}, and @key{SPC}---are
2300: redefined to complete an abbreviation present in the minibuffer into a
2301: longer string that it stands for, by matching it against a set of
2302: @dfn{completion alternatives} provided by the command reading the argument.
2303: @kbd{?} is defined to display a list of possible completions of what you
2304: have inserted.
2305:
2306: For example, when the minibuffer is being used by @kbd{Meta-x} to read
2307: the name of a command, it is given a list of all available Emacs command
2308: names to complete against. The completion keys match the text in the
2309: minibuffer against all the command names, find any additional characters of
2310: the name that are implied by the ones already present in the minibuffer,
2311: and add those characters to the ones you have given.
2312:
2313: Case is normally significant in completion, because it is significant in
2314: most of the names that you can complete (buffer names, file names and
2315: command names). Thus, @samp{fo} will not complete to @samp{Foo}. When you
2316: are completing a name in which case does not matter, case may be ignored
2317: for completion's sake if the program said to do so.
2318:
2319: @subsection Completion Example
2320:
2321: @kindex TAB
2322: @findex minibuffer-complete
2323: A concrete example may help here. If you type @kbd{Meta-x au @key{TAB}},
2324: the @key{TAB} looks for alternatives (in this case, command names) that
2325: start with @samp{au}. There are only two: @code{auto-fill-mode} and
2326: @code{auto-save-mode}. These are the same as far as @code{auto-}, so the
2327: @samp{au} in the minibuffer changes to @samp{auto-}.@refill
2328:
2329: If you type @key{TAB} again immediately, there are multiple possibilities
2330: for the very next character---it could be @samp{s} or @samp{f}---so no more
2331: characters are added; but a list of all possible completions is displayed
2332: in another window.
2333:
2334: If you go on to type @kbd{f @key{TAB}}, this @key{TAB} sees
2335: @samp{auto-f}. The only command name starting this way is
2336: @code{auto-fill-mode}, so completion inserts the rest of that. You
2337: now have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au
2338: @key{TAB} f @key{TAB}}. Note that @key{TAB} has this effect because in the
2339: minibuffer it is bound to the function @code{minibuffer-complete} when
2340: completion is supposed to be done.@refill
2341:
2342: @subsection Completion Commands
2343:
2344: Here is a list of all the completion commands, defined in the minibuffer
2345: when completion is available.
2346:
2347: @table @kbd
2348: @item @key{TAB}
2349: @c !!! added @* to prevent overfull hbox
2350: Complete the text in the minibuffer as much as possible@*
2351: (@code{minibuffer-complete}).
2352: @item @key{SPC}
2353: Complete the text in the minibuffer but don't add or fill out more
2354: than one word (@code{minibuffer-complete-word}).
2355: @item @key{RET}
2356: Submit the text in the minibuffer as the argument, possibly completing
2357: first as described below (@code{minibuffer-complete-and-exit}).
2358: @item ?
2359: Print a list of all possible completions of the text in the minibuffer
2360: (@code{minibuffer-list-completions}).
2361: @end table
2362:
2363: @kindex SPC
2364: @findex minibuffer-complete-word
2365: @key{SPC} completes much like @key{TAB}, but never goes beyond the
2366: next hyphen or space. If you have @samp{auto-f} in the minibuffer and type
2367: @key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but it
2368: stops completing after @samp{fill-}. This gives @samp{auto-fill-}.
2369: Another @key{SPC} at this point completes all the way to
2370: @samp{auto-fill-mode}. @key{SPC} in the minibuffer runs the function
2371: @code{minibuffer-complete-word} when completion is available.@refill
2372:
2373: There are three different ways that @key{RET} can work in completing
2374: minibuffers, depending on how the argument will be used.
2375:
2376: @itemize @bullet
2377: @item
2378: @dfn{Strict} completion is used when it is meaningless to give any
2379: argument except one of the known alternatives. For example, when
2380: @kbd{C-x k} reads the name of a buffer to kill, it is meaningless to
2381: give anything but the name of an existing buffer. In strict
2382: completion, @key{RET} refuses to exit if the text in the minibuffer
2383: does not complete to an exact match.
2384:
2385: @item
2386: @dfn{Cautious} completion is similar to strict completion, except that
2387: @key{RET} exits only if the text was an exact match already, not
2388: needing completion. If the text is not an exact match, @key{RET} does
2389: not exit, but it does complete the text. If it completes to an exact
2390: match, a second @key{RET} will exit.
2391:
2392: Cautious completion is used for reading file names for files that must
2393: already exist.
2394:
2395: @item
2396: @dfn{Permissive} completion is used when any string whatever is
2397: meaningful, and the list of completion alternatives is just a guide.
2398: For example, when @kbd{C-x C-f} reads the name of a file to visit, any
2399: file name is allowed, in case you want to create a file. In
2400: permissive completion, @key{RET} takes the text in the minibuffer
2401: exactly as given, without completing it.
2402: @end itemize
2403:
2404: The completion commands display a list of all possible completions in a
2405: window whenever there is more than one possibility for the very next
2406: character. Also, typing @kbd{?} explicitly requests such a list. The
2407: list of completions counts as help text, so @kbd{C-M-v} typed in the
2408: minibuffer scrolls the list.
2409:
2410: @vindex completion-ignored-extensions
2411: When completion is done on file names, certain file names are usually
2412: ignored. The variable @code{completion-ignored-extensions} contains a list
2413: of strings; a file whose name ends in any of those strings is ignored as a
2414: possible completion. The standard value of this variable has several
2415: elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and @code{"~"}.
2416: The effect is that, for example, @samp{foo} can complete to @samp{foo.c}
2417: even though @samp{foo.o} exists as well. If the only possible completions
2418: are files that end in ``ignored'' strings, then they are not ignored.@refill
2419:
2420: @vindex completion-auto-help
2421: Normally, a completion command that finds the next character is undetermined
2422: automatically displays a list of all possible completions. If the variable
2423: @code{completion-auto-help} is set to @code{nil}, this does not happen,
2424: and you must type @kbd{?} to display the possible completions.
2425:
2426: @node Repetition,, Completion, Minibuffer
2427: @section Repeating Minibuffer Commands
2428: @cindex command history
2429: @cindex history of commands
2430:
2431: Every command that uses the minibuffer at least once is recorded on a
2432: special history list, together with the values of the minibuffer arguments,
2433: so that you can repeat the command easily. In particular, every
2434: use of @kbd{Meta-x} is recorded, since @kbd{M-x} uses the minibuffer to
2435: read the command name.
2436:
2437: @findex list-command-history
2438: @c widecommands
2439: @table @kbd
2440: @c !!! following generates acceptable underfull hbox
2441: @item C-x @key{ESC}
2442: Re-execute a recent minibuffer command @code{repeat-complex-command}).
2443: @item M-p
2444: @c !!! added @* to prevent overfull hbox
2445: Within @kbd{C-x @key{ESC}}, move to the previous recorded command@*
2446: (@code{previous-complex-command}).
2447: @item M-n
2448: Within @kbd{C-x @key{ESC}}, move to the next (more recent) recorded
2449: command (@code{next-complex-command}).
2450: @item M-x list-command-history
2451: Display the entire command history, showing all the commands
2452: @kbd{C-x @key{ESC}} can repeat, most recent first.
2453: @end table
2454:
2455: @kindex C-x ESC
2456: @findex repeat-complex-command
2457: @kbd{C-x @key{ESC}} is used to re-execute a recent minibuffer-using
2458: command. With no argument, it repeats the last such command. A numeric
2459: argument specifies which command to repeat; 1 means the last one, and
2460: larger numbers specify earlier ones.
2461:
2462: @kbd{C-x @key{ESC}} works by turning the previous command into a Lisp
2463: expression and then entering a minibuffer initialized with the text for
2464: that expression. If you type just @key{RET}, the command is repeated as
2465: before. You can also change the command by editing the Lisp expression.
2466: Whatever expression you finally submit is what will be executed. The
2467: repeated command is added to the front of the command history unless it is
2468: identical to the most recently executed command already there.
2469:
2470: Even if you don't understand Lisp syntax, it will probably be obvious
2471: which command is displayed for repetition. If you do not change the text,
2472: you can be sure it will repeat exactly as before.
2473:
2474: @kindex M-n
2475: @kindex M-p
2476: @findex next-complex-command
2477: @findex previous-complex-command
2478: Once inside the minibuffer for @kbd{C-x @key{ESC}}, if the command shown
2479: to you is not the one you want to repeat, you can move around the list of
2480: previous commands using @kbd{M-n} and @kbd{M-p}. @kbd{M-p} replaces the
2481: contents of the minibuffer with the next earlier recorded command, and
2482: @kbd{M-n} replaces them with the next later command. After finding the
2483: desired previous command, you can edit its expression as usual and then
2484: resubmit it by typing @key{RET} as usual. Any editing you have done on the
2485: command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}.
2486:
2487: @kbd{M-p} is more useful than @kbd{M-n}, since more often you will
2488: initially request to repeat the most recent command and then decide to
2489: repeat an older one instead. These keys are specially defined within
2490: @kbd{C-x @key{ESC}} to run the commands @code{previous-complex-command} and
2491: @code{next-complex-command}.
2492:
2493: @vindex command-history
2494: The list of previous minibuffer-using commands is stored as a Lisp list
2495: in the variable @code{command-history}. Each element is a Lisp expression
2496: which describes one command and its arguments. Lisp programs can reexecute
2497: a command by feeding the corresponding @code{command-history} element to
2498: @code{eval}.
2499:
2500: @node M-x, Help, Minibuffer, Top
2501: @chapter Running Commands by Name
2502:
2503: The Emacs commands that are used often or that must be quick to type are
2504: bound to keys---short sequences of characters---for convenient use. Other
2505: Emacs commands that do not need to be brief are not bound to keys; to run
2506: them, you must refer to them by name.
2507:
2508: A command name is, by convention, made up of one or more words, separated
2509: by hyphens; for example, @code{auto-fill-mode} or @code{manual-entry}. The
2510: use of English words makes the command name easier to remember than a key
2511: made up of obscure characters, even though it is more characters to type.
2512: Any command can be run by name, even if it is also runnable by keys.
2513:
2514: @kindex M-x
2515: @cindex minibuffer
2516: The way to run a command by name is to start with @kbd{M-x}, type the
2517: command name, and finish it with @key{RET}. @kbd{M-x} uses the minibuffer
2518: to read the command name. @key{RET} exits the minibuffer and runs the
2519: command.
2520:
2521: Emacs uses the minibuffer for reading input for many different purposes;
2522: on this occasion, the string @samp{M-x} is displayed at the beginning of
2523: the minibuffer as a @dfn{prompt} to remind you that your input should be
2524: the name of a command to be run. @xref{Minibuffer}, for full information
2525: on the features of the minibuffer.
2526:
2527: You can use completion to enter the command name. For example, the
2528: command @code{forward-char} can be invoked by name by typing
2529:
2530: @example
2531: M-x forward-char @key{RET}
2532:
2533: @exdent or
2534:
2535: M-x fo @key{TAB} c @key{RET}
2536: @end example
2537:
2538: @noindent
2539: Note that @code{forward-char} is the same command that you invoke with
2540: the key @kbd{C-f}. Any command (interactively callable function) defined
2541: in Emacs can be called by its name using @kbd{M-x} whether or not any
2542: keys are bound to it.
2543:
2544: If you type @kbd{C-g} while the command name is being read, you cancel
2545: the @kbd{M-x} command and get out of the minibuffer, ending up at top level.
2546:
2547: To pass a numeric argument to the command you are invoking with
2548: @kbd{M-x}, specify the numeric argument before the @kbd{M-x}. @kbd{M-x}
2549: passes the argument along to the function which it calls. The argument
2550: value appears in the prompt while the command name is being read.
2551:
2552: Normally, when describing a command that is run by name, we omit the
2553: @key{RET} that is needed to terminate the name. Thus we might speak of
2554: @kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode @key{RET}}.
2555: We mention the @key{RET} only when there is a need to emphasize its
2556: presence, such as when describing a sequence of input that contains a
2557: command name and arguments that follow it.
2558:
2559: @findex execute-extended-command
2560: @kbd{M-x} is defined to run the command @code{execute-extended-command},
2561: which is responsible for reading the name of another command and invoking
2562: it.
2563:
2564: @node Help, Mark, M-x, Top
2565: @chapter Help
2566: @kindex Help
2567: @cindex help
2568: @cindex self-documentation
2569:
2570: Emacs provides extensive help features which revolve around a single
2571: character, @kbd{C-h}. @kbd{C-h} is a prefix key that is used only for
2572: documentation-printing commands. The characters that you can type after
2573: @kbd{C-h} are called @dfn{help options}. One help option is @kbd{C-h};
2574: that is how you ask for help about using @kbd{C-h}.
2575:
2576: @kbd{C-h C-h} prints a list of the possible help options, and then asks
2577: you to go ahead and type the option. It prompts with a string
2578:
2579: @smallexample
2580: A B C F I K L M N S T V W C-c C-d C-n C-w. Type C-h again for more help:
2581: @end smallexample
2582:
2583: @noindent
2584: and you should type one of those characters.
2585:
2586: Typing a third @kbd{C-h} displays a description of what the options mean;
2587: it still waits for you to type an option. To cancel, type @kbd{C-g}.
2588:
2589: Here is a summary of the defined help commands.
2590:
2591: @table @kbd
2592: @item C-h a @var{string} @key{RET}
2593: @c !!! added @* to prevent overfull hbox
2594: Display a list of commands whose names contain @var{string}@*
2595: (@code{command-apropos}).
2596: @item C-h b
2597: Display a table of all key bindings in effect now; local bindings of
2598: the current major mode first, followed by all global bindings
2599: (@code{describe-bindings}).
2600: @item C-h c @var{key}
2601: Print the name of the command that @var{key} runs (@code{describe-key-briefly}).
2602: @kbd{c} is for `character'. For more extensive information on @var{key},
2603: use @kbd{C-h k}.
2604: @item C-h f @var{function} @key{RET}
2605: Display documentation on the Lisp function named @var{function}
2606: (@code{describe-function}). Note that commands are Lisp functions, so
2607: a command name may be used.
2608: @item C-h i
2609: Run Info, the program for browsing documentation files (@code{info}).
2610: The complete Emacs manual is available on-line in Info.
2611: @item C-h k @var{key}
2612: Display name and documentation of the command @var{key} runs (@code{describe-key}).
2613: @item C-h l
2614: Display a description of the last 100 characters you typed
2615: (@code{view-lossage}).
2616: @item C-h m
2617: Display documentation of the current major mode (@code{describe-mode}).
2618: @item C-h n
2619: Display documentation of Emacs changes, most recent first
2620: (@code{view-emacs-news}).
2621: @item C-h s
2622: Display current contents of the syntax table, plus an explanation of
2623: what they mean (@code{describe-syntax}).
2624: @item C-h t
2625: Display the Emacs tutorial (@code{help-with-tutorial}).
2626: @item C-h v @var{var} @key{RET}
2627: Display the documentation of the Lisp variable @var{var}
2628: (@code{describe-variable}).
2629: @item C-h w @var{command} @key{RET}
2630: Print which keys run the command named @var{command} (@code{where-is}).
2631: @end table
2632:
2633: @section Documentation for a Key
2634:
2635: @kindex C-h c
2636: @findex describe-key-briefly
2637: The most basic @kbd{C-h} options are @kbd{C-h c}
2638: (@code{describe-key-briefly}) and @w{@kbd{C-h k}} (@code{describe-key}).
2639: @kbd{C-h c @var{key}} prints in the echo area the name of the command that
2640: @var{key} is bound to. For example, @kbd{C-h c C-f} prints
2641: @samp{forward-char}. Since command names are chosen to describe what the
2642: command does, this is a good way to get a very brief description of what
2643: @var{key} does.@refill
2644:
2645: @kindex C-h k
2646: @findex describe-key
2647: @kbd{C-h k @var{key}} is similar but gives more information. It displays
2648: the documentation string of the command @var{key} is bound to as well as
2649: its name. This is too big for the echo area, so a window is used for the
2650: display.
2651:
2652: @section Help by Command or Variable Name
2653:
2654: @kindex C-h f
2655: @findex describe-function
2656: @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function
2657: using the minibuffer, then displays that function's documentation string
2658: in a window. Since commands are Lisp functions, you can use this to get
2659: the documentation of a command that is known by name. For example,
2660:
2661: @example
2662: C-h f auto-fill-mode @key{RET}
2663: @end example
2664:
2665: @noindent
2666: displays the documentation of @code{auto-fill-mode}. This is the only
2667: way to see the documentation of a command that is not bound to any key
2668: (one which you would normally call using @kbd{M-x}).
2669:
2670: @kbd{C-h f} is also useful for Lisp functions that you are planning to
2671: use in a Lisp program. For example, if you have just written the code
2672: @code{(make-vector len)} and want to be sure that you are using
2673: @code{make-vector} properly, type
2674: @w{@kbd{C-h f make-vector @key{RET}}}. Because @kbd{C-h f} allows
2675: all function names, not just command names, you may find that some of
2676: your favorite abbreviations that work in @kbd{M-x} don't work in
2677: @kbd{C-h f}. An abbreviation may be unique among command names yet
2678: fail to be unique when other function names are allowed.
2679:
2680: The function name for @kbd{C-h f} to describe has a default which is
2681: used if you type @key{RET} leaving the minibuffer empty. The default is
2682: the function called by the innermost Lisp expression in the buffer around
2683: point, @i{provided} that is a valid, defined Lisp function name. For
2684: example, if point is located following the text @samp{(make-vector (car
2685: x)}, the innermost list containing point is the one that starts with
2686: @samp{(make-vector}, so the default is to describe the function
2687: @code{make-vector}.
2688:
2689: @kbd{C-h f} is often useful just to verify that you have the right
2690: spelling for the function name. If @kbd{C-h f} mentions a default in the
2691: prompt, you have typed the name of a defined Lisp function. If that tells
2692: you what you want to know, just type @kbd{C-g} to cancel the @kbd{C-h f}
2693: command and go on editing.
2694:
2695: @kindex C-h w
2696: @findex where-is
2697: @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
2698: @var{command}. It prints a list of the keys in the echo area.
2699: Alternatively, it says that the command is not on any keys, which implies
2700: that you must use @kbd{M-x} to call it.@refill
2701:
2702: @kindex C-h v
2703: @findex describe-variable
2704: @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes
2705: Lisp variables instead of Lisp functions. Its default is the Lisp symbol
2706: around or before point, but only if that is the name of a known Lisp
2707: variable. @xref{Variables}.@refill
2708:
2709: @section Apropos
2710:
2711: @kindex C-h a
2712: @findex command-apropos
2713: @cindex apropos
2714: A more sophisticated sort of question to ask is, ``What are the commands
2715: for working with files?'' For this, type @kbd{C-h a file @key{RET}}, which
2716: displays a list of all command names that contain @samp{file}, such as
2717: @code{copy-file}, @code{find-file}, and so on. With each command name
2718: appears a brief description of how to use the command, and what keys you
2719: can currently invoke it with. For example, it would say that you can
2720: invoke @code{find-file} by typing @kbd{C-x C-f}. The @kbd{a} in @kbd{C-h
2721: a} stands for `Apropos'; @kbd{C-h a} runs the Lisp function
2722: @code{command-apropos}.@refill
2723:
2724: Because @kbd{C-h a} looks only for functions whose names contain the
2725: string which you specify, you must use ingenuity in choosing the string.
2726: If you are looking for commands for killing backwards and @kbd{C-h a
2727: kill-backwards @key{RET}} doesn't reveal any, don't give up. Try just
2728: @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}. Be persistent.
2729: Pretend you are playing Adventure. Also note that you can use a
2730: regular expression as the argument (@pxref{Regexps}).
2731:
2732: Here is a set of arguments to give to @kbd{C-h a} that covers many
2733: classes of Emacs commands, since there are strong conventions for naming
2734: the standard Emacs commands. By giving you a feel for the naming
2735: conventions, this set should also serve to aid you in developing a
2736: technique for picking @code{apropos} strings.
2737:
2738: @quotation
2739: char, line, word, sentence, paragraph, region, page, sexp, list, defun,
2740: buffer, screen, window, file, dir, register, mode,
2741: beginning, end, forward, backward, next, previous, up, down, search, goto,
2742: kill, delete, mark, insert, yank, fill, indent, case,
2743: change, set, what, list, find, view, describe.
2744: @end quotation
2745:
2746: @findex apropos
2747: To list all Lisp symbols that contain a match for a regexp, not just
2748: the ones that are defined as commands, use the command @kbd{M-x apropos}
2749: instead of @kbd{C-h a}.
2750:
2751: @section Other Help Commands
2752:
2753: @kindex C-h i
2754: @findex info
2755: @kbd{C-h i} (@code{info}) runs the Info program, which is used for
2756: browsing through structured documentation files. The entire Emacs manual
2757: is available within Info. Eventually all the documentation of the GNU
2758: system will be available. Type @kbd{h} after entering Info to run
2759: a tutorial on using Info.
2760:
2761: @kindex C-h l
2762: @findex view-lossage
2763: If something surprising happens, and you are not sure what commands you
2764: typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} prints the last
2765: 100 command characters you typed in. If you see commands that you don't
2766: know, you can use @kbd{C-h c} to find out what they do.
2767:
2768: @kindex C-h m
2769: @findex describe-mode
2770: Emacs has several major modes, each of which redefines a few keys and
2771: makes a few other changes in how editing works. @kbd{C-h m} (@code{describe-mode})
2772: prints documentation on the current major mode, which normally describes
2773: all the commands that are changed in this mode.
2774:
2775: @kindex C-h b
2776: @findex describe-bindings
2777: @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
2778: (@code{describe-syntax}) present other information about the current
2779: Emacs mode. @kbd{C-h b} displays a list of all the key bindings now
2780: in effect; the local bindings of the current major mode first,
2781: followed by the global bindings (@pxref{Key Bindings}). @kbd{C-h s}
2782: displays the contents of the syntax table, with explanations of each
2783: character's syntax (@pxref{Syntax}).@refill
2784:
2785: @kindex C-h n
2786: @findex view-emacs-news
2787: @kindex C-h t
2788: @findex help-with-tutorial
2789: @kindex C-h C-c
2790: @findex describe-copying
2791: @kindex C-h C-d
2792: @findex describe-distribution
2793: @kindex C-h C-w
2794: @findex describe-no-warranty
2795: The other @kbd{C-h} options display various files of useful
2796: information. @w{@kbd{C-h C-w}} displays the full details on the complete
2797: absence of warranty for GNU Emacs. @kbd{C-h n} (@code{view-emacs-news})
2798: displays the file @file{emacs/etc/NEWS}, which contains documentation on
2799: Emacs changes arranged chronologically. @kbd{C-h t}
2800: (@code{help-with-tutorial}) displays the learn-by-doing Emacs tutorial.
2801: @kbd{C-h C-c} (@code{describe-copying}) displays the file
2802: @file{emacs/etc/COPYING}, which tells you the conditions you must obey
2803: in distributing copies of Emacs. @kbd{C-h C-d}
2804: (@code{describe-distribution}) displays another file named
2805: @file{emacs/etc/DISTRIB}, which tells you how you can order a copy of
2806: the latest version of Emacs.
2807:
2808: @node Mark, Killing, Help, Top
2809: @chapter The Mark and the Region
2810: @cindex mark
2811: @cindex region
2812:
2813: There are many Emacs commands which operate on an arbitrary contiguous
2814: part of the current buffer. To specify the text for such a command to
2815: operate on, you set the @dfn{mark} at one end of it, and move point to the
2816: other end. The text between point and the mark is called the @dfn{region}.
2817: You can move point or the mark to adjust the boundaries of the region. It
2818: doesn't matter which one is set first chronologically, or which one comes
2819: earlier in the text.
2820:
2821: Once the mark has been set, it remains until it is set again at another
2822: place. The mark remains fixed with respect to the preceding character if
2823: text is inserted or deleted in the buffer. Each Emacs buffer has its own
2824: mark, so that when you return to a buffer that had been selected
2825: previously, it has the same mark it had before.
2826:
2827: Many commands that insert text, such as @kbd{C-y} (@code{yank}) and
2828: @kbd{M-x insert-buffer}, position the mark at one end of the inserted
2829: text---the opposite end from where point is positioned, so that the region
2830: contains the text just inserted.
2831:
2832: Aside from delimiting the region, the mark is also useful for remembering
2833: a spot that you may want to go back to. To make this feature more useful,
2834: Emacs remembers 16 previous locations of the mark, in the @code{mark ring}.
2835:
2836: @menu
2837: * Setting Mark:: Commands to set the mark.
2838: * Using Region:: Summary of ways to operate on contents of the region.
2839: * Marking Objects:: Commands to put region around textual units.
2840: * Mark Ring:: Previous mark positions saved so you can go back there.
2841: @end menu
2842:
2843: @node Setting Mark, Using Region, Mark, Mark
2844: @section Setting the Mark
2845:
2846: Here are some commands for setting the mark:
2847:
2848: @c WideCommands
2849: @table @kbd
2850: @item C-@key{SPC}
2851: Set the mark where point is (@code{set-mark-command}).
2852: @item C-@@
2853: The same.
2854: @item C-x C-x
2855: Interchange mark and point (@code{exchange-point-and-mark}).
2856: @end table
2857:
2858: For example, if you wish to convert part of the buffer to all upper-case,
2859: you can use the @kbd{C-x C-u} (@code{upcase-region}) command, which operates
2860: on the text in the region. You can first go to the beginning of the text
2861: to be capitalized, type @kbd{C-@key{SPC}} to put the mark there, move to
2862: the end, and then type @kbd{C-x C-u}. Or, you can set the mark at the end
2863: of the text, move to the beginning, and then type @kbd{C-x C-u}. Most
2864: commands that operate on the text in the region have the word @code{region}
2865: in their names.
2866:
2867: @kindex C-SPC
2868: @findex set-mark-command
2869: The most common way to set the mark is with the @kbd{C-@key{SPC}} command
2870: (@code{set-mark-command}). This sets the mark where point is. Then you
2871: can move point away, leaving the mark behind. It is actually incorrect to
2872: speak of the character @kbd{C-@key{SPC}}; there is no such character. When
2873: you type @key{SPC} while holding down @key{CTRL}, what you get on most
2874: terminals is the character @kbd{C-@@}. This is the key actually bound to
2875: @code{set-mark-command}. But unless you are unlucky enough to have a
2876: terminal where typing @kbd{C-@key{SPC}} does not produce @kbd{C-@@}, you
2877: might as well think of this character as @kbd{C-@key{SPC}}.
2878:
2879: @kindex C-x C-x
2880: @findex exchange-point-and-mark
2881: Since terminals have only one cursor, there is no way for Emacs to show
2882: you where the mark is located. You have to remember. The usual solution
2883: to this problem is to set the mark and then use it soon, before you forget
2884: where it is. But you can see where the mark is with the command @w{@kbd{C-x
2885: C-x}} (@code{exchange-point-and-mark}) which puts the mark where point was and
2886: point where the mark was. The extent of the region is unchanged, but the
2887: cursor and point are now at the previous location of the mark.
2888:
2889: @kbd{C-x C-x} is also useful when you are satisfied with the location of
2890: point but want to move the mark; do @kbd{C-x C-x} to put point there and
2891: then you can move it. A second use of @kbd{C-x C-x}, if necessary, puts
2892: the mark at the new location with point back at its original location.
2893:
2894: @node Using Region, Marking Objects, Setting Mark, Mark
2895: @section Operating on the Region
2896:
2897: Once you have created an active region, you can do many things to
2898: the text in it:
2899: @itemize @bullet
2900: @item
2901: Kill it with @kbd{C-w} (@pxref{Killing}).
2902: @item
2903: Save it in a register with @kbd{C-x x} (@pxref{Registers}).
2904: @item
2905: Save it in a buffer or a file (@pxref{Accumulating Text}).
2906: @item
2907: @c !!! added @* to prevent overfull hbox
2908: Convert case with @kbd{C-x C-l} or @kbd{C-x C-u}@*
2909: (@pxref{Case}).
2910: @item
2911: Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
2912: @item
2913: Fill it as text with @kbd{M-g} (@pxref{Filling}).
2914: @item
2915: Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}).
2916: @item
2917: @c !!! added @* to prevent overfull hbox
2918: Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\}@*
2919: (@pxref{Indentation}).
2920: @end itemize
2921:
2922: @node Marking Objects, Mark Ring, Using Region, Mark
2923: @section Commands to Mark Textual Objects
2924:
2925: There are commands for placing point and the mark around a textual
2926: object such as a word, list, paragraph or page.
2927:
2928: @table @kbd
2929: @item M-@@
2930: Set mark after end of next word (@code{mark-word}). This command and
2931: the following one do not move point.
2932: @item C-M-@@
2933: Set mark after end of next Lisp expression (@code{mark-sexp}).
2934: @item M-h
2935: Put region around current paragraph (@code{mark-paragraph}).
2936: @item C-M-h
2937: Put region around current Lisp defun (@code{mark-defun}).
2938: @item C-x h
2939: Put region around entire buffer (@code{mark-whole-buffer}).
2940: @item C-x C-p
2941: Put region around current page (@code{mark-page}).
2942: @end table
2943:
2944: @kindex M-@@
2945: @kindex C-M-@@
2946: @findex mark-word
2947: @findex mark-sexp
2948: @kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next word,
2949: while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the next Lisp
2950: expression. These characters allow you to save a little typing or
2951: redisplay, sometimes.
2952:
2953: @kindex M-h
2954: @kindex C-M-h
2955: @kindex C-x C-p
2956: @kindex C-x h
2957: @findex mark-paragraph
2958: @findex mark-defun
2959: @findex mark-page
2960: @findex mark-whole-buffer
2961: Other commands set both point and mark, to delimit an object in the
2962: buffer. @kbd{M-h} (@code{mark-paragraph}) moves point to the beginning of
2963: the paragraph that surrounds or follows point, and puts the mark at the end
2964: of that paragraph (@pxref{Paragraphs}). @kbd{M-h} does all that's
2965: necessary if you wish to indent, case-convert, or kill a whole paragraph.
2966: @kbd{C-M-h} (@code{mark-defun}) similarly puts point before and the mark
2967: after the current or following defun (@pxref{Defuns}). @kbd{C-x C-p}
2968: (@code{mark-page}) puts point before the current page (or the next or
2969: previous, according to the argument), and mark at the end (@pxref{Pages}).
2970: The mark goes after the terminating page delimiter (to include it), while
2971: point goes after the preceding page delimiter (to exclude it). Finally,
2972: @w{@kbd{C-x h}} (@code{mark-whole-buffer}) sets up the entire buffer as the
2973: region, by putting point at the beginning and the mark at the end.
2974:
2975: @node Mark Ring,, Marking Objects, Mark
2976: @section The Mark Ring
2977:
2978: @kindex C-u C-SPC
2979: @cindex mark ring
2980: @kindex C-u C-@@
2981: Aside from delimiting the region, the mark is also useful for remembering
2982: a spot that you may want to go back to. To make this feature more useful,
2983: Emacs remembers 16 previous locations of the mark, in the @dfn{mark ring}.
2984: Most commands that set the mark push the old mark onto this ring. To
2985: return to a marked location, use @kbd{C-u C-@key{SPC}} (or @kbd{C-u C-@@}); this is
2986: the command @code{set-mark-command} given a numeric argument. It moves
2987: point to where the mark was, and restores the mark from the ring of former
2988: marks. So repeated use of this command moves point to all of the old marks
2989: on the ring, one by one. The marks you see go to the end of the ring,
2990: so no marks are lost.
2991:
2992: Each buffer has its own mark ring. All editing commands use the current
2993: buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} always stays in
2994: the same buffer.
2995:
2996: Many commands that can move long distances, such as @kbd{M-<}
2997: (@code{beginning-of-buffer}), start by setting the mark and saving the old
2998: mark on the mark ring. This is to make it easier for you to move back
2999: later. Searches do this except when they do not actually move point. You
3000: can tell when a command sets the mark because @samp{Mark Set} is printed in
3001: the echo area.
3002:
3003: Another way of remembering positions so you can go back to them is with
3004: registers (@pxref{RegPos}).
3005:
3006: @vindex mark-ring-max
3007: The variable @code{mark-ring-max} is the maximum number of entries to
3008: keep in the mark ring. If that many entries exist and another one is
3009: pushed, the last one in the list is discarded. Repeating @kbd{C-u
3010: C-@key{SPC}} circulates through the limited number of entries that are
3011: currently in the ring.
3012:
3013: @vindex mark-ring
3014: The variable @code{mark-ring} holds the mark ring itself, as a list of
3015: marker objects in the order most recent first. This variable is local
3016: in every buffer.
3017:
3018: @iftex
3019: @chapter Killing and Moving Text
3020:
3021: @dfn{Killing} means erasing text and copying it into the @dfn{kill ring},
3022: from which it can be retrieved by @dfn{yanking} it. Some other systems
3023: that have recently become popular use the terms ``cutting'' and ``pasting''
3024: for these operations.
3025:
3026: The commonest way of moving or copying text with Emacs is to kill it and
3027: later yank it in one or more places. This is very safe because all the
3028: text killed recently is remembered, and it is versatile, because the many
3029: commands for killing syntactic units can also be used for moving those
3030: units. There are also other ways of copying text for special purposes.
3031:
3032: Emacs has only one kill ring, so you can kill text in one buffer and yank
3033: it in another buffer.
3034:
3035: @end iftex
3036:
3037: @node Killing, Yanking, Mark, Top
3038: @section Deletion and Killing
3039: @findex delete-char
3040: @c ??? Should be backward-delete-char
3041: @findex delete-backward-char
3042:
3043: @cindex killing
3044: @cindex cutting
3045: @cindex clipping text
3046: @cindex deletion
3047: @kindex C-d
3048: @kindex DEL
3049: Most commands which erase text from the buffer save it so that you can
3050: get it back if you change your mind, or move or copy it to other parts of
3051: the buffer. These commands are known as @dfn{kill} commands. The rest of
3052: the commands that erase text do not save it; they are known as @dfn{delete}
3053: commands. (This distinction is made only for erasure of text in the
3054: buffer.)
3055:
3056: @c !!! following generates acceptable underfull hbox
3057: The delete commands include @kbd{C-d} (@code{delete-char}) and
3058: @key{DEL} (@code{delete-backward-char}), which delete only one character at
3059: a time, and those commands that delete only spaces or newlines. Commands
3060: that can destroy significant amounts of nontrivial data generally kill.
3061: The commands' names and individual descriptions use the words @samp{kill}
3062: and @samp{delete} to say which they do. If you do a kill or delete command
3063: by mistake, you can use the @w{@kbd{C-x u}} (@code{undo}) command to undo it
3064: (@pxref{Undo}).
3065:
3066: @subsection Deletion
3067:
3068: @table @kbd
3069: @item C-d
3070: Delete next character (@code{delete-char}).
3071: @item @key{DEL}
3072: Delete previous character (@code{delete-backward-char}).
3073: @item M-\
3074: Delete spaces and tabs around point (@code{delete-horizontal-space}).
3075: @item M-@key{SPC}
3076: Delete spaces and tabs around point, leaving one space
3077: (@code{just-one-space}).
3078: @item C-x C-o
3079: Delete blank lines around the current line (@code{delete-blank-lines}).
3080: @item M-^
3081: Join two lines by deleting the intervening newline, and any indentation
3082: following it (@code{delete-indentation}).
3083: @end table
3084:
3085: The most basic delete commands are @kbd{C-d} (@code{delete-char}) and
3086: @key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the character
3087: after point, the one the cursor is ``on top of''. Point doesn't move.
3088: @key{DEL} deletes the character before the cursor, and moves point back.
3089: Newlines can be deleted like any other characters in the buffer; deleting a
3090: newline joins two lines. Actually, @kbd{C-d} and @key{DEL} aren't always
3091: delete commands; if given an argument, they kill instead, since they can
3092: erase more than one character this way.
3093:
3094: @kindex M-\
3095: @findex delete-horizontal-space
3096: @kindex M-SPC
3097: @findex just-one-space
3098: @kindex C-x C-o
3099: @findex delete-blank-lines
3100: @kindex M-^
3101: @findex delete-indentation
3102: The other delete commands are those which delete only formatting
3103: characters: spaces, tabs and newlines. @kbd{M-\} (@code{delete-horizontal-space})
3104: deletes all the spaces and tab characters before and after point.
3105: @kbd{M-@key{SPC}} (@code{just-one-space}) does likewise but leaves a single
3106: space after point, regardless of the number of spaces that existed
3107: previously (even zero).
3108:
3109: @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines after
3110: the current line, and if the current line is blank deletes all blank lines
3111: preceding the current line as well (leaving one blank line, the current
3112: line). @kbd{M-^} (@code{delete-indentation}) joins the current line and
3113: the previous line, or the current line and the next line if given an
3114: argument, by deleting a newline and all surrounding spaces, possibly
3115: leaving a single space. @xref{Indentation,M-^}.
3116:
3117: @subsection Killing by Lines
3118:
3119: @table @kbd
3120: @item C-k
3121: Kill rest of line or one or more lines (@code{kill-line}).
3122: @end table
3123:
3124: @kindex C-k
3125: @findex kill-line
3126: The simplest kill command is @kbd{C-k}. If given at the beginning of a
3127: line, it kills all the text on the line, leaving it blank. If given on a
3128: blank line, the blank line disappears. As a consequence, if you go to the
3129: front of a non-blank line and type @kbd{C-k} twice, the line disappears
3130: completely.
3131:
3132: More generally, @kbd{C-k} kills from point up to the end of the line,
3133: unless it is at the end of a line. In that case it kills the newline
3134: following the line, thus merging the next line into the current one.
3135: Invisible spaces and tabs at the end of the line are ignored when deciding
3136: which case applies, so if point appears to be at the end of the line, you
3137: can be sure the newline will be killed.
3138:
3139: If @kbd{C-k} is given a positive argument, it kills that many lines and
3140: the newlines that follow them (however, text on the current line before
3141: point is spared). With a negative argument, it kills back to a number of
3142: line beginnings. An argument of @minus{}2 means kill back to the second line
3143: beginning. If point is at the beginning of a line, that line beginning
3144: doesn't count, so @w{@kbd{C-u - 2 C-k}} with point at the front of a line kills
3145: the two previous lines.
3146:
3147: @kbd{C-k} with an argument of zero kills all the text before point on the
3148: current line.
3149:
3150: @subsection Other Kill Commands
3151: @findex kill-line
3152: @findex kill-region
3153: @findex kill-word
3154: @findex backward-kill-word
3155: @findex kill-sexp
3156: @findex kill-sentence
3157: @findex backward-kill-sentence
3158: @kindex M-d
3159: @kindex M-DEL
3160: @kindex C-M-k
3161: @kindex C-x DEL
3162: @kindex M-k
3163: @kindex C-k
3164: @kindex C-w
3165:
3166: @c DoubleWideCommands
3167: @table @kbd
3168: @item C-w
3169: Kill region (from point to the mark) (@code{kill-region}).
3170: @xref{Words}.
3171: @item M-d
3172: Kill word (@code{kill-word}).
3173: @item M-@key{DEL}
3174: Kill word backwards (@code{backward-kill-word}).
3175: @item C-x @key{DEL}
3176: Kill back to beginning of sentence (@code{backward-kill-sentence}).
3177: @xref{Sentences}.
3178: @item M-k
3179: Kill to end of sentence (@code{kill-sentence}).
3180: @item C-M-k
3181: Kill sexp (@code{kill-sexp}). @xref{Lists}.
3182: @item M-z @var{char}
3183: Kill up to next occurrence of @var{char} (@code{zap-to-char}).
3184: @end table
3185:
3186: A kill command which is very general is @kbd{C-w} (@code{kill-region}),
3187: which kills everything between point and the mark. With this command, you
3188: can kill any contiguous sequence of characters, if you first set the mark
3189: at one end of them and go to the other end.
3190:
3191: @kindex M-z
3192: @findex zap-to-char
3193: A convenient way of killing is combined with searching: @kbd{M-z}
3194: (@code{zap-to-char}) reads a character and kills from point up to (but not
3195: including) the next occurrence of that character in the buffer. If there
3196: is no next occurrence, killing goes to the end of the buffer. A numeric
3197: argument acts as a repeat count. A negative argument means to search
3198: backward and kill text before point.
3199:
3200: Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and
3201: @kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and
3202: sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k}
3203: (@pxref{Sentences}).@refill
3204:
3205: @node Yanking, Accumulating Text, Killing, Top
3206: @section Yanking
3207: @cindex moving text
3208: @cindex copying text
3209: @cindex kill ring
3210: @cindex yanking
3211: @cindex pasting
3212:
3213: @dfn{Yanking} is getting back text which was killed. This is what some
3214: systems call ``pasting''. The usual way to move or copy text is to kill it
3215: and then yank it one or more times.
3216:
3217: @table @kbd
3218: @item C-y
3219: Yank last killed text (@code{yank}).
3220: @item M-y
3221: Replace re-inserted killed text with the previously killed text
3222: (@code{yank-pop}).
3223: @item M-w
3224: Save region as last killed text without actually killing it
3225: (@code{copy-region-as-kill}).
3226: @item C-M-w
3227: Append next kill to last batch of killed text (@code{append-next-kill}).
3228: @end table
3229:
3230: @menu
3231: * Kill Ring:: Where killed text is stored. Basic yanking.
3232: * Appending Kills:: Several kills in a row all yank together.
3233: * Earlier Kills:: Yanking something killed some time ago.
3234: @end menu
3235:
3236: @node Kill Ring, Appending Kills, Yanking, Yanking
3237: @subsection The Kill Ring
3238:
3239: @kindex C-y
3240: @findex Yank
3241: All killed text is recorded in the @dfn{kill ring}, a list of blocks of
3242: text that have been killed. There is only one kill ring, used in all
3243: buffers, so you can kill text in one buffer and yank it in another buffer.
3244: This is the usual way to move text from one file to another.
3245: (@xref{Accumulating Text}, for some other ways.)
3246:
3247: The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent
3248: kill. It leaves the cursor at the end of the text. It sets the mark at
3249: the beginning of the text. @xref{Mark}.
3250:
3251: @kbd{C-u C-y} leaves the cursor in front of the text, and sets the mark
3252: after it. This is only if the argument is specified with just a @kbd{C-u},
3253: precisely. Any other sort of argument, including @kbd{C-u} and digits, has
3254: an effect described below (under ``Yanking Earlier Kills'').
3255:
3256: @kindex M-w
3257: @findex copy-region-as-kill
3258: If you wish to copy a block of text, you might want to use @kbd{M-w}
3259: (@code{copy-region-as-kill}), which copies the region into the kill ring
3260: without removing it from the buffer. This is approximately equivalent to
3261: @kbd{C-w} followed by @kbd{C-y}, except that @kbd{M-w} does not mark the
3262: buffer as ``modified'' and does not temporarily change the screen.
3263:
3264: @node Appending Kills, Earlier Kills, Kill Ring, Yanking
3265: @subsection Appending Kills
3266:
3267: @cindex television
3268: Normally, each kill command pushes a new block onto the kill ring.
3269: However, two or more kill commands in a row combine their text into a
3270: single entry, so that a single @kbd{C-y} gets it all back as it was before
3271: it was killed. This means that you don't have to kill all the text in one
3272: command; you can keep killing line after line, or word after word, until
3273: you have killed it all, and you can still get it all back at once. (Thus
3274: we join television in leading people to kill thoughtlessly.)
3275:
3276: Commands that kill forward from point add onto the end of the previous
3277: killed text. Commands that kill backward from point add onto the
3278: beginning. This way, any sequence of mixed forward and backward kill
3279: commands puts all the killed text into one entry without rearrangement.
3280: Numeric arguments do not break the sequence of appending kills. For
3281: example, suppose the buffer contains
3282:
3283: @example
3284: This is the first
3285: line of sample text
3286: and here is the third.
3287: @end example
3288:
3289: @noindent
3290: with point at the beginning of the second line. If you type @kbd{C-k C-u 2
3291: M-@key{DEL} C-k}, the first @kbd{C-k} kills the text @samp{line of sample
3292: text}, @kbd{C-u 2 M-@key{DEL}} kills @samp{the first} with the newline that
3293: followed it, and the second @kbd{C-k} kills the newline after the second
3294: line. The result is that the buffer contains @samp{This is and here is the
3295: third.} and a single kill entry contains @samp{the first@key{RET}line of
3296: sample text@key{RET}}---all the killed text, in its original order.
3297:
3298: @kindex C-M-w
3299: @findex append-next-kill
3300: If a kill command is separated from the last kill command by other
3301: commands (not just numeric arguments), it starts a new entry on the kill
3302: ring. But you can force it to append by first typing the command
3303: @kbd{C-M-w} (@code{append-next-kill}) in front of it. The @kbd{C-M-w}
3304: tells the following command, if it is a kill command, to append the text it
3305: kills to the last killed text, instead of starting a new entry. With
3306: @kbd{C-M-w}, you can kill several separated pieces of text and accumulate
3307: them to be yanked back in one place.@refill
3308:
3309: @node Earlier Kills,, Appending Kills, Yanking
3310: @subsection Yanking Earlier Kills
3311:
3312: @kindex M-y
3313: @findex yank-pop
3314: To recover killed text that is no longer the most recent kill, you need
3315: the @kbd{Meta-y} (@code{yank-pop}) command. @kbd{M-y} can be used only
3316: after a @kbd{C-y} or another @kbd{M-y}. It takes the text previously
3317: yanked and replaces it with the text from an earlier kill. So, to recover
3318: the text of the next-to-the-last kill, you first use @kbd{C-y} to recover
3319: the last kill, and then use @kbd{M-y} to replace it with the previous
3320: kill.@refill
3321:
3322: You can think in terms of a ``last yank'' pointer which points at an item
3323: in the kill ring. Each time you kill, the ``last yank'' pointer moves to
3324: the newly made item at the front of the ring. @kbd{C-y} yanks the item
3325: which the ``last yank'' pointer points to. @kbd{M-y} moves the ``last
3326: yank'' pointer to a different item, and the text in the buffer changes to
3327: match. Enough @kbd{M-y} commands can move the pointer to any item in the
3328: ring, so you can get any item into the buffer. Eventually the pointer
3329: reaches the end of the ring; the next @kbd{M-y} moves it to the first item
3330: again.
3331:
3332: Yanking moves the ``last yank'' pointer around the ring, but it does not
3333: change the order of the entries in the ring, which always runs from the
3334: most recent kill at the front to the oldest one still remembered.
3335:
3336: @kbd{M-y} can take a numeric argument, which tells it how many items to
3337: advance the ``last yank'' pointer by. A negative argument moves the
3338: pointer toward the front of the ring; from the front of the ring, it moves
3339: to the last entry and starts moving forward from there.
3340:
3341: Once the text you are looking for is brought into the buffer, you can
3342: stop doing @kbd{M-y} commands and it will stay there. It's just a copy of
3343: the kill ring item, so editing it in the buffer does not change what's in
3344: the ring. As long as no new killing is done, the ``last yank'' pointer
3345: remains at the same place in the kill ring, so repeating @kbd{C-y} will
3346: yank another copy of the same old kill.
3347:
3348: If you know how many @kbd{M-y} commands it would take to find the
3349: text you want, you can yank that text in one step using @kbd{C-y} with
3350: a numeric argument. @kbd{C-y} with an argument greater than one
3351: restores the text the specified number of entries back in the kill
3352: ring. Thus, @kbd{C-u 2 C-y} gets the next to the last block of killed
3353: text. It is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numeric
3354: argument starts counting from the ``last yank'' pointer, and sets the
3355: ``last yank'' pointer to the entry that it yanks.
3356:
3357: @vindex kill-ring-max
3358: The length of the kill ring is controlled by the variable
3359: @code{kill-ring-max}; no more than that many blocks of killed text are
3360: saved.
3361:
3362: @node Accumulating Text, Rectangles, Yanking, Top
3363: @section Accumulating Text
3364: @kindex C-x a
3365: @findex append-to-buffer
3366: @findex prepend-to-buffer
3367: @findex copy-to-buffer
3368: @findex append-to-file
3369:
3370: Usually we copy or move text by killing it and yanking it, but there are
3371: other ways that are useful for copying one block of text in many places, or
3372: for copying many scattered blocks of text into one place.
3373:
3374: You can accumulate blocks of text from scattered locations either into a
3375: buffer or into a file if you like. These commands are described here. You
3376: can also use Emacs registers for storing and accumulating text.
3377: @xref{Registers}.
3378:
3379: @table @kbd
3380: @item C-x a
3381: Append region to contents of specified buffer (@code{append-to-buffer}).
3382: @item M-x prepend-to-buffer
3383: Prepend region to contents of specified buffer.
3384: @item M-x copy-to-buffer
3385: Copy region into specified buffer, deleting that buffer's old contents.
3386: @item M-x insert-buffer
3387: Insert contents of specified buffer into current buffer at point.
3388: @item M-x append-to-file
3389: Append region to contents of specified file, at the end.
3390: @end table
3391:
3392: To accumulate text into a buffer, use the command @kbd{C-x a @var{buffername}}
3393: (@code{append-to-buffer}), which inserts a copy of the region into the
3394: buffer @var{buffername}, at the location of point in that buffer. If there
3395: is no buffer with that name, one is created. If you append text into a
3396: buffer which has been used for editing, the copied text goes into the
3397: middle of the text of the buffer, wherever point happens to be in it.
3398:
3399: Point in that buffer is left at the end of the copied text, so successive
3400: uses of @kbd{C-x a} accumulate the text in the specified buffer in the same
3401: order as they were copied. Strictly speaking, @kbd{C-x a} does not always
3402: append to the text already in the buffer; but if @kbd{C-x a} is the only
3403: command used to alter a buffer, it does always append to the existing text
3404: because point is always at the end.
3405:
3406: @kbd{M-x prepend-to-buffer} is just like @kbd{C-x a} except that point in
3407: the other buffer is left before the copied text, so successive prependings
3408: add text in reverse order. @kbd{M-x copy-to-buffer} is similar except that
3409: any existing text in the other buffer is deleted, so the buffer is left
3410: containing just the text newly copied into it.
3411:
3412: You can retrieve the accumulated text from that buffer with @kbd{M-x
3413: insert-buffer}; this too takes @var{buffername} as an argument. It inserts
3414: a copy of the text in buffer @var{buffername} into the selected buffer.
3415: You could alternatively select the other buffer for editing, perhaps moving
3416: text from it by killing or with @kbd{C-x a}. @xref{Buffers}, for
3417: background information on buffers.
3418:
3419: Instead of accumulating text within Emacs, in a buffer, you can append
3420: text directly into a file with @kbd{M-x append-to-file}, which takes
3421: @var{file-name} as an argument. It adds the text of the region to the end
3422: of the specified file. The file is changed immediately on disk. This
3423: command is normally used with files that are @i{not} being visited in
3424: Emacs. Using it on a file that Emacs is visiting can produce confusing
3425: results, because the text inside Emacs for that file will not change
3426: while the file itself changes.
3427:
3428: @node Rectangles, Registers, Accumulating Text, Top
3429: @section Rectangles
3430: @cindex rectangles
3431:
3432: The rectangle commands affect rectangular areas of the text: all the
3433: characters between a certain pair of columns, in a certain range of lines.
3434: Commands are provided to kill rectangles, yank killed rectangles, clear
3435: them out, or delete them. Rectangle commands are useful with text in
3436: multicolumnar formats, such as perhaps code with comments at the right,
3437: or for changing text into or out of such formats.
3438:
3439: When you must specify a rectangle for a command to work on, you do
3440: it by putting the mark at one corner and point at the opposite corner.
3441: The rectangle thus specified is called the @dfn{region-rectangle}
3442: because it is controlled about the same way the region is controlled.
3443: But remember that a given combination of point and mark values can be
3444: interpreted either as specifying a region or as specifying a
3445: rectangle; it is up to the command that uses them to choose the
3446: interpretation.
3447:
3448: @table @kbd
3449: @item M-x delete-rectangle
3450: Delete the text of the region-rectangle, moving any following text on
3451: each line leftward to the left edge of the region-rectangle.
3452: @item M-x kill-rectangle
3453: Similar, but also save the contents of the region-rectangle as the
3454: ``last killed rectangle''.
3455: @item M-x yank-rectangle
3456: Yank the last killed rectangle with its upper left corner at point.
3457: @item M-x open-rectangle
3458: Insert blank space to fill the space of the region-rectangle.
3459: The previous contents of the region-rectangle are pushed rightward.
3460: @item M-x clear-rectangle
3461: Clear the region-rectangle by replacing its contents with spaces.
3462: @end table
3463:
3464: The rectangle operations fall into two classes: commands deleting and
3465: moving rectangles, and commands for blank rectangles.
3466:
3467: @findex delete-rectangle
3468: @findex kill-rectangle
3469: There are two ways to get rid of the text in a rectangle: you can discard
3470: the text (delete it) or save it as the ``last killed'' rectangle. The
3471: commands for these two ways are @kbd{M-x delete-rectangle} and @kbd{M-x
3472: kill-rectangle}. In either case, the portion of each line that falls inside
3473: the rectangle's boundaries is deleted, causing following text (if any) on
3474: the line to move left.
3475:
3476: Note that ``killing'' a rectangle is not killing in the usual sense; the
3477: rectangle is not stored in the kill ring, but in a special place that
3478: can only record the most recent rectangle killed. This is because yanking
3479: a rectangle is so different from yanking linear text that different yank
3480: commands have to be used and yank-popping is hard to make sense of.
3481:
3482: Inserting a rectangle is the opposite of deleting one. All you need to
3483: specify is where to put the upper left corner; that is done by putting
3484: point there. The rectangle's first line is inserted there, the rectangle's
3485: second line is inserted at a point one line vertically down, and so on.
3486: The number of lines affected is determined by the height of the saved
3487: rectangle.
3488:
3489: @findex yank-rectangle
3490: To insert the last killed rectangle, type @kbd{M-x yank-rectangle}.
3491: This can be used to convert single-column lists into double-column
3492: lists; kill the second half of the list as a rectangle and then
3493: yank it beside the first line of the list.
3494:
3495: @findex open-rectangle
3496: @findex clear-rectangle
3497: There are two commands for working with blank rectangles: @kbd{M-x
3498: clear-rectangle} to blank out existing text, and @kbd{M-x open-rectangle}
3499: to insert a blank rectangle. Clearing a rectangle is equivalent to
3500: deleting it and then inserting as blank rectangle of the same size.
3501:
3502: Rectangles can also be copied into and out of registers.
3503: @xref{RegRect,,Rectangle Registers}.
3504:
3505: @node Registers, Display, Rectangles, Top
3506: @chapter Registers
3507: @cindex registers
3508:
3509: Emacs @dfn{registers} are places you can save text or positions for
3510: later use. Text saved in a register can be copied into the buffer
3511: once or many times; a position saved in a register is used by moving
3512: point to that position. Rectangles can also be copied into and out of
3513: registers (@pxref{Rectangles}).
3514:
3515: Each register has a name, which is a single character. A register can
3516: store either a piece of text or a position or a rectangle, but only one
3517: thing at any given time. Whatever you store in a register remains
3518: there until you store something else in that register.
3519:
3520: @menu
3521: * RegPos:: Saving positions in registers.
3522: * RegText:: Saving text in registers.
3523: * RegRect:: Saving rectangles in registers.
3524: @end menu
3525:
3526: @table @kbd
3527: @item M-x view-register @key{RET} @var{r}
3528: Display a description of what register @var{r} contains.
3529: @end table
3530:
3531: @findex view-register
3532: @kbd{M-x view-register} reads a register name as an argument and then
3533: displays the contents of the specified register.
3534:
3535: @node RegPos, RegText, Registers, Registers
3536: @section Saving Positions in Registers
3537:
3538: Saving a position records a spot in a buffer so that you can move
3539: back there later. Moving to a saved position reselects the buffer
3540: and moves point to the spot.
3541:
3542: @table @kbd
3543: @item C-x / @var{r}
3544: Save location of point in register @var{r} (@code{point-to-register}).
3545: @item C-x j @var{r}
3546: Jump to the location saved in register @var{r} (@code{register-to-point}).
3547: @end table
3548:
3549: @kindex C-x /
3550: @findex point-to-register
3551: To save the current location of point in a register, choose a name
3552: @var{r} and type @kbd{C-x / @var{r}}. The register @var{r} retains
3553: the location thus saved until you store something else in that
3554: register.@refill
3555:
3556: @kindex C-x j
3557: @findex register-to-point
3558: The command @kbd{C-x j @var{r}} moves point to the location recorded
3559: in register @var{r}. The register is not affected; it continues to
3560: record the same location. You can jump to the same position using the
3561: same register any number of times.
3562:
3563: @node RegText, RegRect, RegPos, Registers
3564: @section Saving Text in Registers
3565:
3566: When you want to insert a copy of the same piece of text frequently, it
3567: may be impractical to use the kill ring, since each subsequent kill moves
3568: the piece of text further down on the ring. It becomes hard to keep track
3569: of what argument is needed to retrieve the same text with @kbd{C-y}. An
3570: alternative is to store the text in a register with @kbd{C-x x}
3571: (@code{copy-to-register}) and then retrieve it with @kbd{C-x g}
3572: (@code{insert-register}).
3573:
3574: @table @kbd
3575: @item C-x x @var{r}
3576: Copy region into register @var{r} (@code{copy-to-register}).
3577: @item C-x g @var{r}
3578: Insert text contents of register @var{r} (@code{insert-register}).
3579: @end table
3580:
3581: @kindex C-x x
3582: @kindex C-x g
3583: @findex copy-to-register
3584: @findex insert-register
3585: @kbd{C-x x @var{r}} stores a copy of the text of the region into the
3586: register named @var{r}. Given a numeric argument, @kbd{C-x x} deletes the
3587: text from the buffer as well.
3588:
3589: @kbd{C-x g @var{r}} inserts in the buffer the text from register @var{r}.
3590: Normally it leaves point before the text and places the mark after, but
3591: with a numeric argument it puts point after the text and the mark before.
3592:
3593: @node RegRect,, RegText, Registers
3594: @section Saving Rectangles in Registers
3595:
3596: A register can contain a rectangle instead of linear text. The rectangle
3597: is represented as a list of strings. @xref{Rectangles}, for basic
3598: information on rectangles and how rectangles in the buffer are specified.
3599:
3600: @table @kbd
3601: @c !!! following generates acceptable underfull hbox
3602: @item C-x r @var{r}
3603: Copy the region-rectangle into register @var{r} (@code{copy-region-to-rectangle}).
3604: With numeric argument, delete it as well.
3605: @item C-x g @var{r}
3606: Insert the rectangle stored in register @var{r} (if it contains a
3607: rectangle) (@code{insert-register}).
3608: @end table
3609:
3610: The @kbd{C-x g} command inserts linear text if the register contains
3611: that, or inserts a rectangle if the register contains one.
3612:
3613: @node Display, Search, Registers, Top
3614: @chapter Controlling the Display
3615:
3616: Since only part of a large buffer fits in the window, Emacs tries to show
3617: the part that is likely to be interesting. The display control commands
3618: allow you to specify which part of the text you want to see.
3619:
3620: @table @kbd
3621: @item C-l
3622: Clear screen and redisplay, scrolling the selected window to center
3623: point vertically within it (@code{recenter}).
3624: @item C-v
3625: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
3626: @item M-v
3627: Scroll backward (@code{scroll-down}).
3628: @item @var{arg} C-l
3629: Scroll so point is on line @var{arg} (@code{recenter}).
3630: @item C-x <
3631: Scroll text in current window to the left (@code{scroll-left}).
3632: @item C-x >
3633: Scroll to the right (@code{scroll-right}).
3634: @item C-x $
3635: Make deeply indented lines invisible (@code{set-selective-display}).
3636: @end table
3637:
3638: @menu
3639: * Scrolling:: Moving text up and down in a window.
3640: * Horizontal Scrolling:: Moving text left and right in a window.
3641: * Selective Display:: Hiding lines with lots of indentation.
3642: * Display Vars:: Information on variables for customizing display.
3643: @end menu
3644:
3645: @node Scrolling, Horizontal Scrolling, Display, Display
3646: @section Scrolling
3647:
3648: If a buffer contains text that is too large to fit entirely within a
3649: window that is displaying the buffer, Emacs shows a contiguous section of
3650: the text. The section shown always contains point.
3651:
3652: @cindex scrolling
3653: @dfn{Scrolling} means moving text up or down in the window so that
3654: different parts of the text are visible. Scrolling forward means that text
3655: moves up, and new text appears at the bottom. Scrolling backward moves
3656: text down and new text appears at the top.
3657:
3658: Scrolling happens automatically if you move point past the bottom or top
3659: of the window. You can also explicitly request scrolling with the commands
3660: in this section.
3661:
3662: @ifinfo
3663: @table @kbd
3664: @item C-l
3665: Clear screen and redisplay, scrolling the selected window to center
3666: point vertically within it (@code{recenter}).
3667: @item C-v
3668: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
3669: @item M-v
3670: Scroll backward (@code{scroll-down}).
3671: @item @var{arg} C-l
3672: Scroll so point is on line @var{arg} (@code{recenter}).
3673: @end table
3674: @end ifinfo
3675:
3676: @kindex C-l
3677: @findex recenter
3678: The most basic scrolling command is @kbd{C-l} (@code{recenter}) with no
3679: argument. It clears the entire screen and redisplays all windows. In
3680: addition, the selected window is scrolled so that point is halfway down
3681: from the top of the window.
3682:
3683: @kindex C-v
3684: @kindex M-v
3685: @findex scroll-up
3686: @findex scroll-down
3687: The scrolling commands @kbd{C-v} and @kbd{M-v} let you move all the text
3688: in the window up or down a few lines. @kbd{C-v} (@code{scroll-up}) with an
3689: argument shows you that many more lines at the bottom of the window, moving
3690: the text and point up together as @kbd{C-l} might. @kbd{C-v} with a
3691: negative argument shows you more lines at the top of the window.
3692: @kbd{Meta-v} (@code{scroll-down}) is like @kbd{C-v}, but moves in the
3693: opposite direction.@refill
3694:
3695: @vindex next-screen-context-lines
3696: To read the buffer a windowful at a time, use @kbd{C-v} with no argument.
3697: It takes the last two lines at the bottom of the window and puts them at
3698: the top, followed by nearly a whole windowful of lines not previously
3699: visible. If point was in the text scrolled off the top, it moves to the
3700: new top of the window. @kbd{M-v} with no argument moves backward with
3701: overlap similarly. The number of lines of overlap across a @kbd{C-v} or
3702: @kbd{M-v} is controlled by the variable @code{next-screen-context-lines}; by
3703: default, it is two.
3704:
3705: Another way to do scrolling is with @kbd{C-l} with a numeric argument.
3706: @kbd{C-l} does not clear the screen when given an argument; it only scrolls
3707: the selected window. With a positive argument @var{n}, it repositions text
3708: to put point @var{n} lines down from the top. An argument of zero puts
3709: point on the very top line. Point does not move with respect to the text;
3710: rather, the text and point move rigidly on the screen. @kbd{C-l} with a
3711: negative argument puts point that many lines from the bottom of the window.
3712: For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u
3713: - 5 C-l} puts it five lines from the bottom. Just @kbd{C-u} as argument,
3714: as in @kbd{C-u C-l}, scrolls point to the center of the screen.
3715:
3716: @vindex scroll-step
3717: Scrolling happens automatically if point has moved out of the visible
3718: portion of the text when it is time to display. Usually the scrolling is
3719: done so as to put point vertically centered within the window. However, if
3720: the variable @code{scroll-step} has a nonzero value, an attempt is made to
3721: scroll the buffer by that many lines; if that is enough to bring point back
3722: into visibility, that is what is done.
3723:
3724: @node Horizontal Scrolling,, Scrolling, Display
3725: @section Horizontal Scrolling
3726:
3727: @ifinfo
3728: @table @kbd
3729: @item C-x <
3730: Scroll text in current window to the left (@code{scroll-left}).
3731: @item C-x >
3732: Scroll to the right (@code{scroll-right}).
3733: @end table
3734: @end ifinfo
3735:
3736: @kindex C-x <
3737: @kindex C-x >
3738: @findex scroll-left
3739: @findex scroll-right
3740: @cindex horizontal scrolling
3741: The text in a window can also be scrolled horizontally. This means that
3742: each line of text is shifted sideways in the window, and one or more
3743: characters at the beginning of each line are not displayed at all. When a
3744: window has been scrolled horizontally in this way, text lines are truncated
3745: rather than continued (@pxref{Continuation Lines}), with a @samp{$} appearing
3746: in the first column when there is text truncated to the left, and in the
3747: last column when there is text truncated to the right.
3748:
3749: The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected window
3750: to the left by @var{n} columns with argument @var{n}. With no argument, it scrolls
3751: by almost the full width of the window (two columns less, to be precise).
3752: @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right.
3753: The window cannot be scrolled any farther to the right once it is
3754: displaying normally (with each line starting at the window's left margin);
3755: attempting to do so has no effect.
3756:
3757: @node Selective Display, Display Vars, Display, Display
3758: @section Selective Display
3759: @findex set-selective-display
3760: @kindex C-x $
3761:
3762: Emacs has the ability to hide lines indented more than a certain number
3763: of columns (you specify how many columns). You can use this to get an
3764: overview of a part of a program.
3765:
3766: To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a
3767: numeric argument @var{n}. (@xref{Arguments}, for how to give the
3768: argument.) Then lines with at least @var{n} columns of indentation
3769: disappear from the screen. The only indication of their presence is that
3770: three dots (@samp{@dots{}}) appear at the end of each visible line that is
3771: followed by one or more invisible ones.@refill
3772:
3773: The invisible lines are still present in the buffer, and most editing
3774: commands see them as usual, so it is very easy to put point in the middle
3775: of invisible text. When this happens, the cursor appears at the end of the
3776: previous line, after the three dots. If point is at the end of the visible
3777: line, before the newline that ends it, the cursor appears before the three
3778: dots.
3779:
3780: The commands @kbd{C-n} and @kbd{C-p} move across the invisible lines as if they
3781: were not there.
3782:
3783: To make everything visible again, type @kbd{C-x $} with no argument.
3784:
3785: @node Display Vars,, Selective Display, Display
3786: @section Variables Controlling Display
3787:
3788: This section contains information for customization only. Beginning
3789: users should skip it.
3790:
3791: @vindex mode-line-inverse-video
3792: The variable @code{mode-line-inverse-video} controls whether the mode
3793: line is displayed in inverse video (assuming the terminal supports it);
3794: @code{nil} means don't do so. @xref{Mode Line}.
3795:
3796: @vindex inverse-video
3797: If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
3798: to invert all the lines of the display from what they normally are.
3799:
3800: @vindex visible-bell
3801: If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
3802: to make the whole screen blink when it would normally make an audible bell
3803: sound. This variable has no effect if your terminal does not have a way
3804: to make the screen blink.@refill
3805:
3806: @vindex no-redraw-on-reenter
3807: When you reenter Emacs after suspending, Emacs normally clears the screen
3808: and redraws the entire display. On some terminals with more than one page
3809: of memory, it is possible to arrange the termcap entry so that the
3810: @samp{ti} and @samp{te} strings (output to the terminal when Emacs is
3811: entered and exited, respectively) switch between pages of memory so as to
3812: use one page for Emacs and another page for other output. Then you might
3813: want to set the variable @code{no-redraw-on-reenter} non-@code{nil} so that
3814: Emacs will assume, when resumed, that the screen page it is using still
3815: contains what Emacs last wrote there.
3816:
3817: @vindex echo-keystrokes
3818: The variable @code{echo-keystrokes} controls the echoing of multi-character
3819: keys; its value is the number of seconds of pause required to cause echoing
3820: to start, or zero meaning don't echo at all. @xref{Echo Area}.
3821:
3822: @vindex ctl-arrow
3823: If the variable @code{ctl-arrow} is @code{nil}, control characters in the
3824: buffer are displayed with octal escape sequences, all except newline and
3825: tab. Altering the value of @code{ctl-arrow} makes it local to the current
3826: buffer; until that time, the default value is in effect. The default is
3827: initially @code{t}. @xref{Locals}.
3828:
3829: @vindex tab-width
3830: Normally, a tab character in the buffer is displayed as whitespace which
3831: extends to the next display tab stop position, and display tab stops come
3832: at intervals equal to eight spaces. The number of spaces per tab is
3833: controlled by the variable @code{tab-width}, which is made local by
3834: changing it, just like @code{ctl-arrow}. Note that how the tab character
3835: in the buffer is displayed has nothing to do with the definition of
3836: @key{TAB} as a command.
3837:
3838: @vindex selective-display-ellipses
3839: If you set the variable @code{selective-display-ellipses} to @code{nil},
3840: the three dots do not appear at the end of a line that precedes invisible
3841: lines. Then there is no visible indication of the invisible lines.
3842: This variable too becomes local automatically when set.
3843:
3844: @node Search, Fixit, Display, Top
3845: @chapter Searching and Replacement
3846: @cindex searching
3847:
3848: Like other editors, Emacs has commands for searching for occurrences of
3849: a string. The principal search command is unusual in that it is
3850: @dfn{incremental}; it begins to search before you have finished typing the
3851: search string. There are also nonincremental search commands more like
3852: those of other editors.
3853:
3854: Besides the usual @code{replace-string} command that finds all
3855: occurrences of one string and replaces them with another, Emacs has a fancy
3856: replacement command called @code{query-replace} which asks interactively
3857: which occurrences to replace.
3858:
3859: @menu
3860: * Incremental Search:: Search happens as you type the string.
3861: * Nonincremental Search:: Specify entire string and then search.
3862: * Word Search:: Search for sequence of words.
3863: * Regexp Search:: Search for match for a regexp.
3864: * Regexps:: Syntax of regular expressions.
3865: * Search Case:: To ignore case while searching, or not.
3866: * Replace:: Search, and replace some or all matches.
3867: * Other Repeating Search:: Operating on all matches for some regexp.
3868: @end menu
3869:
3870: @node Incremental Search, Nonincremental Search, Search, Search
3871: @section Incremental Search
3872:
3873: An incremental search begins searching as soon as you type the first
3874: character of the search string. As you type in the search string, Emacs
3875: shows you where the string (as you have typed it so far) would be found.
3876: When you have typed enough characters to identify the place you want, you
3877: can stop. Depending on what you will do next, you may or may not need to
3878: terminate the search explicitly with an @key{ESC} first.
3879:
3880: @c WideCommands
3881: @table @kbd
3882: @item C-s
3883: Incremental search forward (@code{isearch-forward}).
3884: @item C-r
3885: Incremental search backward (@code{isearch-backward}).
3886: @end table
3887:
3888: @kindex C-s
3889: @kindex C-r
3890: @findex isearch-forward
3891: @findex isearch-backward
3892: @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from
3893: the keyboard and positions the cursor at the first occurrence of the
3894: characters that you have typed. If you type @kbd{C-s} and then @kbd{F},
3895: the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see
3896: the cursor move to after the first @samp{FO}. After another @kbd{O}, the
3897: cursor is after the first @samp{FOO} after the place where you started the
3898: search. Meanwhile, the search string @samp{FOO} has been echoed in the
3899: echo area.@refill
3900:
3901: The echo area display ends with three dots when actual searching is going
3902: on. When search is waiting for more input, the three dots are removed.
3903: (On slow terminals, the three dots are not displayed.)
3904:
3905: If you make a mistake in typing the search string, you can erase
3906: characters with @key{DEL}. Each @key{DEL} cancels the last character of
3907: search string. This does not happen until Emacs is ready to read another
3908: input character; first it must either find, or fail to find, the character
3909: you want to erase. If you do not want to wait for this to happen, use
3910: @kbd{C-g} as described below.@refill
3911:
3912: When you are satisfied with the place you have reached, you can type
3913: @key{ESC}, which stops searching, leaving the cursor where the search
3914: brought it. Also, any command not specially meaningful in searches stops
3915: the searching and is then executed. Thus, typing @kbd{C-a} would exit the
3916: search and then move to the beginning of the line. @key{ESC} is necessary
3917: only if the next command you want to type is a printing character,
3918: @key{DEL}, @key{ESC}, or another control character that is special within
3919: searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s} or @kbd{C-y}).
3920:
3921: Sometimes you search for @samp{FOO} and find it, but not the one you
3922: expected to find. There was a second @samp{FOO} that you forgot about,
3923: before the one you were looking for. In this event, type another @kbd{C-s}
3924: to move to the next occurrence of the search string. This can be done any
3925: number of times. If you overshoot, you can cancel some @kbd{C-s}
3926: characters with @key{DEL}.
3927:
3928: After you exit a search, you can search for the same string again by
3929: typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
3930: incremental search, and the second @kbd{C-s} means ``search again''.
3931:
3932: If your string is not found at all, the echo area says @samp{Failing
3933: I-Search}. The cursor is after the place where Emacs found as much of your
3934: string as it could. Thus, if you search for @samp{FOOT}, and there is no
3935: @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
3936: At this point there are several things you can do. If your string was
3937: mistyped, you can rub some of it out and correct it. If you like the place
3938: you have found, you can type @key{ESC} or some other Emacs command to
3939: ``accept what the search offered''. Or you can type @kbd{C-g}, which
3940: removes from the search string the characters that could not be found (the
3941: @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
3942: @samp{FOOT}). A second @kbd{C-g} at that point cancels the search
3943: entirely, returning point to where it was when the search started.
3944:
3945: If a search is failing and you ask to repeat it by typing another
3946: @kbd{C-s}, it starts again from the beginning of the buffer. Repeating
3947: a failing reverse search with @kbd{C-r} starts again from the end. This
3948: is called @dfn{wrapping around}. @samp{Wrapped} appears in the search
3949: prompt once this has happened.
3950:
3951: @cindex quitting (in search)
3952: The @kbd{C-g} ``quit'' character does special things during searches;
3953: just what it does depends on the status of the search. If the search has
3954: found what you specified and is waiting for input, @kbd{C-g} cancels the
3955: entire search. The cursor moves back to where you started the search. If
3956: @kbd{C-g} is typed when there are characters in the search string that have
3957: not been found---because Emacs is still searching for them, or because it
3958: has failed to find them---then the search string characters which have not
3959: been found are discarded from the search string. With them gone, the
3960: search is now successful and waiting for more input, so a second @kbd{C-g}
3961: will cancel the entire search.
3962:
3963: To search for a control character such as @kbd{C-s} or @key{DEL} or
3964: @key{ESC}, you must quote it by typing @kbd{C-q} first. This function
3965: of @kbd{C-q} is analogous to its meaning as an Emacs command: it causes
3966: the following character to be treated the way a graphic character would
3967: normally be treated in the same context. You can also specify a quoted
3968: character in octal while searching, just as you can for insertion.
3969: @xref{Basic}.
3970:
3971: You can change to searching backwards with @kbd{C-r}. If a search fails
3972: because the place you started was too late in the file, you should do this.
3973: Repeated @w{@kbd{C-r}} keeps looking for more occurrences backwards. A
3974: @kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be cancelled
3975: with @key{DEL}.
3976:
3977: If you know initially that you want to search backwards, you can
3978: use @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r}
3979: is also a key running a command (@code{isearch-backward}) to search
3980: backward.
3981:
3982: The characters @kbd{C-y} and @kbd{C-w} can be used in incremental search
3983: to grab text from the buffer into the search string. This makes it
3984: convenient to search for another occurrence of text at point. @kbd{C-w}
3985: copies the word after point as part of the search string, advancing
3986: point over that word. Another @kbd{C-s} to repeat the search will then
3987: search for a string including that word. @kbd{C-y} is similar to @kbd{C-w}
3988: but copies all the rest of the current line into the search string.
3989:
3990: All the characters special in incremental search can be changed by setting
3991: the following variables:
3992:
3993: @vindex search-delete-char
3994: @vindex search-exit-char
3995: @vindex search-quote-char
3996: @vindex search-repeat-char
3997: @vindex search-reverse-char
3998: @vindex search-yank-line-char
3999: @vindex search-yank-word-char
4000: @table @code
4001: @item search-delete-char
4002: Character to delete from incremental search string (normally @key{DEL}).
4003: @item search-exit-char
4004: Character to exit incremental search (normally @key{ESC}).
4005: @item search-quote-char
4006: Character to quote special characters for incremental search (normally
4007: @kbd{C-q}).
4008: @item search-repeat-char
4009: Character to repeat incremental search forwards (normally @w{@kbd{C-s}}).
4010: @item search-reverse-char
4011: Character to repeat incremental search backwards (normally @w{@kbd{C-r}}).
4012: @item search-yank-line-char
4013: Character to pull rest of line from buffer into search string
4014: (normally @kbd{C-y}).
4015: @item search-yank-word-char
4016: Character to pull next word from buffer into search string (normally
4017: @kbd{C-w}).
4018: @end table
4019:
4020: @subsection Slow Terminal Incremental Search
4021:
4022: Incremental search on a slow terminal uses a modified style of display
4023: that is designed to take less time. Instead of redisplaying the buffer at
4024: each place the search gets to, it creates a new single-line window and uses
4025: that to display the line that the search has found. The single-line window
4026: comes into play as soon as point gets outside of the text that is already
4027: on the screen.
4028:
4029: When the search is terminated, the single-line window is removed. Only
4030: at this time is the window in which the search was done redisplayed to show
4031: its new value of point.
4032:
4033: The three dots at the end of the search string, normally used to indicate
4034: that searching is going on, are not displayed in slow style display.
4035:
4036: @vindex search-slow-speed
4037: The slow terminal style of display is used when the terminal baud rate is
4038: less than or equal to the value of the variable @code{search-slow-speed},
4039: initially 1200.
4040:
4041: @vindex search-slow-window-lines
4042: The number of lines to use in slow terminal search display is controlled
4043: by the variable @code{search-slow-window-lines}. 1 is its normal value.
4044:
4045: @node Nonincremental Search, Word Search, Incremental Search, Search
4046: @section Nonincremental Search
4047: @cindex nonincremental search
4048:
4049: Emacs also has conventional nonincremental search commands, which require
4050: you to type the entire search string before searching begins.
4051:
4052: @table @kbd
4053: @item C-s @key{ESC} @var{string} @key{RET}
4054: Search for @var{string}.
4055: @item C-r @key{ESC} @var{string} @key{RET}
4056: Search backward for @var{string}.
4057: @end table
4058:
4059: To do a nonincremental search, first type @kbd{C-s @key{ESC}}. This
4060: enters the minibuffer to read the search string; terminate the string with
4061: @key{RET}, and then the search is done. If the string is not found the
4062: search command gets an error.
4063:
4064: The way @kbd{C-s @key{ESC}} works is that the @kbd{C-s} invokes
4065: incremental search, which is specially programmed to invoke nonincremental
4066: search if the argument you give it is empty. (Such an empty argument would
4067: otherwise be useless.) @kbd{C-r @key{ESC}} also works this way.
4068:
4069: @findex search-forward
4070: @findex search-backward
4071: Forward and backward nonincremental searches are implemented by the
4072: commands @code{search-forward} and @code{search-backward}. These commands
4073: may be bound to keys in the usual manner. The reason that incremental
4074: search is programmed to invoke them as well is that @kbd{C-s @key{ESC}}
4075: is the traditional sequence of characters used in Emacs to invoke
4076: nonincremental search.
4077:
4078: However, nonincremental searches performed using @kbd{C-s @key{ESC}} do
4079: not call @code{search-forward} right away. The first thing done is to see
4080: if the next character is @kbd{C-w}, which requests a word search.
4081: @ifinfo
4082: @xref{Word Search}.
4083: @end ifinfo
4084:
4085: @node Word Search, Regexp Search, Nonincremental Search, Search
4086: @section Word Search
4087: @cindex word search
4088:
4089: Word search searches for a sequence of words without regard to how the
4090: words are separated. More precisely, you type a string of many words,
4091: using single spaces to separate them, and the string can be found even if
4092: there are multiple spaces, newlines or other punctuation between the words.
4093:
4094: Word search is useful in editing documents formatted by text formatters.
4095: If you edit while looking at the printed, formatted version, you can't tell
4096: where the line breaks are in the source file. With word search, you can
4097: search without having to know them.
4098:
4099: @table @kbd
4100: @item C-s @key{ESC} C-w @var{words} @key{RET}
4101: Search for @var{words}, ignoring differences in punctuation.
4102: @item C-r @key{ESC} C-w @var{words} @key{RET}
4103: Search backward for @var{words}, ignoring differences in punctuation.
4104: @end table
4105:
4106: Word search is a special case of nonincremental search and is invoked
4107: with @kbd{C-s @key{ESC} C-w}. This is followed by the search string, which
4108: must always be terminated with @key{RET}. Being nonincremental, this
4109: search does not start until the argument is terminated. It works by
4110: constructing a regular expression and searching for that. @xref{Regexp
4111: Search}.
4112:
4113: A backward word search can be done by @kbd{C-r @key{ESC} C-w}.
4114:
4115: @findex word-search-forward
4116: @findex word-search-backward
4117: Forward and backward word searches are implemented by the commands
4118: @code{word-search-forward} and @code{word-search-backward}. These commands
4119: may be bound to keys in the usual manner. The reason that incremental
4120: search is programmed to invoke them as well is that @kbd{C-s @key{ESC} C-w}
4121: is the traditional Emacs sequence of keys for word search.
4122:
4123: @node Regexp Search, Regexps, Word Search, Search
4124: @section Regular Expression Search
4125: @cindex regular expression
4126: @cindex expressions, regular
4127: @cindex regexp
4128:
4129: A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
4130: denotes a set of strings, possibly an infinite set. Searching for matches
4131: for a regexp is a very powerful operation that editors on Unix systems have
4132: traditionally offered. In GNU Emacs, you can search for the next match for
4133: a regexp either incrementally or not.
4134:
4135: @kindex C-M-s
4136: @findex isearch-forward-regexp
4137: @findex isearch-backward-regexp
4138: Incremental search for a regexp is done by typing @kbd{C-M-s}
4139: (@code{isearch-forward-regexp}). This command reads a search string
4140: incrementally just like @kbd{C-s}, but it treats the search string as a
4141: regexp rather than looking for an exact match against the text in the
4142: buffer. Each time you add text to the search string, you make the regexp
4143: longer, and the new regexp is searched for. A reverse regexp search command,
4144: @code{isearch-backward-regexp}, also exists but no key runs it.
4145:
4146: All of the control characters that do special things within an ordinary
4147: incremental search have the same function in incremental regexp search.
4148: Typing @kbd{C-s} or @kbd{C-r} immediately after starting the search
4149: retrieves the last incremental search regexp used; that is to say,
4150: incremental regexp and non-regexp searches have independent defaults.
4151:
4152: Note that adding characters to the regexp in an incremental regexp search
4153: does not make the cursor move back and start again. Perhaps it ought to; I
4154: am not sure. As it stands, if you have searched for @samp{foo} and you
4155: add @samp{\|bar}, the search will not check for a @samp{bar} in the
4156: buffer before the @samp{foo}.
4157:
4158: @findex re-search-forward
4159: @findex re-search-backward
4160: Nonincremental search for a regexp is done by the functions
4161: @code{re-search-forward} and @code{re-search-backward}. You can invoke
4162: these with @kbd{M-x}, or bind them to keys. Also, you can call
4163: @code{re-search-forward} by way of incremental regexp search with
4164: @kbd{C-M-s @key{ESC}}.
4165:
4166: @node Regexps, Search Case, Regexp Search, Search
4167: @section Syntax of Regular Expressions
4168:
4169: Regular expressions have a syntax in which a few characters are special
4170: constructs and the rest are @dfn{ordinary}. An ordinary character is a
4171: simple regular expression which matches that character and nothing else.
4172: The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*},
4173: @samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}; no new special
4174: characters will be defined. Any other character appearing in a regular
4175: expression is ordinary, unless a @samp{\} precedes it.@refill
4176:
4177: For example, @samp{f} is not a special character, so it is ordinary, and
4178: therefore @samp{f} is a regular expression that matches the string @samp{f}
4179: and no other string. (It does @i{not} match the string @samp{ff}.) Likewise,
4180: @samp{o} is a regular expression that matches only @samp{o}.@refill
4181:
4182: Any two regular expressions @var{a} and @var{b} can be concatenated. The
4183: result is a regular expression which matches a string if @var{a} matches
4184: some amount of the beginning of that string and @var{b} matches the rest of
4185: the string.@refill
4186:
4187: As a simple example, we can concatenate the regular expressions @samp{f}
4188: and @samp{o} to get the regular expression @samp{fo}, which matches only
4189: the string @samp{fo}. Still trivial. To do something nontrivial, you
4190: need to use one of the special characters. Here is a list of them.
4191:
4192: @table @kbd
4193: @item .@: @r{(Period)}
4194: is a special character that matches any single character except a newline.
4195: Using concatenation, we can make regular expressions like @samp{a.b} which
4196: matches any three-character string which begins with @samp{a} and ends with
4197: @samp{b}.@refill
4198:
4199: @item *
4200: is not a construct by itself; it is a suffix, which means the
4201: preceding regular expression is to be repeated as many times as
4202: possible. In @samp{fo*}, the @samp{*} applies to the @samp{o}, so
4203: @samp{fo*} matches one @samp{f} followed by any number of @samp{o}s.
4204: The case of zero @samp{o}s is allowed: @samp{fo*} does match
4205: @samp{f}.@refill
4206:
4207: @samp{*} always applies to the @i{smallest} possible preceding
4208: expression. Thus, @samp{fo*} has a repeating @samp{o}, not a
4209: repeating @samp{fo}.@refill
4210:
4211: The matcher processes a @samp{*} construct by matching, immediately,
4212: as many repetitions as can be found. Then it continues with the rest
4213: of the pattern. If that fails, backtracking occurs, discarding some
4214: of the matches of the @samp{*}-modified construct in case that makes
4215: it possible to match the rest of the pattern. For example, matching
4216: @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
4217: tries to match all three @samp{a}s; but the rest of the pattern is
4218: @samp{ar} and there is only @samp{r} left to match, so this try fails.
4219: The next alternative is for @samp{a*} to match only two @samp{a}s.
4220: With this choice, the rest of the regexp matches successfully.@refill
4221:
4222: @item +
4223: Is a suffix character similar to @samp{*} except that it requires that
4224: the preceding expression be matched at least once. So, for example,
4225: @samp{ca+r} will match the strings @samp{car} and @samp{caaaar}
4226: but not the string @samp{cr}, whereas @samp{ca*r} would match all
4227: three strings.@refill
4228:
4229: @item ?
4230: Is a suffix character similar to @samp{*} except that it can match the
4231: preceding expression either once or not at all. For example,
4232: @samp{ca?r} will match @samp{car} or @samp{cr}; nothing else.
4233:
4234: @item [ @dots{} ]
4235: @samp{[} begins a @dfn{character set}, which is terminated by a
4236: @samp{]}. In the simplest case, the characters between the two form
4237: the set. Thus, @samp{[ad]} matches either one @samp{a} or one
4238: @samp{d}, and @samp{[ad]*} matches any string composed of just
4239: @samp{a}s and @samp{d}s (including the empty string), from which it
4240: follows that @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
4241: @samp{caddaar}, etc.@refill
4242:
4243: Character ranges can also be included in a character set, by writing
4244: two characters with a @samp{-} between them. Thus, @samp{[a-z]}
4245: matches any lower-case letter. Ranges may be intermixed freely with
4246: individual characters, as in @samp{[a-z$%.]}, which matches any lower
4247: case letter or @samp{$}, @samp{%} or period.@refill
4248:
4249: Note that the usual special characters are not special any more inside
4250: a character set. A completely different set of special characters
4251: exists inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
4252:
4253: To include a @samp{]} in a character set, you must make it the first
4254: character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
4255: include a @samp{-}, write @samp{---}, which is a range containing only
4256: @samp{-}. To include @samp{^}, make it other than the first character
4257: in the set.@refill
4258:
4259: @item [^ @dots{} ]
4260: @samp{[^} begins a @dfn{complement character set}, which matches any
4261: character except the ones specified. Thus, @samp{[^a-z0-9A-Z]}
4262: matches all characters @i{except} letters and digits.@refill
4263:
4264: @samp{^} is not special in a character set unless it is the first
4265: character. The character following the @samp{^} is treated as if it
4266: were first (@samp{-} and @samp{]} are not special there).
4267:
4268: Note that a complement character set can match a newline, unless
4269: newline is mentioned as one of the characters not to match.
4270:
4271: @item ^
4272: is a special character that matches the empty string, but only if at
4273: the beginning of a line in the text being matched. Otherwise it fails
4274: to match anything. Thus, @samp{^foo} matches a @samp{foo} which occurs
4275: at the beginning of a line.
4276:
4277: @item $
4278: is similar to @samp{^} but matches only at the end of a line. Thus,
4279: @samp{xx*$} matches a string of one @samp{x} or more at the end of a line.
4280:
4281: @item \
4282: has two functions: it quotes the special characters (including
4283: @samp{\}), and it introduces additional special constructs.
4284:
4285: Because @samp{\} quotes special characters, @samp{\$} is a regular
4286: expression which matches only @samp{$}, and @samp{\[} is a regular
4287: expression which matches only @samp{[}, and so on.@refill
4288: @end table
4289:
4290: Note: for historical compatibility, special characters are treated as
4291: ordinary ones if they are in contexts where their special meanings make no
4292: sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is
4293: no preceding expression on which the @samp{*} can act. It is poor practice
4294: to depend on this behavior; better to quote the special character anyway,
4295: regardless of where is appears.@refill
4296:
4297: For the most part, @samp{\} followed by any character matches only
4298: that character. However, there are several exceptions: characters
4299: which, when preceded by @samp{\}, are special constructs. Such
4300: characters are always ordinary when encountered on their own. Here
4301: is a table of @samp{\} constructs.
4302:
4303: @table @kbd
4304: @item \|
4305: specifies an alternative.
4306: Two regular expressions @var{a} and @var{b} with @samp{\|} in
4307: between form an expression that matches anything that either @var{a} or
4308: @var{b} will match.@refill
4309:
4310: Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
4311: but no other string.@refill
4312:
4313: @samp{\|} applies to the largest possible surrounding expressions. Only a
4314: surrounding @samp{$ @dots{} $} grouping can limit the grouping power of
4315: @samp{\|}.@refill
4316:
4317: Full backtracking capability exists to handle multiple uses of @samp{\|}.
4318:
4319: @item $ @dots{} $
4320: is a grouping construct that serves three purposes:
4321:
4322: @enumerate
4323: @item
4324: To enclose a set of @samp{\|} alternatives for other operations.
4325: Thus, @samp{$foo\|bar$x} matches either @samp{foox} or @samp{barx}.
4326:
4327: @item
4328: To enclose a complicated expression for the postfix @samp{*} to operate on.
4329: Thus, @samp{ba$na$*} matches @samp{bananana}, etc., with any (zero or
4330: more) number of @samp{na} strings.@refill
4331:
4332: @item
4333: To mark a matched substring for future reference.
4334:
4335: @end enumerate
4336:
4337: This last application is not a consequence of the idea of a
4338: parenthetical grouping; it is a separate feature which happens to be
4339: assigned as a second meaning to the same @samp{$ @dots{} $} construct
4340: because there is no conflict in practice between the two meanings.
4341: Here is an explanation of this feature:
4342:
4343: @item \@var{digit}
4344: after the end of a @samp{$ @dots{} $} construct, the matcher remembers the
4345: beginning and end of the text matched by that construct. Then, later on
4346: in the regular expression, you can use @samp{\} followed by @var{digit}
4347: to mean ``match the same text matched the @var{digit}'th time by the
4348: @samp{$ @dots{} $} construct.''@refill
4349:
4350: The strings matching the first nine @samp{$ @dots{} $} constructs appearing
4351: in a regular expression are assigned numbers 1 through 9 in order that the
4352: open-parentheses appear in the regular expression. @samp{\1} through
4353: @samp{\9} may be used to refer to the text matched by the corresponding
4354: @samp{$ @dots{} $} construct.
4355:
4356: For example, @samp{$.*$\1} matches any newline-free string that is
4357: composed of two identical halves. The @samp{$.*$} matches the first
4358: half, which may be anything, but the @samp{\1} that follows must match
4359: the same exact text.
4360:
4361: @item \`
4362: matches the empty string, provided it is at the beginning
4363: of the buffer.
4364:
4365: @item \'
4366: matches the empty string, provided it is at the end of
4367: the buffer.
4368:
4369: @item \b
4370: matches the empty string, provided it is at the beginning or
4371: end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
4372: @samp{foo} as a separate word. @samp{\bballs?\b} matches
4373: @samp{ball} or @samp{balls} as a separate word.@refill
4374:
4375: @item \B
4376: matches the empty string, provided it is @i{not} at the beginning or
4377: end of a word.
4378:
4379: @item \<
4380: matches the empty string, provided it is at the beginning of a word.
4381:
4382: @item \>
4383: matches the empty string, provided it is at the end of a word.
4384:
4385: @item \w
4386: matches any word-constituent character. The editor syntax table
4387: determines which characters these are.
4388:
4389: @item \W
4390: matches any character that is not a word-constituent.
4391:
4392: @item \s@var{code}
4393: matches any character whose syntax is @var{code}. @var{code} is a
4394: character which represents a syntax code: thus, @samp{w} for word
4395: constituent, @samp{-} for whitespace, @samp{(} for open-parenthesis,
4396: etc. @xref{Syntax}.@refill
4397:
4398: @item \S@var{code}
4399: matches any character whose syntax is not @var{code}.
4400: @end table
4401:
4402: Here is a complicated regexp, used by Emacs to recognize the end of a
4403: sentence together with any whitespace that follows. It is given in Lisp
4404: syntax to enable you to distinguish the spaces from the tab characters. In
4405: Lisp syntax, the string constant begins and ends with a double-quote.
4406: @samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a
4407: backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a
4408: newline.
4409:
4410: @example
4411: "[.?!][]\"')]*\$$\\|\t\\| \$[ \t\n]*"
4412: @end example
4413:
4414: @noindent
4415: This contains four parts in succession: a character set matching period,
4416: @samp{?} or @samp{!}; a character set matching close-brackets,
4417: quotes or parentheses, repeated any number of times; an alternative in
4418: backslash-parentheses that matches end-of-line, a tab or two spaces; and a
4419: character set matching whitespace characters, repeated any number of times.
4420:
4421: Note that the above example shows how to write this regexp when
4422: entering it as part of an Emacs Lisp program. To enter the same regexp
4423: in an interactive command such as @code{re-search-forward} you must
4424: spell it differently:
4425:
4426: @example
4427: [.?!][]"')]*$$\|^Q^I\| $[ ^Q^I^Q^J]*
4428: @end example
4429:
4430: @node Search Case, Replace, Regexps, Search
4431: @section Searching and Case
4432:
4433: @vindex case-fold-search
4434: All sorts of searches in Emacs normally ignore the case of the text they
4435: are searching through; if you specify searching for @samp{FOO}, then
4436: @samp{Foo} and @samp{foo} are also considered a match. Regexps, and in
4437: particular character sets, are included: @samp{[aB]} would match @samp{a}
4438: or @samp{A} or @samp{b} or @samp{B}.@refill
4439:
4440: If you do not want this feature, set the variable @code{case-fold-search}
4441: to @code{nil}. Then all letters must match exactly, including case. This
4442: is a per-buffer variable; altering the variable affects only the current
4443: buffer, but there is a default value which you can change as well.
4444: @xref{Locals}.
4445:
4446: @node Replace, Other Repeating Search, Search Case, Search
4447: @section Replacement Commands
4448: @cindex replacement
4449: @cindex string substitution
4450: @cindex global substitution
4451:
4452: Global search-and-replace operations are not needed as often in Emacs as
4453: they are in other editors, but they are available. In addition to the
4454: simple @code{replace-string} command which is like that found in most
4455: editors, there is a @code{query-replace} command which asks you, for each
4456: occurrence of the pattern, whether to replace it.
4457:
4458: The replace commands all replace one string (or regexp) with one
4459: replacement string. It is possible to perform several replacements in
4460: parallel using the command @code{expand-region-abbrevs}. @xref{Expanding
4461: Abbrevs}.
4462:
4463: @menu
4464: * Unconditional Replace:: Replacing all matches for a string.
4465: * Regexp Replace:: Replacing all matches for a regexp.
4466: * Replacement and Case:: How replacements preserve case of letters.
4467: * Query Replace:: How to use querying.
4468: @end menu
4469:
4470: @node Unconditional Replace, Regexp Replace, Replace, Replace
4471: @subsection Unconditional Replacement
4472: @findex replace-string
4473: @findex replace-regexp
4474:
4475: @table @kbd
4476: @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
4477: Replace every occurrence of @var{string} with @var{newstring}.
4478: @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
4479: Replace every match for @var{regexp} with @var{newstring}.
4480: @end table
4481:
4482: To replace every instance of @samp{foo} after point with @samp{bar}, use
4483: the command @kbd{M-x replace-string} with the two arguments @samp{foo} and
4484: @samp{bar}. Replacement occurs only after point, so if you want to cover
4485: the whole buffer you must go to the beginning first. All occurrences up to
4486: the end of the buffer are replaced; to limit replacement to part of the
4487: buffer, narrow to that part of the buffer before doing the replacement
4488: (@pxref{Narrowing}).
4489:
4490: When @code{replace-string} exits, point is left at the last occurrence
4491: replaced. The value of point when the @code{replace-string} command was
4492: issued is remembered on the mark ring; @kbd{C-u C-@key{SPC}} moves back
4493: there.
4494:
4495: A numeric argument restricts replacement to matches that are surrounded
4496: by word boundaries.
4497:
4498: @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
4499: @subsection Regexp Replacement
4500:
4501: @code{replace-string} replaces exact matches for a single string. The
4502: similar command @code{replace-regexp} replaces any match for a specified
4503: pattern.
4504:
4505: In @code{replace-regexp}, the @var{newstring} need not be constant. It
4506: can refer to all or part of what is matched by the @var{regexp}. @samp{\&}
4507: in @var{newstring} stands for the entire text being replaced.
4508: @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for
4509: whatever matched the @var{d}'th parenthesized grouping in @var{regexp}.
4510: For example,@refill
4511:
4512: @example
4513: M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
4514: @end example
4515:
4516: @noindent
4517: would replace (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
4518: with @samp{cddr-safe}.
4519:
4520: @example
4521: M-x replace-regexp @key{RET} $c[ad]+r$-safe @key{RET} \1 @key{RET}
4522: @end example
4523:
4524: @noindent
4525: would perform exactly the opposite replacements. To include a @samp{\}
4526: in the text to replace with, you must give @samp{\\}.
4527:
4528: @node Replacement and Case, Query Replace, Regexp Replace, Replace
4529: @subsection Replace Commands and Case
4530:
4531: @vindex case-replace
4532: @vindex case-fold-search
4533: If the arguments to a replace command are in lower case, it preserves
4534: case when it makes a replacement. Thus, the command
4535:
4536: @example
4537: M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
4538: @end example
4539:
4540: @noindent
4541: replaces a lower case @samp{foo} with a lower case @samp{bar}, @samp{FOO}
4542: with @samp{BAR}, and @samp{Foo} with @samp{Bar}. If upper case letters are
4543: used in the second argument, they remain upper case every time that
4544: argument is inserted. If upper case letters are used in the first
4545: argument, the second argument is always substituted exactly as given, with
4546: no case conversion. Likewise, if the variable @code{case-replace} is set
4547: to @code{nil}, replacement is done without case conversion. If
4548: @code{case-fold-search} is set to @code{nil}, case is significant in
4549: matching occurrences of @samp{foo} to replace; also, case conversion of the
4550: replacement string is not done.
4551:
4552: @node Query Replace,, Replacement and Case, Replace
4553: @subsection Query Replace
4554: @cindex query replace
4555:
4556: @table @kbd
4557: @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
4558: @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
4559: Replace some occurrences of @var{string} with @var{newstring}.
4560: @item M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
4561: Replace some matches for @var{regexp} with @var{newstring}.
4562: @end table
4563:
4564: @kindex M-%
4565: @findex query-replace
4566: If you want to change only some of the occurrences of @samp{foo} to
4567: @samp{bar}, not all of them, then you cannot use an ordinary
4568: @code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}).
4569: This command finds occurrences of @samp{foo} one by one, displays each
4570: occurrence and asks you whether to replace it. A numeric argument to
4571: @code{query-replace} tells it to consider only occurrences that are bounded
4572: by word-delimiter characters.@refill
4573:
4574: @findex query-replace-regexp
4575: Aside from querying, @code{query-replace} works just like
4576: @code{replace-string}, and @code{query-replace-regexp} works
4577: just like @code{replace-regexp}.@refill
4578:
4579: The things you can type when you are shown an occurrence of @var{string}
4580: or a match for @var{regexp} are:
4581:
4582: @kindex SPC (query-replace)
4583: @kindex DEL (query-replace)
4584: @kindex , (query-replace)
4585: @kindex ESC (query-replace)
4586: @kindex . (query-replace)
4587: @kindex ! (query-replace)
4588: @kindex ^ (query-replace)
4589: @kindex C-r (query-replace)
4590: @kindex C-w (query-replace)
4591: @kindex C-l (query-replace)
4592:
4593: @c WideCommands
4594: @table @kbd
4595: @item @key{SPC}
4596: to replace the occurrence with @var{newstring}. This preserves case, just
4597: like @code{replace-string}, provided @code{case-replace} is non-@code{nil},
4598: as it normally is.@refill
4599:
4600: @item @key{DEL}
4601: to skip to the next occurrence without replacing this one.
4602:
4603: @item , @r{(Comma)}
4604: to replace this occurrence and display the result. You are then asked
4605: for another input character, except that since the replacement has
4606: already been made, @key{DEL} and @key{SPC} are equivalent. You could
4607: type @kbd{C-r} at this point (see below) to alter the replaced text. You
4608: could also type @kbd{C-x u} to undo the replacement; this exits the
4609: @code{query-replace}, so if you want to do further replacement you must use
4610: @kbd{C-x ESC} to restart (@pxref{Repetition}).
4611:
4612: @item @key{ESC}
4613: to exit without doing any more replacements.
4614:
4615: @item .@: @r{(Period)}
4616: to replace this occurrence and then exit.
4617:
4618: @item !
4619: to replace all remaining occurrences without asking again.
4620:
4621: @item ^
4622: to go back to the location of the previous occurrence (or what used to
4623: be an occurrence), in case you changed it by mistake. This works by
4624: popping the mark ring. Only one @kbd{^} in a row is allowed, because
4625: only one previous replacement location is kept during @code{query-replace}.
4626:
4627: @item C-r
4628: to enter a recursive editing level, in case the occurrence needs to be
4629: edited rather than just replaced with @var{newstring}. When you are
4630: done, exit the recursive editing level with @kbd{C-M-c} and the next
4631: occurrence will be displayed. @xref{Recursive Edit}.
4632:
4633: @item C-w
4634: to delete the occurrence, and then enter a recursive editing level as
4635: in @kbd{C-r}. Use the recursive edit to insert text to replace the
4636: deleted occurrence of @var{string}. When done, exit the recursive
4637: editing level with @kbd{C-M-c} and the next occurrence will be
4638: displayed.
4639:
4640: @item C-l
4641: to redisplay the screen and then give another answer.
4642:
4643: @item C-h
4644: to display a message summarizing these options, then give another
4645: answer.
4646: @end table
4647:
4648: If you type any other character, the @code{query-replace} is exited, and
4649: the character executed as a command. To restart the @code{query-replace},
4650: use @kbd{C-x @key{ESC}}, which repeats the @code{query-replace} because it
4651: used the minibuffer to read its arguments. @xref{Repetition, C-x ESC}.
4652:
4653: To replace every occurrence, you can start @code{query-replace} at the
4654: beginning of the buffer and type @kbd{!}, or you can use the
4655: @code{replace-string} command at the beginning of the buffer. To
4656: replace every occurrence in a part of the buffer, narrow to that part
4657: and then run @code{replace-string} or @code{query-replace} at the
4658: beginning of it. @xref{Narrowing}.
4659:
4660: @node Other Repeating Search,, Replace, Search
4661: @section Other Search-and-Loop Commands
4662:
4663: Here are some other commands that find matches for a regular expression.
4664: They all operate from point to the end of the buffer.
4665:
4666: @findex list-matching-lines
4667: @findex occur
4668: @findex count-matches
4669: @findex delete-non-matching-lines
4670: @findex delete-matching-lines
4671: @c grosscommands
4672: @table @kbd
4673: @item M-x occur
4674: Print each line that follows point and contains a match for the
4675: specified regexp. A numeric argument specifies the number of context
4676: lines to print before and after each matching line; the default is
4677: none.
4678:
4679: @kindex C-c C-c (Occur mode)
4680: The buffer @samp{*Occur*} containing the output serves as a menu for
4681: finding the occurrences in their original context. Find an occurrence
4682: as listed in @samp{*Occur*}, position point there and type @kbd{C-c
4683: C-c}; this switches to the buffer that was searched and moves point to
4684: the original of the same occurrence.
4685:
4686: @item M-x list-matching-lines
4687: Synonym for @kbd{M-x occur}.
4688:
4689: @item M-x count-matches
4690: Print the number of matches following point for the specified regexp.
4691:
4692: @item M-x delete-non-matching-lines
4693: Delete each line that follows point and does not contain a match for
4694: the specified regexp.
4695:
4696: @item M-x delete-matching-lines
4697: Delete each line that follows point and contains a match for the
4698: specified regexp.
4699: @end table
4700:
4701: @node Fixit, Files, Search, Top
4702: @chapter Commands for Fixing Typos
4703: @cindex typos
4704: @cindex mistakes, correcting
4705:
4706: In this chapter we describe the commands that are especially useful for
4707: the times when you catch a mistake in your text just after you have made
4708: it, or change your mind while composing text on line.
4709:
4710: @menu
4711: * Kill Errors:: Commands to kill a batch of recently entered text.
4712: * Transpose:: Exchanging two characters, words, lines, lists...
4713: * Fixing Case:: Correcting case of last word entered.
4714: * Spelling:: Apply spelling checker to a word, or a whole file.
4715: @end menu
4716:
4717: @node Kill Errors, Transpose, Fixit, Fixit
4718: @section Killing Your Mistakes
4719:
4720: @table @kbd
4721: @item @key{DEL}
4722: Delete last character (@code{delete-backward-char}).
4723: @item M-@key{DEL}
4724: Kill last word (@code{backward-kill-word}).
4725: @item C-x @key{DEL}
4726: Kill to beginning of sentence (@code{backward-kill-sentence}).
4727: @end table
4728:
4729: @kindex DEL
4730: @findex delete-backward-char
4731: The @key{DEL} character (@code{delete-backward-char}) is the most
4732: important correction command. When used among graphic (self-inserting)
4733: characters, it can be thought of as canceling the last character typed.
4734:
4735: @kindex M-DEL
4736: @kindex C-x DEL
4737: @findex backward-kill-word
4738: @findex backward-kill-sentence
4739: When your mistake is longer than a couple of characters, it might be more
4740: convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}.
4741: @kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x
4742: @key{DEL}} kills back to the start of the last sentence. @kbd{C-x
4743: @key{DEL}} is particularly useful when you are thinking of what to write as
4744: you type it, in case you change your mind about phrasing.
4745: @kbd{M-@key{DEL}} and @kbd{C-x @key{DEL}} save the killed text for
4746: @kbd{C-y} and @kbd{M-y} to retrieve. @xref{Yanking}.@refill
4747:
4748: @kbd{M-@key{DEL}} is often useful even when you have typed only a few
4749: characters wrong, if you know you are confused in your typing and aren't
4750: sure exactly what you typed. At such a time, you cannot correct with
4751: @key{DEL} except by looking at the screen to see what you did. It requires
4752: less thought to kill the whole word and start over again.
4753:
4754: @node Transpose, Fixing Case, Kill Errors, Fixit
4755: @section Transposing Text
4756:
4757: @table @kbd
4758: @item C-t
4759: Transpose two characters (@code{transpose-chars}).
4760: @item M-t
4761: Transpose two words (@code{transpose-words}).
4762: @item C-M-t
4763: Transpose two balanced expressions (@code{transpose-sexps}).
4764: @item C-x C-t
4765: Transpose two lines (@code{transpose-lines}).
4766: @end table
4767:
4768: @cindex transposition
4769: @kindex C-t
4770: @findex transpose-chars
4771: The common error of transposing two characters can be fixed, when they
4772: are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally,
4773: @kbd{C-t} transposes the two characters on either side of point. When
4774: given at the end of a line, rather than transposing the last character of
4775: the line with the newline, which would be useless, @kbd{C-t} transposes the
4776: last two characters on the line. So, if you catch your transposition error
4777: right away, you can fix it with just a @kbd{C-t}. If you don't catch it so
4778: fast, you must move the cursor back to between the two transposed
4779: characters. If you transposed a space with the last character of the word
4780: before it, the word motion commands are a good way of getting there.
4781: Otherwise, a reverse search (@kbd{C-r}) is often the best way.
4782: @xref{Search}.
4783:
4784:
4785: @kindex C-x C-t
4786: @findex transpose-lines
4787: @kindex M-t
4788: @findex transpose-words
4789: @kindex C-M-t
4790: @findex transpose-sexps
4791: @kbd{Meta-t} (@code{transpose-words}) transposes the word before point
4792: with the word after point. It moves point forward over a word, dragging
4793: the word preceding or containing point forward as well. The punctuation
4794: characters between the words do not move. For example, @w{@samp{FOO, BAR}}
4795: transposes into @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.
4796:
4797: @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing
4798: two expressions (@pxref{Lists}), and @kbd{C-x C-t} (@code{transpose-lines})
4799: exchanges lines. They work like @kbd{M-t} except in determining the
4800: division of the text into syntactic units.
4801:
4802: A numeric argument to a transpose command serves as a repeat count: it
4803: tells the transpose command to move the character (word, sexp, line) before
4804: or containing point across several other characters (words, sexps, lines).
4805: For example, @kbd{C-u 3 C-t} moves the character before point forward
4806: across three other characters. This is equivalent to repeating @kbd{C-t}
4807: three times. @kbd{C-u - 4 M-t} moves the word before point backward across
4808: four words. @kbd{C-u - C-M-t} would cancel the effect of plain
4809: @kbd{C-M-t}.@refill
4810:
4811: A numeric argument of zero is assigned a special meaning (because
4812: otherwise a command with a repeat count of zero would do nothing): to
4813: transpose the character (word, sexp, line) ending after point with the
4814: one ending after the mark.
4815:
4816: @node Fixing Case, Spelling, Transpose, Fixit
4817: @section Case Conversion
4818:
4819: @table @kbd
4820: @item M-- M-l
4821: Convert last word to lower case. Note @kbd{Meta--} is Meta-minus.
4822: @item M-- M-u
4823: Convert last word to all upper case.
4824: @item M-- M-c
4825: Convert last word to lower case with capital initial.
4826: @end table
4827:
4828: @findex downcase-word
4829: @findex upcase-word
4830: @findex capitalize-word
4831: @kindex M-@t{-} M-l
4832: @kindex M-@t{-} M-u
4833: @kindex M-@t{-} M-c
4834: @cindex case conversion
4835: @cindex words
4836: A very common error is to type words in the wrong case. Because of this,
4837: the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a
4838: special feature when used with a negative argument: they do not move the
4839: cursor. As soon as you see you have mistyped the last word, you can simply
4840: case-convert it and go on typing. @xref{Case}.@refill
4841:
4842: @node Spelling,, Fixing Case, Fixit
4843: @section Checking and Correcting Spelling
4844: @cindex spelling
4845:
4846: @c doublewidecommands
4847: @table @kbd
4848: @item M-$
4849: Check and correct spelling of word (@code{spell-word}).
4850: @item M-x spell-buffer
4851: Check and correct spelling of each word in the buffer.
4852: @item M-x spell-region
4853: Check and correct spelling of each word in the region.
4854: @item M-x spell-string
4855: Check spelling of specified word.
4856: @end table
4857:
4858: @kindex M-$
4859: @findex spell-word
4860: To check the spelling of the word before point, and optionally correct it
4861: as well, use the command @kbd{M-$} (@code{spell-word}). This command runs
4862: an inferior process containing the @code{spell} program to see whether the
4863: word is correct English. If it is not, it asks you to edit the word (in
4864: the minibuffer) into a corrected spelling, and then does a @code{query-replace}
4865: to substitute the corrected spelling for the old one throughout the buffer.
4866:
4867: If you exit the minibuffer without altering the original spelling, it
4868: means you do not want to do anything to that word. Then the @code{query-replace}
4869: is not done.
4870:
4871: @findex spell-buffer
4872: @kbd{M-x spell-buffer} checks each word in the buffer the same way that
4873: @code{spell-word} does, doing a @code{query-replace} if appropriate for
4874: every incorrect word.@refill
4875:
4876: @findex spell-region
4877: @kbd{M-x spell-region} is similar but operates only on the region, not
4878: the entire buffer.
4879:
4880: @findex spell-string
4881: @kbd{M-x spell-string} reads a string as an argument and checks whether
4882: that is a correctly spelled English word. It prints in the echo area a
4883: message giving the answer.
4884:
4885: @node Files, Buffers, Fixit, Top
4886: @chapter File Handling
4887: @cindex files
4888:
4889: The basic unit of stored data in Unix is the @dfn{file}. To edit a file,
4890: you must tell Emacs to examine the file and prepare a buffer containing a
4891: copy of the file's text. This is called @dfn{visiting} the file. Editing
4892: commands apply directly to text in the buffer; that is, to the copy inside
4893: Emacs. Your changes appear in the file itself only when you @dfn{save} the
4894: buffer back into the file.
4895:
4896: In addition to visiting and saving files, Emacs can delete, copy, rename,
4897: and append to files, and operate on file directories.
4898:
4899: @menu
4900: * File Names:: How to type and edit file name arguments.
4901: * Visiting:: Visiting a file prepares Emacs to edit the file.
4902: * Saving:: Saving makes your changes permanent.
4903: * Reverting:: Reverting cancels all the changes not saved.
4904: * Auto Save:: Auto Save periodically protects against loss of data.
4905: * ListDir:: Listing the contents of a file directory.
4906: * Dired:: ``Editing'' a directory to delete, rename, etc.
4907: the files in it.
4908: * Misc File Ops:: Other things you can do on files.
4909: @end menu
4910:
4911: @node File Names, Visiting, Files, Files
4912: @section File Names
4913: @cindex file names
4914:
4915: Most Emacs commands that operate on a file require you to specify the
4916: file name. (Saving and reverting are exceptions; the buffer knows which
4917: file name to use for them.) File names are specified using the minibuffer
4918: (@pxref{Minibuffer}). @dfn{Completion} is available, to make it easier to
4919: specify long file names. @xref{Completion}.
4920:
4921: There is always a @dfn{default file name} which will be used if you type
4922: just @key{RET}, entering an empty argument. Normally the default file name
4923: is the name of the file visited in the current buffer; this makes it easy
4924: to operate on that file with any of the Emacs file commands.
4925:
4926: @vindex default-directory
4927: Each buffer has a default directory, normally the same as the directory
4928: of the file visited in that buffer. When Emacs reads a file name, if you
4929: do not specify a directory, the default directory is used. If you specify
4930: a directory in a relative fashion, with a name that does not start with a
4931: slash, it is interpreted with respect to the default directory. The
4932: default directory is kept in the variable @code{default-directory}, which
4933: has a separate value in every buffer.
4934:
4935: For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then
4936: the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo},
4937: which does not specify a directory, it is short for @file{/u/rms/gnu/foo}.
4938: @samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo}
4939: would stand for the filename @file{/u/rms/gnu/new/foo}.
4940:
4941: The command @kbd{M-x pwd} prints the current buffer's default directory,
4942: and the command @kbd{M-x cd} sets it (to a value read using the
4943: minibuffer). A buffer's default directory changes only when the @code{cd}
4944: command is used. A file-visiting buffer's default directory is initialized
4945: to the directory of the file that is visited there. If a buffer is made
4946: randomly with @kbd{C-x b}, its default directory is copied from that of the
4947: buffer that was current at the time.
4948:
4949: @vindex insert-default-directory
4950: The default directory actually appears in the minibuffer when the
4951: minibuffer becomes active to read a file name. This serves two purposes:
4952: it shows you what the default is, so that you can type a relative file name
4953: and know with certainty what it will mean, and it allows you to edit the
4954: default to specify a different directory. This insertion of the default
4955: directory is inhibited if the variable @code{insert-default-directory} is
4956: set to @code{nil}.
4957:
4958: Note that it is legitimate to type an absolute file name after you enter
4959: the minibuffer, ignoring the presence of the default directory name as part
4960: of the text. The final minibuffer contents may look invalid, but that is
4961: not so. @xref{Minibuffer File}.
4962:
4963: @samp{$} in a file name is used to substitute environment variables. For
4964: example, if you have used the C shell command @samp{setenv FOO
4965: rms/hacks} to set up an environment variable named @samp{FOO}, then
4966: you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an
4967: abbreviation for @file{/u/rms/hacks/test.c}. (In the Bourne-Again
4968: shell, write @code{export FOO=rms/hacks} to define @code{FOO}.) The
4969: environment variable name consists of all the alphanumeric characters
4970: after the @samp{$}; alternatively, it may be enclosed in braces after
4971: the @samp{$}. Note that the @samp{setenv} command affects Emacs only
4972: if done before Emacs is started.
4973: @ignore
4974: In @code{sh}
4975:
4976: @example
4977: FOO=rms/hacks
4978: export FOO
4979: @end example
4980: @end ignore
4981:
4982: To access a file with @samp{$} in its name, type @samp{$$}. This pair
4983: is converted to a single @samp{$} at the same time as variable substitution
4984: is performed for single @samp{$}. The Lisp function that performs the
4985: substitution is called @code{substitute-in-file-name}. The substitution
4986: is performed only on filenames read as such using the minibuffer.
4987:
4988: @node Visiting, Saving, File Names, Files
4989: @section Visiting Files
4990: @cindex visiting files
4991:
4992: @c WideCommands
4993: @table @kbd
4994: @item C-x C-f
4995: Visit a file (@code{find-file}).
4996: @item C-x C-v
4997: Visit a different file instead of the one visited last
4998: (@code{find-alternate-file}).
4999: @item C-x 4 C-f
5000: Visit a file, in another window (@code{find-file-other-window}). Don't
5001: change this window.
5002: @end table
5003:
5004: @cindex files
5005: @cindex visiting
5006: @cindex saving
5007: @dfn{Visiting} a file means copying its contents into Emacs where you can
5008: edit them. Emacs makes a new buffer for each file that you visit. We say
5009: that the buffer is visiting the file that it was created to hold. Emacs
5010: constructs the buffer name from the file name by throwing away the
5011: directory, keeping just the name proper. For example, a file named
5012: @file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}. If
5013: there is already a buffer with that name, a unique name is constructed by
5014: appending @samp{<2>}, @samp{<3>}, or so on, using the lowest number that
5015: makes a name that is not already in use.
5016:
5017: Each window's mode line shows the name of the buffer that is being displayed
5018: in that window, so you can always tell what buffer you are editing.
5019:
5020: The changes you make with Emacs are made in the Emacs buffer. They do
5021: not take effect in the file that you visited, or any place permanent, until
5022: you @dfn{save} the buffer. Saving the buffer means that Emacs writes the
5023: current contents of the buffer into its visited file. @xref{Saving}.
5024:
5025: @cindex modified (buffer)
5026: If a buffer contains changes that have not been saved, the buffer is said
5027: to be @dfn{modified}. This is important because it implies that some
5028: changes will be lost if the buffer is not saved. The mode line displays
5029: two stars near the left margin if the buffer is modified.
5030:
5031: @kindex C-x C-f
5032: @findex find-file
5033: To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow
5034: the command with the name of the file you wish to visit, terminated by a
5035: @key{RET}.
5036:
5037: The file name is read using the minibuffer (@pxref{Minibuffer}), with
5038: defaulting and completion in the standard manner (@pxref{File Names}).
5039: While in the minibuffer, you can abort @w{@kbd{C-x C-f}} by typing @kbd{C-g}.
5040:
5041: Your confirmation that @kbd{C-x C-f} has completed successfully is the
5042: appearance of new text on the screen and a new buffer name in the mode
5043: line. If the specified file does not exist and could not be created, or
5044: cannot be read, then an error results. The error message is printed in the
5045: echo area, and includes the file name which Emacs was trying to visit.
5046:
5047: If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
5048: another copy. It selects the existing buffer containing that file.
5049: However, before doing so, it checks that the file itself has not changed
5050: since you visited or saved it last. If the file has changed, a warning
5051: message is printed. @xref{Interlocking,,Simultaneous Editing}.
5052:
5053: @cindex creating files
5054: What if you want to create a file? Just visit it. Emacs prints
5055: @samp{(New File)} in the echo area, but in other respects behaves as if you
5056: had visited an existing empty file. If you make any changes and save them,
5057: the file is created.
5058:
5059: @kindex C-x C-v
5060: @findex find-alternate-file
5061: If you visit a nonexistent file unintentionally (because you typed the
5062: wrong file name), use the @kbd{C-x C-v} (@code{find-alternate-file})
5063: command to visit the file you wanted. @kbd{C-x C-v} is similar to @kbd{C-x
5064: C-f}, but it kills the current buffer (after first offering to save it if
5065: it is modified). @kbd{C-x C-v} is allowed even if the current buffer
5066: is not visiting a file.
5067:
5068: @vindex find-file-run-dired
5069: If the file you specify is actually a directory, Dired is called on that
5070: directory (@pxref{Dired}). This can be inhibited by setting the variable
5071: @code{find-file-run-dired} to @code{nil}; then it is an error to try to
5072: visit a directory.
5073:
5074: @kindex C-x 4 f
5075: @findex find-file-other-window
5076: @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
5077: except that the buffer containing the specified file is selected in another
5078: window. The window that was selected before @kbd{C-x 4 f} continues to
5079: show the same buffer it was already showing. If this command is used when
5080: only one window is being displayed, that window is split in two, with one
5081: window showing the same before as before, and the other one showing the
5082: newly requested file. @xref{Windows}.
5083:
5084: @cindex hooks for files
5085: @vindex find-file-hooks
5086: @vindex find-file-not-found-hooks
5087: There are two hook variables that allow extensions to modify the
5088: operation of visiting files. Visiting a file that does not exist runs the
5089: functions in the list @code{find-file-not-found-hooks}; the value of this
5090: variable is expected to be a list of functions, and the functions are
5091: called one by one until one of them returns non-@code{nil}. Any visiting
5092: of a file, whether extant or not, expects @code{find-file-hooks} to
5093: contain a list of functions and calls them all, one by one. In both cases
5094: the functions receive no arguments. Visiting a nonexistent file
5095: runs the @code{find-file-not-found-hooks} first.
5096:
5097: You can put a local variable specification at the end of a file which
5098: specifies values for Emacs local variables whenever you visit the file.
5099: @xref{File Variables}.
5100:
5101: @node Saving, Reverting, Visiting, Files
5102: @section Saving Files
5103:
5104: @dfn{Saving} a buffer in Emacs means writing its contents back into the file
5105: that was visited in the buffer.
5106:
5107: @table @kbd
5108: @item C-x C-s
5109: Save the current buffer in its visited file (@code{save-buffer}).
5110: @item C-x s
5111: Save any or all buffers in their visited files (@code{save-some-buffers}).
5112: @item M-~
5113: @c !!! added @* to prevent overfull hbox
5114: Forget that the current buffer has been changed@*(@code{not-modified}).
5115: @item C-x C-w
5116: Save the current buffer in a specified file, and record that file as
5117: the one visited in the buffer (@code{write-file}).
5118: @item M-x set-visited-file-name
5119: Change file the name under which the current buffer will be saved.
5120: @end table
5121:
5122: @kindex C-x C-s
5123: @findex save-buffer
5124: When you wish to save the file and make your changes permanent, type
5125: @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
5126: prints a message such as
5127:
5128: @example
5129: Wrote /u/rms/gnu/gnu.tasks
5130: @end example
5131:
5132: @noindent
5133: If the selected buffer is not modified (no changes have been made in it
5134: since the buffer was created or last saved), saving is not really done,
5135: because it would have no effect. Instead, @kbd{C-x C-s} prints a message
5136: in the echo area saying
5137:
5138: @example
5139: (No changes need to be written)
5140: @end example
5141:
5142: @kindex C-x s
5143: @findex save-some-buffers
5144: The command @kbd{C-x s} (@code{save-some-buffers}) can save any or all modified
5145: buffers. First it asks, for each modified buffer, whether to save it.
5146: These questions should be answered with @kbd{y} or @kbd{n}. @kbd{C-x C-c},
5147: the key that kills Emacs, invokes @code{save-some-buffers} and therefore
5148: asks the same questions.
5149:
5150: @kindex M-~
5151: @findex not-modified
5152: If you have changed a buffer and do not want the changes to be saved, you
5153: should take some action to prevent it. Otherwise, each time you use
5154: @code{save-some-buffers} you are liable to save it by mistake. One thing
5155: you can do is type @kbd{M-~} (@code{not-modified}), which clears out the
5156: indication that the buffer is modified. If you do this, none of the save
5157: commands will believe that the buffer needs to be saved. (@samp{~} is often
5158: used as a mathematical symbol for `not'; thus @kbd{Meta-~} is `not', metafied.)
5159: You could also use @code{set-visited-file-name} (see below) to mark the
5160: buffer as visiting a different file name, one which is not in use for
5161: anything important. Alternatively, you can undo all the changes made since
5162: the file was visited or saved, by reading the text from the file again.
5163: This is called @dfn{reverting}. @xref{Reverting}. You could also undo all
5164: the changes by repeating the undo command @kbd{C-x u} until you have undone
5165: all the changes; but this only works if you have not made more changes than
5166: the undo mechanism can remember.
5167:
5168: @findex set-visited-file-name
5169: @kbd{M-x set-visited-file-name} alters the name of the file that the
5170: current buffer is visiting. It reads the new file name using the
5171: minibuffer. It can be used on a buffer that is not visiting a file, too.
5172: The buffer's name is changed to correspond to the file it is now visiting
5173: in the usual fashion (unless the new name is in use already for some other
5174: buffer; in that case, the buffer name is not changed).
5175: @code{set-visited-file-name} does not save the buffer in the newly visited
5176: file; it just alters the records inside Emacs so that, if you save the
5177: buffer, it will be saved in that file. It also marks the buffer as
5178: ``modified'' so that @kbd{C-x C-s} @i{will} save.
5179:
5180: @kindex C-x C-w
5181: @findex write-file
5182: If you wish to mark the buffer as visiting a different file and save it
5183: right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely
5184: equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}.
5185: @kbd{C-x C-s} used on a buffer that is not visiting with a file has the
5186: same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
5187: buffer as visiting that file, and saves it there. The default file name in
5188: a buffer that is not visiting a file is made by combining the buffer name
5189: with the buffer's default directory.
5190:
5191: If Emacs is about to save a file and sees that the date of the latest
5192: version on disk does not match what Emacs last read or wrote, Emacs
5193: notifies you of this fact, because it probably indicates a problem caused
5194: by simultaneous editing and requires your immediate attention.
5195: @xref{Interlocking,, Simultaneous Editing}.
5196:
5197: @vindex require-final-newline
5198: If the variable @code{require-final-newline} is non-@code{nil}, Emacs
5199: puts a newline at the end of any file that doesn't already end in one,
5200: every time a file is saved or written.
5201:
5202: @vindex write-file-hooks
5203: You can implement other ways to write files, and other things to be done
5204: before writing them, using the hook variable @code{write-file-hooks}. The
5205: value of this variable should be a list of Lisp functions. When a file is
5206: to be written, the functions in the list are called, one by one, with no
5207: arguments. If one of them returns a non-@code{nil} value, Emacs takes this
5208: to mean that the file has been written in some suitable fashion; the rest
5209: of the functions are not called, and normal writing is not done.
5210:
5211: @menu
5212: * Backup:: How Emacs saves the old version of your file.
5213: * Interlocking:: How Emacs protects against simultaneous editing
5214: of one file by two users.
5215: @end menu
5216:
5217: @node Backup, Interlocking, Saving, Saving
5218: @subsection Backup Files
5219: @cindex backup file
5220: @vindex make-backup-files
5221:
5222: Because Unix does not provide version numbers in file names, rewriting a
5223: file in Unix automatically destroys all record of what the file used to
5224: contain. Thus, saving a file from Emacs throws away the old contents of
5225: the file---or it would, except that Emacs carefully copies the old contents
5226: to another file, called the @dfn{backup} file, before actually saving
5227: (provided the variable @code{make-backup-files} is non-@code{nil};
5228: backup files are not written if this variable is @code{nil}).
5229:
5230: At your option, Emacs can keep either a single backup file or a series of
5231: numbered backup files for each file that you edit.
5232:
5233: Emacs makes a backup for a file only the first time the file is saved
5234: from one buffer. No matter how many times you save a file, its backup file
5235: continues to contain the contents from before the file was visited.
5236: Normally this means that the backup file contains the contents from before
5237: the current editing session; however, if you kill the buffer and then visit
5238: the file again, a new backup file will be made by the next save.
5239:
5240: @menu
5241: * Names: Backup Names. How backup files are named;
5242: Choosing single or numbered backup files.
5243: * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
5244: * Copying: Backup Copying. Backups can be made by copying or renaming.
5245: @end menu
5246:
5247: @node Backup Names, Backup Deletion, Backup, Backup
5248: @subsubsection Single or Numbered Backups
5249:
5250: If you choose to have a single backup file (this is the default),
5251: the backup file's name is constructed by appending @samp{~} to the
5252: file name being edited; thus, the backup file for @file{eval.c} would
5253: be @file{eval.c~}.
5254:
5255: If you choose to have a series of numbered backup files, backup file
5256: names are made by appending @samp{.~}, the number, and another @samp{~} to
5257: the original file name. Thus, the backup files of @file{eval.c} would be
5258: called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names
5259: like @file{eval.c.~259~} and beyond.
5260:
5261: If protection stops you from writing backup files under the usual names,
5262: the backup file is written as @file{%backup%~} in your home directory.
5263: Only one such file can exist, so only the most recently made such backup is
5264: available.
5265:
5266: @vindex version-control
5267: The choice of single backup or numbered backups is controlled by the
5268: variable @code{version-control}. Its possible values are
5269:
5270: @table @code
5271: @item t
5272: Make numbered backups.
5273: @item nil
5274: Make numbered backups for files that have numbered backups already.
5275: Otherwise, make single backups.
5276: @item never
5277: Do not in any case make numbered backups; always make single backups.
5278: @end table
5279:
5280: @noindent
5281: @code{version-control} may be set locally in an individual buffer to
5282: control the making of backups for that buffer's file. For example,
5283: Rmail mode locally sets @code{version-control} to @code{never} to make sure
5284: that there is only one backup for an Rmail file. @xref{Locals}.
5285:
5286: @node Backup Deletion, Backup Copying, Backup Names, Backup
5287: @subsubsection Automatic Deletion of Backups
5288:
5289: @cindex backups, automatic deleting of
5290: @cindex versions, keeping old
5291: @vindex kept-old-versions
5292: @vindex kept-new-versions
5293: To prevent unlimited consumption of disk space, Emacs can delete numbered
5294: backup versions automatically. Generally Emacs keeps the first few backups
5295: and the latest few backups, deleting any in between. This happens every
5296: time a new backup is made. The two variables that control the deletion are
5297: @code{kept-old-versions} and @code{kept-new-versions}. Their values are, respectively
5298: the number of oldest (lowest-numbered) backups to keep and the number of
5299: newest (highest-numbered) ones to keep, each time a new backup is made.
5300: Recall that these values are used just after a new backup version is made;
5301: that newly made backup is included in the count in @code{kept-new-versions}.
5302: By default, both variables are 2.
5303:
5304: @vindex trim-versions-without-asking
5305: If @code{trim-versions-without-asking} is non-@code{nil}, the excess
5306: middle versions are deleted without a murmur. If it is @code{nil}, the
5307: default, then you are asked whether the excess middle versions should
5308: really be deleted.
5309:
5310: Dired's @kbd{.} (Period) command can also be used to delete old versions.
5311: @xref{Dired}.
5312:
5313: @node Backup Copying,, Backup Deletion, Backup
5314: @subsubsection Copying vs. Renaming
5315: @c !!!! zzzz change back after fixref
5316: @c subsubsection Copying vs.@: Renaming
5317:
5318: Backup files can be made by copying the old file or by renaming it. This
5319: makes a difference when the old file has multiple names. If the old file
5320: is renamed into the backup file, then the alternate names become names for
5321: the backup file. If the old file is copied instead, then the alternate
5322: names remain names for the file that you are editing, and the contents
5323: accessed by those names will be the new contents.
5324:
5325: The method of making a backup file may also affect the file's owner
5326: and group. If copying is used, these do not change. If renaming is used,
5327: you become the file's owner, and the file's group becomes the default
5328: (different operating systems have different defaults for the group).
5329:
5330: Having the owner change is usually a good idea, because then the owner
5331: always shows who last edited the file. Also, the owners of the backups
5332: show who produced those versions. Occasionally there is a file whose
5333: owner should not change; it is a good idea for such files to contain
5334: local variable lists to set @code{backup-by-copying-when-mismatch} for
5335: them alone (@pxref{File Variables}).
5336:
5337: @vindex backup-by-copying
5338: @vindex backup-by-copying-when-linked
5339: @vindex backup-by-copying-when-mismatch
5340: The choice of renaming or copying is controlled by three variables.
5341: Normally, renaming is done. If the variable @code{backup-by-copying} is
5342: non-@code{nil}, copying is used. Otherwise, if the variable
5343: @code{backup-by-copying-when-linked} is non-@code{nil}, then copying is
5344: done for files that have multiple names, but renaming may still done when
5345: the file being edited has only one name. If the variable
5346: @code{backup-by-copying-when-mismatch} is non-@code{nil}, then copying is
5347: done if renaming would cause the file's owner or group to change. @refill
5348:
5349: @node Interlocking,,Backup,Saving
5350: @subsection Protection against Simultaneous Editing
5351:
5352: @cindex buffer locking
5353: @cindex locking buffers
5354: @cindex interlocking buffers
5355: @cindex file dates
5356: @cindex simultaneous editing
5357: Simultaneous editing occurs when two users visit the same file, both make
5358: changes, and then both save them. If nobody were informed that this was
5359: happening, whichever user saved first would later find that his changes
5360: were lost. On some systems, Emacs notices immediately when the second user
5361: starts to change the file, and issues an immediate warning. When this is
5362: not possible, or if the second user has gone on to change the file despite
5363: the warning, Emacs checks later when the file is saved, and issues a second
5364: warning when a user is about to overwrite a file containing another user's
5365: changes. If the editing user takes the proper corrective action at this
5366: point, he can prevent actual loss of work.
5367:
5368: @findex ask-user-about-lock
5369: When you make the first modification in an Emacs buffer that is visiting
5370: a file, Emacs records that you have locked the file. (It does this by
5371: writing another file in a directory reserved for this purpose.) The lock
5372: is removed when you save the changes. The idea is that the file is locked
5373: whenever the buffer is modified. If you begin to modify the buffer while
5374: the visited file is locked by someone else, this constitutes a collision,
5375: and Emacs asks you what to do. It does this by calling the Lisp function
5376: @code{ask-user-about-lock}, which you can redefine for the sake of
5377: customization. The standard definition of this function asks you a
5378: question and accepts three possible answers:
5379:
5380: @table @kbd
5381: @item s
5382: Steal the lock. Whoever was already changing the file loses the lock,
5383: and you gain the lock.
5384: @item p
5385: Proceed. Go ahead and edit the file despite its being locked by someone else.
5386: @item q
5387: Quit. This causes an error (@code{file-locked}) and the modification you
5388: were trying to make in the buffer does not actually take place.
5389: @end table
5390:
5391: Note that locking works on the basis of a file name; if a file has
5392: multiple names, Emacs does not realize that the two names are the same file
5393: and cannot prevent two user from editing it simultaneously under different
5394: names. However, basing locking on names means that Emacs can interlock the
5395: editing of new files that will not really exist until they are saved.
5396:
5397: Some systems are not configured to allow Emacs to make locks. On
5398: these systems, Emacs cannot detect trouble in advance, but it still can
5399: detect it in time to prevent you from overwriting someone else's changes.
5400:
5401: Every time Emacs saves a buffer, it first checks the last-modification
5402: date of the existing file on disk to see that it has not changed since the
5403: file was last visited or saved. If the date does not match, it implies
5404: that changes were made in the file in some other way, and these changes are
5405: about to be lost if Emacs actually does save. To prevent this, Emacs
5406: prints a warning message and asks for confirmation before saving.
5407: Occasionally you will know why the file was changed and know that it does
5408: not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should
5409: cancel the save with @kbd{C-g} and investigate the situation.
5410:
5411: The first thing you should do when notified that simultaneous editing has
5412: already taken place is to list the directory with @kbd{C-u C-x C-d}
5413: (@pxref{ListDir,,Directory Listing}). This will show the file's
5414: current author. You should attempt to contact that person to warn him
5415: or her not to continue editing. Often the next step is to save the
5416: contents of your Emacs buffer under a different name, and use
5417: @code{diff} to compare the two files.@refill
5418:
5419: Simultaneous editing checks are also made when you visit with @kbd{C-x
5420: C-f} a file that is already visited and when you start to modify a file.
5421: This is not strictly necessary, but it can cause you to find out about the
5422: problem earlier, when perhaps correction takes less work.
5423:
5424: @node Reverting, Auto Save, Saving, Files
5425: @section Reverting a Buffer
5426: @findex revert-buffer
5427: @cindex drastic changes
5428:
5429: If you have made extensive changes to a file and then change your mind
5430: about them, you can get rid of them by reading in the previous version of
5431: the file. To do this, use @kbd{M-x revert-buffer}, which operates on the
5432: current buffer. Since this is a very dangerous thing to do, you must
5433: confirm it with @kbd{yes}.
5434:
5435: If the current buffer has been auto-saved more recently than it has been
5436: saved for real, @code{revert-buffer} offers to read the auto save file
5437: instead of the visited file (@pxref{Auto Save}). This question comes
5438: before the usual request for confirmation, and demands @kbd{y} or @kbd{n}
5439: as an answer. If you have started to type @kbd{yes} for confirmation
5440: without realizing that the other question was going to be asked, the
5441: @kbd{y} will answer that question, but the @kbd{es} will not be valid
5442: confirmation. So you will have a chance to cancel the operation with
5443: @kbd{C-g} and try it again with the answers that you really intend.
5444:
5445: @code{revert-buffer} keeps point at the same distance (measured in
5446: characters) from the beginning of the file. If the file was edited only
5447: slightly, you will be at approximately the same piece of text after
5448: reverting as before. If you have made drastic changes, the same value of
5449: point in the old file may address a totally different piece of text.
5450:
5451: A buffer reverted from its visited file is marked ``not modified'' until
5452: another change is made.
5453:
5454: Some kinds of buffers whose contents reflect data bases other than files,
5455: such as Dired buffers, can also be reverted. For them, reverting means
5456: recalculating their contents from the appropriate data base. Buffers
5457: created randomly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
5458: reports an error when asked to do so.
5459:
5460: @node Auto Save, ListDir, Reverting, Files
5461: @section Auto-Saving: Protection Against Disasters
5462: @cindex Auto-Save mode
5463: @cindex crashes
5464:
5465: Emacs saves all the visited files from time to time (based on counting
5466: your keystrokes) without being asked. This is called @dfn{auto-saving}.
5467: It prevents you from losing more than a limited amount of work if the
5468: system crashes.
5469:
5470: When Emacs determines that it is time for auto-saving, each buffer is
5471: considered, and is auto-saved if auto-saving is turned on for it and it has
5472: been changed since the last time it was auto-saved. If any auto-saving is
5473: done, the message @samp{Auto-saving...} is displayed in the echo area until
5474: auto-saving is finished. Errors occurring during auto-saving are caught
5475: so that they do not interfere with the execution of commands you have been
5476: typing.
5477:
5478: @menu
5479: * Files: Auto Save Files.
5480: * Control: Auto Save Control.
5481: * Recover:: Recovering text from auto-save files.
5482: @end menu
5483:
5484: @node Auto Save Files, Auto Save Control, Auto Save, Auto Save
5485: @subsection Auto-Save Files
5486:
5487: Auto-saving does not normally save in the files that you visited, because
5488: it can be very undesirable to save a program that is in an inconsistent
5489: state when you have made half of a planned change. Instead, auto-saving
5490: is done in a different file called the @dfn{auto-save file}, and the
5491: visited file is changed only when you request saving explicitly (such as
5492: with @kbd{C-x C-s}).
5493:
5494: Normally, the auto-save file name is made by appending @samp{#} to the
5495: front and rear of the visited file name. Thus, a buffer visiting file
5496: @file{foo.c} would be auto-saved in a file @file{#foo.c#}. Most buffers
5497: that are not visiting files are auto-saved only if you request it
5498: explicitly; when they are auto-saved, the auto-save file name is made by
5499: appending @samp{#%} to the front and @samp{#} to the rear of buffer name.
5500: For example, the @samp{*mail*} buffer in which you compose messages to be
5501: sent is auto-saved in a file named @file{#%*mail*#}. Auto-save file names
5502: are made this way unless you reprogram parts of Emacs to do something
5503: different (the functions @code{make-auto-save-file-name} and
5504: @code{auto-save-file-name-p}). The file name to be used for auto-saving
5505: in a buffer is calculated when auto-saving is turned on in that buffer.
5506:
5507: @vindex auto-save-visited-file-name
5508: If you want auto-saving to be done in the visited file, set the variable
5509: @code{auto-save-visited-file-name} to be non-@code{nil}. In this mode,
5510: there is really no difference between auto-saving and explicit saving.
5511:
5512: @vindex delete-auto-save-files
5513: A buffer's auto-save file is deleted when you save the buffer in its
5514: visited file. To inhibit this, set the variable @code{delete-auto-save-files}
5515: to @code{nil}. Changing the visited file name with @kbd{C-x C-w} or
5516: @code{set-visited-file-name} renames any auto-save file to go with
5517: the new visited name.
5518:
5519: @node Auto Save Control, Recover, Auto Save Files, Auto Save
5520: @subsection Controlling Auto-Saving
5521:
5522: @vindex auto-save-default
5523: @findex auto-save-mode
5524: Each time you visit a file, auto-saving is turned on for that file's
5525: buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
5526: in batch mode; @pxref{Entering Emacs}). The default for this variable is
5527: @code{t}, so auto-saving is the usual practice for file-visiting buffers.
5528: Auto-saving can be turned on or off for any existing buffer with the
5529: command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x
5530: auto-save-mode} turns auto-saving on with a positive argument, off with a
5531: zero or negative argument; with no argument, it toggles.
5532:
5533: @vindex auto-save-interval
5534: @findex do-auto-save
5535: Emacs does auto-saving periodically based on counting how many characters
5536: you have typed since the last time auto-saving was done. The variable
5537: @code{auto-save-interval} specifies how many characters there are between
5538: auto-saves. By default, it is 300. Emacs also auto-saves whenever you
5539: call the function @code{do-auto-save}.
5540:
5541: Emacs also does auto-saving whenever it gets a fatal error. This
5542: includes killing the Emacs job with a shell command such as @code{kill
5543: %emacs}, or disconnecting a phone line or network connection.
5544:
5545: @node Recover,, Auto Save Control, Auto Save
5546: @subsection Recovering Data from Auto-Saves
5547:
5548: @findex recover-file
5549: The way to use the contents of an auto-save file to recover from a loss
5550: of data is with the command @kbd{M-x recover-file @key{RET} @var{file}
5551: @key{RET}}. This visits @var{file} and then (after your confirmation)
5552: restores the contents from its auto-save file @file{#@var{file}#}. You
5553: can then save with @kbd{C-x C-s} to put the recovered text into @var{file}
5554: itself. For example, to recover file @file{foo.c} from its auto-save file
5555: @file{#foo.c#}, do:@refill
5556:
5557: @example
5558: M-x recover-file @key{RET} foo.c @key{RET}
5559: C-x C-s
5560: @end example
5561:
5562: Before asking for confirmation, @kbd{M-x recover-file} displays a
5563: directory listing describing the specified file and the auto-save file,
5564: so you can compare their sizes and dates. If the auto-save file
5565: is older, @kbd{M-x recover-file} does not offer to read it.
5566:
5567: Auto-saving is disabled by @kbd{M-x recover-file} because using
5568: this command implies that the auto-save file contains valuable data
5569: from a past session. If you save the data in the visited file and
5570: then go on to make new changes, you should turn auto-saving back on
5571: with @kbd{M-x auto-save-mode}.
5572:
5573: @node ListDir, Dired, Auto Save, Files
5574: @section Listing a File Directory
5575:
5576: @cindex file directory
5577: @cindex directory listing
5578: @cindex listing a directory
5579: Files are classified by Unix into @dfn{directories}. A @dfn{directory
5580: listing} is a list of all the files in a directory. Emacs provides
5581: directory listings in brief format (file names only) and verbose format
5582: (sizes, dates, and authors included).
5583:
5584: @table @kbd
5585: @item C-x C-d @var{dir-or-pattern}
5586: Print a brief directory listing (@code{list-directory}).
5587: @item C-u C-x C-d @var{dir-or-pattern}
5588: Print a verbose directory listing.
5589: @end table
5590:
5591: @findex list-directory
5592: @kindex C-x C-d
5593: The command to print a directory listing is @kbd{C-x C-d} (@code{list-directory}).
5594: It reads using the minibuffer a file name which is either a directory to be
5595: listed or a wildcard-containing pattern for the files to be listed. For
5596: example,
5597:
5598: @example
5599: C-x C-d /u2/emacs/etc @key{RET}
5600: @end example
5601:
5602: @noindent
5603: lists all the files in directory @file{/u2/emacs/etc}. An example of
5604: specifying a file name pattern is
5605:
5606: @example
5607: C-x C-d /u2/emacs/src/*.c @key{RET}
5608: @end example
5609:
5610: Normally, @kbd{C-x C-d} prints a brief directory listing containing just
5611: file names. A numeric argument (regardless of value) tells it to print a
5612: verbose listing (like @code{ls -l}).
5613:
5614: @vindex list-directory-brief-switches
5615: @vindex list-directory-verbose-switches
5616: The text of a directory listing is obtained by running @code{ls} in an
5617: inferior process. Two Emacs variables control the switches passed to
5618: @code{ls}: @code{list-directory-brief-switches} is a string giving the
5619: switches to use in brief listings (@code{"-CF"} by default), and
5620: @code{list-directory-verbose-switches} is a string giving the switches to
5621: use in a verbose listing (@code{"-l"} by default).
5622:
5623: @node Dired, Misc File Ops, ListDir, Files
5624: @section Dired, the Directory Editor
5625: @cindex Dired
5626: @cindex deletion (of files)
5627:
5628: Dired makes it easy to delete or visit many of the files in a single
5629: directory at once. It makes an Emacs buffer containing a listing of the
5630: directory. You can use the normal Emacs commands to move around in this
5631: buffer, and special Dired commands to operate on the files.
5632:
5633: @menu
5634: * Enter: Dired Enter. How to invoke Dired.
5635: * Edit: Dired Edit. Editing the Dired buffer.
5636: * Deletion: Dired Deletion. Deleting files with Dired.
5637: * Immed: Dired Immed. Other file operations through Dired.
5638: @end menu
5639:
5640: @node Dired Enter, Dired Edit, Dired, Dired
5641: @subsection Entering Dired
5642:
5643: @findex dired
5644: @kindex C-x d
5645: @cindex Dired mode
5646: @vindex dired-listing-switches
5647: To invoke dired, do @kbd{C-x d} or @kbd{M-x dired}. The command reads a
5648: directory name or wildcard file name pattern as a minibuffer argument just
5649: like the @code{list-directory} command, @kbd{C-x C-d}. Where @code{dired}
5650: differs from @code{list-directory} is in naming the buffer after the
5651: directory name or the wildcard pattern used for the listing, and putting
5652: the buffer into Dired mode so that the special commands of Dired are
5653: available in it. The variable @code{dired-listing-switches} is a string
5654: used as an argument to @code{ls} in making the directory; this string
5655: @i{must} contain @samp{-l}.
5656:
5657: @findex dired-other-window
5658: @kindex C-x 4 d
5659: To display the Dired buffer in another window rather than in the selected
5660: window, use @kbd{C-x 4 d} (@code{dired-other-window)} instead of @kbd{C-x d}.
5661:
5662: @node Dired Edit, Dired Deletion, Dired Enter, Dired
5663: @subsection Editing in Dired
5664:
5665: Once the Dired buffer exists, you can switch freely between it and other
5666: Emacs buffers. Whenever the Dired buffer is selected, certain special
5667: commands are provided that operate on files that are listed. The Dired
5668: buffer is ``read-only'', and inserting text in it is not useful, so
5669: ordinary printing characters such as @kbd{d} and @kbd{x} are used for Dired
5670: commands. Most Dired commands operate on the file described by the line
5671: that point is on. Some commands perform operations immediately; others
5672: ``flag'' the file to be operated on later.
5673:
5674: Most Dired commands that operate on the current line's file also treat a
5675: numeric argument as a repeat count, meaning to act on the files of the
5676: next few lines. A negative argument means to operate on the files of the
5677: preceding lines, and leave point on the first of those lines.
5678:
5679: All the usual Emacs cursor motion commands are available in Dired
5680: buffers. Some special purpose commands are also provided. The keys
5681: @kbd{C-n} and @kbd{C-p} are redefined so that they try to position
5682: the cursor at the beginning of the filename on the line, rather than
5683: at the beginning of the line.
5684:
5685: For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent to
5686: @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. Moving by lines is done so
5687: often in Dired that it deserves to be easy to type. @key{DEL} (move up and
5688: unflag) is often useful simply for moving up.@refill
5689:
5690: The @kbd{g} command in Dired runs @code{revert-buffer} to reinitialize
5691: the buffer from the actual disk directory and show any changes made in the
5692: directory by programs other than Dired. All deletion flags in the Dired
5693: buffer are lost when this is done.
5694:
5695: @node Dired Deletion, Dired Immed, Dired Edit, Dired
5696: @subsection Deleting Files with Dired
5697:
5698: The primary use of Dired is to flag files for deletion and then delete
5699: them.
5700:
5701: @table @kbd
5702: @item d
5703: Flag this file for deletion.
5704: @item u
5705: Remove deletion-flag on this line.
5706: @item @key{DEL}
5707: Remove deletion-flag on previous line, moving point to that line.
5708: @item x
5709: Delete the files that are flagged for deletion.
5710: @item #
5711: Flag all auto-save files (files whose names start and end with @samp{#})
5712: for deletion (@pxref{Auto Save}).
5713: @item ~
5714: Flag all backup files (files whose names end with @samp{~}) for deletion
5715: (@pxref{Backup}).
5716: @item .@: @r{(Period)}
5717: Flag excess numeric backup files for deletion. The oldest and newest
5718: few backup files of any one file are exempt; the middle ones are flagged.
5719: @end table
5720:
5721: You can flag a file for deletion by moving to the line describing the
5722: file and typing @kbd{d} or @kbd{C-d}. The deletion flag is visible as a
5723: @samp{D} at the beginning of the line. Point is moved to the beginning of
5724: the next line, so that repeated @kbd{d} commands flag successive files.
5725:
5726: The files are flagged for deletion rather than deleted immediately to
5727: avoid the danger of deleting a file accidentally. Until you direct Dired
5728: to delete the flagged files, you can remove deletion flags using the
5729: commands @kbd{u} and @key{DEL}. @kbd{u} works just like @kbd{d}, but
5730: removes flags rather than making flags. @key{DEL} moves upward, removing
5731: flags; it is like @kbd{u} with numeric argument automatically negated.
5732:
5733: To delete the flagged files, type @kbd{x}. This command first displays a
5734: list of all the file names flagged for deletion, and requests confirmation
5735: with @kbd{yes}. Once you confirm, all the flagged files are deleted, and their
5736: lines are deleted from the text of the Dired buffer. The shortened Dired
5737: buffer remains selected. If you answer @kbd{no} or quit with @kbd{C-g}, you
5738: return immediately to Dired, with the deletion flags still present and no
5739: files actually deleted.
5740:
5741: The @kbd{#}, @kbd{~} and @kbd{.} commands flag many files for
5742: deletion, based on their names. These commands are useful precisely
5743: because they do not actually delete any files; you can remove the
5744: deletion flags from any flagged files that you really wish to keep.@refill
5745:
5746: @kbd{#} flags for deletion all files that appear to have been made by
5747: auto-saving (that is, files whose names begin and end with @samp{#}).
5748: @kbd{~} flags for deletion all files that appear to have been made as
5749: backups for files that were edited (that is, files whose names end with
5750: @samp{~}).
5751:
5752: @vindex dired-kept-versions
5753: @kbd{.} (Period) flags just some of the backup files for deletion: only
5754: numeric backups that are not among the oldest few nor the newest few
5755: backups of any one file. Normally @code{dired-kept-versions} (not
5756: @code{kept-new-versions}; that applies only when saving) specifies the
5757: number of newest versions of each file to keep, and
5758: @code{kept-old-versions} specifies the number of oldest versions to keep.
5759: Period with a positive numeric argument, as in @kbd{C-u 3 .}, specifies the
5760: number of newest versions to keep, overriding @code{dired-kept-versions}.
5761: A negative numeric argument overrides @code{kept-old-versions}, using minus
5762: the value of the argument to specify the number of oldest versions of each
5763: file to keep.@refill
5764:
5765: @node Dired Immed,, Dired Deletion, Dired
5766: @subsection Immediate File Operations in Dired
5767:
5768: Some file operations in Dired take place immediately when they are
5769: requested.
5770:
5771: @table @kbd
5772: @item c
5773: Copies the file described on the current line. You must supply a file name
5774: to copy to, using the minibuffer.
5775: @item f
5776: Visits the file described on the current line. It is just like typing
5777: @kbd{C-x C-f} and supplying that file name. If the file on this line is a
5778: subdirectory, @kbd{f} actually causes Dired to be invoked on that
5779: subdirectory. @xref{Visiting}.
5780: @item o
5781: Like @kbd{f}, but uses another window to display the file's buffer. The
5782: Dired buffer remains visible in the first window. This is like using
5783: @kbd{C-x 4 C-f} to visit the file. @xref{Windows}.
5784: @item r
5785: Renames the file described on the current line. You must supply a file
5786: name to rename to, using the minibuffer.
5787: @item v
5788: Views the file described on this line using @kbd{M-x view-file}. Viewing a
5789: file is like visiting it, but is slanted toward moving around in the file
5790: conveniently and does not allow changing the file. @xref{Misc File
5791: Ops,View File}. Viewing a file that is a directory runs Dired on that
5792: directory.@refill
5793: @end table
5794:
5795: @node Misc File Ops,, Dired, Files
5796: @section Miscellaneous File Operations
5797:
5798: Emacs has commands for performing many other operations on files.
5799: All operate on one file; they do not accept wild card file names.
5800:
5801: @findex view-file
5802: @cindex viewing
5803: @kbd{M-x view-file} allows you to scan or read a file by sequential
5804: screenfuls. It reads a file name argument using the minibuffer. After
5805: reading the file into an Emacs buffer, @code{view-file} reads and displays
5806: one windowful. You can then type @key{SPC} to scroll forward one windowful,
5807: or @key{DEL} to scroll backward. Various other commands are provided for
5808: moving around in the file, but none for changing it; type @kbd{C-h} while
5809: viewing for a list of them. They are mostly the same as normal Emacs
5810: cursor motion commands. To exit from viewing, type @kbd{C-c}.
5811:
5812: @findex insert-file
5813: @kbd{M-x insert-file} inserts a copy of the contents of the specified
5814: file into the current buffer at point, leaving point unchanged before the
5815: contents and the mark after them. @xref{Mark}.
5816:
5817: @findex write-region
5818: @findex append-to-file
5819: @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it copies
5820: the contents of the region into the specified file. @kbd{M-x append-to-file}
5821: adds the text of the region to the end of the specified file.
5822:
5823: @findex delete-file
5824: @cindex deletion (of files)
5825: @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
5826: command in the shell. If you are deleting many files in one directory, it
5827: may be more convenient to use Dired (@pxref{Dired}).
5828:
5829: @findex rename-file
5830: @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
5831: the minibuffer, then renames file @var{old} as @var{new}. If a file named
5832: @var{new} already exists, you must confirm with @kbd{yes} or renaming is not
5833: done; this is because renaming causes the old meaning of the name @var{new}
5834: to be lost. If @var{old} and @var{new} are on different file systems, the
5835: file @var{old} is copied and deleted.
5836:
5837: @findex add-name-to-file
5838: The similar command @kbd{M-x add-name-to-file} is used to add an
5839: additional name to an existing file without removing its old name.
5840: The new name must belong on the same file system that the file is on.
5841:
5842: @findex copy-file
5843: @cindex copying files
5844: @kbd{M-x copy-file} reads the file @var{old} and writes a new file named
5845: @var{new} with the same contents. Confirmation is required if a file named
5846: @var{new} already exists, because copying has the consequence of overwriting
5847: the old contents of the file @var{new}.
5848:
5849: @findex make-symbolic-link
5850: @kbd{M-x make-symbolic-link} reads two file names @var{old} and @var{linkname},
5851: and then creates a symbolic link named @var{linkname} and pointing at @var{old}.
5852: The effect is that future attempts to open file @var{linkname} will refer
5853: to whatever file is named @var{old} at the time the opening is done, or
5854: will get an error if the name @var{old} is not in use at that time.
5855: Confirmation is required when creating the link if @var{linkname} is in
5856: use. Note that not all systems support symbolic links.
5857:
5858: @node Buffers, Windows, Files, Top
5859: @chapter Using Multiple Buffers
5860:
5861: @cindex buffers
5862: The text you are editing in Emacs resides in an object called a
5863: @dfn{buffer}. Each time you visit a file, a buffer is created to hold the
5864: file's text. Each time you invoke Dired, a buffer is created to hold the
5865: directory listing. If you send a message with @kbd{C-x m}, a buffer named
5866: @samp{*mail*} is used to hold the text of the message. When you ask for a
5867: command's documentation, that appears in a buffer called @file{*Help*}.
5868:
5869: @cindex selected buffer
5870: @cindex current buffer
5871: At any time, one and only one buffer is @dfn{selected}. It is also
5872: called the @dfn{current buffer}. Often we say that a command operates on
5873: ``the buffer'' as if there were only one; but really this means that the
5874: command operates on the selected buffer (most commands do).
5875:
5876: When Emacs makes multiple windows, each window has a chosen buffer which
5877: is displayed there, but at any time only one of the windows is selected and
5878: its chosen buffer is the selected buffer. Each window's mode line displays
5879: the name of the buffer that the window is displaying (@pxref{Windows}).
5880:
5881: Each buffer has a name, which can be of any length, and you can select
5882: any buffer by giving its name. Most buffers are made by visiting files,
5883: and their names are derived from the files' names. But you can also create
5884: an empty buffer with any name you want. A newly started Emacs has a buffer
5885: named @samp{*scratch*} which can be used for evaluating Lisp expressions in
5886: Emacs. The distinction between upper and lower case matters in buffer
5887: names.
5888:
5889: Each buffer records individually what file it is visiting, whether it is
5890: modified, and what major mode and minor modes are in effect in it
5891: (@pxref{Major Modes}). Any Emacs variable can be made @dfn{local to} a
5892: particular buffer, meaning its value in that buffer can be different from
5893: the value in other buffers. @xref{Locals}.
5894:
5895: @menu
5896: * Select Buffer:: Creating a new buffer or reselecting an old one.
5897: * List Buffers:: Getting a list of buffers that exist.
5898: * Misc Buffer:: Renaming; changing read-onliness; copying text.
5899: * Kill Buffer:: Killing buffers you no longer need.
5900: * Several Buffers:: How to go through the list of all buffers
5901: and operate variously on several of them.
5902: @end menu
5903:
5904: @node Select Buffer, List Buffers, Buffers, Buffers
5905: @section Creating and Selecting Buffers
5906: @cindex change buffers
5907: @cindex switch buffers
5908:
5909: @table @kbd
5910: @item C-x b @var{buffer} @key{RET}
5911: Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
5912: @item C-x 4 b @var{buffer} @key{RET}
5913: Similar, but select a buffer named @var{buffer} in another window
5914: (@code{switch-to-buffer-other-window}).
5915: @end table
5916:
5917: @kindex C-x 4 b
5918: @c @findex switch-to-buffer-other-window
5919: @kindex C-x b
5920: @findex switch-to-buffer
5921: To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
5922: @key{RET}}. This is the command @code{switch-to-buffer} with argument
5923: @var{bufname}. You can use completion on an abbreviation for the buffer
5924: name you want (@pxref{Completion}). An empty argument to @kbd{C-x b}
5925: specifies the most recently selected buffer that is not displayed in any
5926: window.@refill
5927:
5928: Most buffers are created by visiting files, or by Emacs commands that
5929: want to display some text, but you can also create a buffer explicitly by
5930: typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty buffer which
5931: is not visiting any file, and selects it for editing. Such buffers are
5932: used for making notes to yourself. If you try to save one, you are asked
5933: for the file name to use. The new buffer's major mode is determined by the
5934: value of @code{default-major-mode} (@pxref{Major Modes}).
5935:
5936: Note that @kbd{C-x C-f}, and any other command for visiting a file, can
5937: also be used to switch buffers. @xref{Visiting}.
5938:
5939: @node List Buffers, Misc Buffer, Select Buffer, Buffers
5940: @section Listing Existing Buffers
5941:
5942: @table @kbd
5943: @item C-x C-b
5944: List the existing buffers (@code{list-buffers}).
5945: @end table
5946:
5947: @kindex C-x C-b
5948: @findex list-buffers
5949: To print a list of all the buffers that exist, type @kbd{C-x C-b}.
5950: Each line in the list shows one buffer's name, major mode and visited file.
5951: @samp{*} at the beginning of a line indicates the buffer is ``modified''.
5952: If several buffers are modified, it may be time to save some with @kbd{C-x
5953: s} (@pxref{Saving}). @samp{%} indicates a read-only buffer. @samp{.}
5954: marks the selected buffer. Here is an example of a buffer list:@refill
5955:
5956: @smallexample
5957: MR Buffer Size Mode File
5958: -- ------ ---- ---- ----
5959: .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
5960: *Help* 1287 Fundamental
5961: files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
5962: % RMAIL 64042 RMAIL /u/rms/RMAIL
5963: *% man 747 Dired
5964: net.emacs 343885 Fundamental /u/rms/net.emacs
5965: fileio.c 27691 C /u2/emacs/src/fileio.c
5966: NEWS 67340 Text /u2/emacs/etc/NEWS
5967: *scratch* 0 Lisp Interaction
5968: @end smallexample
5969:
5970: @noindent
5971: Note that the buffer @file{*Help*} was made by a help request; it is not
5972: visiting any file. The buffer @file{man} was made by Dired on the
5973: directory @file{/u2/emacs/man/}.
5974:
5975: @node Misc Buffer, Kill Buffer, List Buffers, Buffers
5976: @section Miscellaneous Buffer Operations
5977:
5978: @table @kbd
5979: @item C-x C-q
5980: Toggle read-only status of buffer (@code{toggle-read-only}).
5981: @item M-x rename-buffer
5982: Change the name of the current buffer.
5983: @item M-x view-buffer
5984: Scroll through a buffer.
5985: @end table
5986:
5987: @cindex read-only buffer
5988: @kindex C-x C-q
5989: @findex toggle-read-only
5990: @vindex buffer-read-only
5991: A buffer can be @dfn{read-only}, which means that commands to change its
5992: text are not allowed. Normally, read-only buffers are made by subsystems
5993: such as Dired and Rmail that have special commands to operate on the text;
5994: a read-only buffer is also made if you visit a file that is protected so
5995: you cannot write it. If you wish to make changes in a read-only buffer,
5996: use the command @kbd{C-x C-q} (@code{toggle-read-only}). It makes a
5997: read-only buffer writable, and makes a writable buffer read-only. This
5998: works by setting the variable @code{buffer-read-only}, which has a local
5999: value in each buffer and makes the buffer read-only if its value is
6000: non-@code{nil}.
6001:
6002: @findex rename-buffer
6003: @kbd{M-x rename-buffer} changes the name of the current buffer. Specify
6004: the new name as a minibuffer argument. There is no default. If you
6005: specify a name that is in use for some other buffer, an error happens and
6006: no renaming is done.
6007:
6008: @findex view-buffer
6009: @cindex View mode
6010: @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc File Ops})
6011: except that it examines an already existing Emacs buffer. View mode
6012: provides commands for scrolling through the buffer conveniently but not
6013: for changing it. When you exit View mode, the value of point that resulted
6014: from your perusal remains in effect.
6015:
6016: The commands @kbd{C-x a} (@code{append-to-buffer}) and @kbd{M-x
6017: insert-buffer} can be used to copy text from one buffer to another.
6018: @xref{Accumulating Text}.@refill
6019:
6020: @node Kill Buffer, Several Buffers, Misc Buffer, Buffers
6021: @section Killing Buffers
6022:
6023: After you use Emacs for a while, you may accumulate a large number of
6024: buffers. You may then find it convenient to eliminate the ones you no
6025: longer need. There are several commands provided for doing this.
6026:
6027: @c WideCommands
6028: @table @kbd
6029: @item C-x k
6030: Kill a buffer, specified by name (@code{kill-buffer}).
6031: @item M-x kill-some-buffers
6032: Offer to kill each buffer, one by one.
6033: @end table
6034:
6035: @findex kill-buffer
6036: @findex kill-some-buffers
6037: @kindex C-x k
6038:
6039: @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you specify
6040: in the minibuffer. The default, used if you type just @key{RET} in the
6041: minibuffer, is to kill the current buffer. If the current buffer is
6042: killed, another buffer is selected; a buffer that has been selected
6043: recently but does not appear in any window now is chosen to be selected.
6044: If the buffer being killed is modified (has unsaved editing) then you are
6045: asked to confirm with @kbd{yes} before the buffer is killed.
6046:
6047: The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
6048: one. An answer of @kbd{y} means to kill the buffer. Killing the current
6049: buffer or a buffer containing unsaved changes selects a new buffer or asks
6050: for confirmation just like @code{kill-buffer}.
6051:
6052: @node Several Buffers,, Kill Buffer, Buffers
6053: @section Operating on Several Buffers
6054: @cindex buffer menu
6055:
6056: The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
6057: you to request operations on various Emacs buffers by editing an Emacs
6058: buffer containing a list of them. You can save buffers, kill them
6059: (here called @dfn{deleting} them, for consistency with Dired), or display
6060: them.
6061:
6062: @table @kbd
6063: @item M-x buffer-menu
6064: Begin editing a buffer listing all Emacs buffers.
6065: @end table
6066:
6067: @findex buffer-menu
6068: @cindex Buffer Menu mode
6069: The command @code{buffer-menu} writes a list of all Emacs buffers into
6070: the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
6071: mode. The buffer is read-only, and can only be changed through the special
6072: commands described in this section. Most of these commands are graphic
6073: characters. The usual Emacs cursor motion commands can be used in the
6074: @samp{*Buffer List*} buffer. The following special commands apply to the
6075: buffer described on the current line.
6076:
6077: @table @kbd
6078: @item d
6079: Request to delete (kill) the buffer, then move down. The request
6080: shows as a @samp{D} on the line, before the buffer name. Requested
6081: deletions take place when the @kbd{x} command is used.
6082: @item k
6083: Synonym for @kbd{d}.
6084: @item C-d
6085: Like @kbd{d} but move up afterwards instead of down.
6086: @item s
6087: Request to save the buffer. The request shows as an @samp{S} on the
6088: line. Requested saves take place when the @kbd{x} command is used.
6089: You may request both saving and deletion for the same buffer.
6090: @item ~
6091: Mark buffer ``unmodified''. The command @kbd{~} does this
6092: immediately when typed.
6093: @item x
6094: Perform previously requested deletions and saves.
6095: @item u
6096: Remove any request made for the current line, and move down.
6097: @item @key{DEL}
6098: Move to previous line and remove any request made for that line.
6099: @end table
6100:
6101: All the commands that put in or remove flags to request later operations
6102: also move down a line, and accept a numeric argument as a repeat count,
6103: unless otherwise specified.
6104:
6105: There are also special commands to use the buffer list to select another
6106: buffer, and to specify one or more other buffers for display in additional
6107: windows.
6108:
6109: @table @kbd
6110: @item 1
6111: Select the buffer in a full-screen window. This command takes effect
6112: immediately.
6113: @item 2
6114: Immediately set up two windows, with this buffer in one, and the
6115: previously selected buffer (aside from the buffer @samp{*Buffer List*})
6116: in the other.
6117: @item f
6118: Immediately select the buffer in place of the @samp{*Buffer List*} buffer.
6119: @item o
6120: Immediately select the buffer in another window as if by @w{@kbd{C-x 4 b}},
6121: leaving @samp{*Buffer List*} visible.
6122: @item q
6123: Immediately select this buffer, and also display in other windows any
6124: buffers previously flagged with the @kbd{m} command. If there are no
6125: such buffers, this command is equivalent to @kbd{1}.
6126: @item m
6127: Flag this buffer to be displayed in another window if the @kbd{q}
6128: command is used. The request shows as a @samp{>} at the beginning of
6129: the line. The same buffer may not have both a delete request and a
6130: display request.
6131: @end table
6132:
6133: All that @code{buffer-menu} does directly is create and select a suitable
6134: buffer, and turn on Buffer Menu mode. Everything else described above is
6135: implemented by the special commands provided in Buffer Menu mode. One
6136: consequence of this is that you can switch from the @samp{*Buffer List*}
6137: buffer to another Emacs buffer, and edit there. You can reselect the
6138: @code{buffer-menu} buffer later, to perform the operations already
6139: requested, or you can kill it, or pay no further attention to it.
6140:
6141: The only difference between @code{buffer-menu} and @code{list-buffers} is
6142: that @code{buffer-menu} selects the @samp{*Buffer List*} buffer and
6143: @code{list-buffers} does not. If you run @code{list-buffers} (that is,
6144: type @kbd{C-x C-b}) and select the buffer list manually, you can use all of
6145: the commands described here.
6146:
6147: @node Windows, Major Modes, Buffers, Top
6148: @chapter Multiple Windows
6149: @cindex windows
6150:
6151: Emacs can split the screen into two or many windows, which can display
6152: parts of different buffers, or different parts of one buffer.
6153:
6154: @menu
6155: * Basic Window:: Introduction to Emacs windows.
6156: * Split Window:: New windows are made by splitting existing windows.
6157: * Other Window:: Moving to another window or doing something to it.
6158: * Pop Up Window:: Finding a file or buffer in another window.
6159: * Change Window:: Deleting windows and changing their sizes.
6160: @end menu
6161:
6162: @node Basic Window, Split Window, Windows, Windows
6163: @section Concepts of Emacs Windows
6164:
6165: When multiple windows are being displayed, each window has an Emacs
6166: buffer designated for display in it. The same buffer may appear in more
6167: than one window; if it does, any changes in its text are displayed in all
6168: the windows where it appears. But the windows showing the same buffer can
6169: show different parts of it, because each window has its own value of point.
6170:
6171: @cindex selected window
6172: At any time, one of the windows is the @dfn{selected window}; the buffer
6173: this window is displaying is the current buffer. The terminal's cursor
6174: shows the location of point in this window. Each other window has a
6175: location of point as well, but since the terminal has only one cursor there
6176: is no way to show where those locations are.
6177:
6178: Commands to move point affect the value of point for the selected Emacs
6179: window only. They do not change the value of point in any other Emacs
6180: window, even one showing the same buffer. The same is true for commands
6181: such as @kbd{C-x b} to change the selected buffer in the selected window;
6182: they do not affect other windows at all. However, there are other commands
6183: such as @kbd{C-x 4 b} that select a different window and switch buffers in
6184: it. Also, all commands that display information in a window, including
6185: (for example) @w{@kbd{C-h f}} (@code{describe-function}) and @kbd{C-x C-b}
6186: (@code{list-buffers}), work by switching buffers in a nonselected window
6187: without affecting the selected window.
6188:
6189: Each window has its own mode line, which displays the buffer name,
6190: modification status and major and minor modes of the buffer that is
6191: displayed in the window. @xref{Mode Line}, for full details on the mode
6192: line.
6193:
6194: @node Split Window, Other Window, Basic Window, Windows
6195: @section Splitting Windows
6196:
6197: @table @kbd
6198: @item C-x 2
6199: Split the selected window into two windows, one above the other
6200: (@code{split-window-vertically}).
6201: @item C-x 5
6202: Split the selected window into two windows positioned side by side
6203: (@code{split-window-horizontally}).
6204: @end table
6205:
6206: @kindex C-x 2
6207: @findex split-window-vertically
6208: The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the
6209: selected window into two windows, one above the other. Both windows start
6210: out displaying the same buffer, with the same value of point. By default
6211: the two windows each get half the height of the window that was split; a
6212: numeric argument specifies how many lines to give to the top window.
6213:
6214: @kindex C-x 5
6215: @findex split-window-horizontally
6216: @kbd{C-x 5} (@code{split-window-horizontally}) breaks the selected
6217: window into two side-by-side windows. A numeric argument specifies
6218: how many columns to give the one on the left. A line of vertical bars
6219: separates the two windows. Windows that are not the full width of the
6220: screen have mode lines, but they are truncated; also, they do not
6221: always appear in inverse video, because, the Emacs display routines
6222: have not been taught how to display a region of inverse video that is
6223: only part of a line on the screen.
6224:
6225: @vindex truncate-partial-width-windows
6226: When a window is less than the full width, text lines too long to fit are
6227: frequent. Continuing all those lines might be confusing. The variable
6228: @code{truncate-partial-width-windows} can be set non-@code{nil} to force
6229: truncation in all windows less than the full width of the screen,
6230: independent of the buffer being displayed and its value for
6231: @code{truncate-lines}. @xref{Continuation Lines}.@refill
6232:
6233: Horizontal scrolling is often used in side-by-side windows.
6234: @xref{Display}.
6235:
6236: @node Other Window, Pop Up Window, Split Window, Windows
6237: @section Using Other Windows
6238:
6239: @table @kbd
6240: @item C-x o
6241: Select another window (@code{other-window}). That is @kbd{o}, not zero.
6242: @item C-M-v
6243: Scroll the next window (@code{scroll-other-window}).
6244: @item M-x compare-windows
6245: Find next place where the text in the selected window does not match
6246: the text in the next window.
6247: @end table
6248:
6249: @kindex C-x o
6250: @findex other-window
6251: To select a different window, use @kbd{C-x o} (@code{other-window}).
6252: That is an @kbd{o}, for `other', not a zero. When there are more than two
6253: windows, this command moves through all the windows in a cyclic order,
6254: generally top to bottom and left to right. From the rightmost and
6255: bottommost window, it goes back to the one at the upper left corner. A
6256: numeric argument means to move several steps in the cyclic order of
6257: windows. A negative argument moves around the cycle in the opposite order.
6258: When the minibuffer is active, the minibuffer is the last window in the
6259: cycle; you can switch from the minibuffer window to one of the other
6260: windows, and later switch back and finish supplying the minibuffer argument
6261: that is requested. @xref{Minibuffer Edit}.
6262:
6263: @kindex C-M-v
6264: @findex scroll-other-window
6265: The usual scrolling commands (@pxref{Display}) apply to the selected
6266: window only, but there is one command to scroll the next window.
6267: @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that @w{@kbd{C-x o}}
6268: would select. It takes arguments, positive and negative, like @kbd{C-v}.
6269:
6270: @findex compare-windows
6271: The command @kbd{M-x compare-windows} compares the text in the current
6272: window with that in the next window. Comparison starts at point in each
6273: window. Point moves forward in each window, a character at a time in each
6274: window, until the next characters in the two windows are different. Then
6275: the command is finished.
6276:
6277: @node Pop Up Window, Change Window, Other Window, Windows
6278: @section Displaying in Another Window
6279:
6280: @kindex C-x 4
6281: @kbd{C-x 4} is a prefix key for commands that select another window
6282: (splitting the window if there is only one) and select a buffer in that
6283: window. Different @kbd{C-x 4} commands have different ways of finding the
6284: buffer to select.
6285:
6286: @findex switch-to-buffer-other-window
6287: @findex find-file-other-window
6288: @findex find-tag-other-window
6289: @findex dired-other-window
6290: @findex mail-other-window
6291: @table @kbd
6292: @item C-x 4 b @var{bufname} @key{RET}
6293: Select buffer @var{bufname} in another window. This runs
6294: @code{switch-to-buffer-other-window}.
6295: @item C-x 4 f @var{filename} @key{RET}
6296: Visit file @var{filename} and select its buffer in another window. This
6297: runs @code{find-file-other-window}. @xref{Visiting}.
6298: @item C-x 4 d @var{directory} @key{RET}
6299: Select a Dired buffer for directory @var{directory} in another window.
6300: This runs @code{dired-other-window}. @xref{Dired}.
6301: @item C-x 4 m
6302: Start composing a mail message in another window. This runs
6303: @code{mail-other-window}, and its same-window version is @kbd{C-x m}
6304: (@pxref{Sending Mail}).
6305: @item C-x 4 .
6306: Find a tag in the current tag table in another window. This runs
6307: @code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
6308: (@pxref{Tags}).
6309: @end table
6310:
6311: @node Change Window,, Pop Up Window, Windows
6312: @section Deleting and Rearranging Windows
6313:
6314: @table @kbd
6315: @item C-x 0
6316: Get rid of the selected window (@code{kill-window}). That is a zero.
6317: @item C-x 1
6318: Get rid of all windows except the selected one (@code{delete-other-windows}).
6319: @item C-x ^
6320: Make the selected window taller, at the expense of the other(s)
6321: (@code{enlarge-window}).
6322: @item C-x @}
6323: Widen the selected window (@code{enlarge-window-horizontally}).
6324: @end table
6325:
6326: @kindex C-x 0
6327: @findex delete-window
6328: To delete a window, type @kbd{C-x 0} (@code{delete-window}). (That is a
6329: zero.) The space occupied by the deleted window is distributed among the
6330: other active windows (but not the minibuffer window, even if that is active
6331: at the time). Once a window is deleted, its attributes are forgotten;
6332: there is no automatic way to make another window of the same shape or
6333: showing the same buffer. But the buffer continues to exist, and you can
6334: select it in any window with @kbd{C-x b}.
6335:
6336: @kindex C-x 1
6337: @findex delete-other-windows
6338: @kbd{C-x 1} (@code{delete-other-windows}) is more powerful than @kbd{C-x 0};
6339: it deletes all the windows except the selected one (and the minibuffer);
6340: the selected window expands to use the whole screen except for the echo
6341: area.
6342:
6343: @kindex C-x ^
6344: @findex enlarge-window
6345: @kindex C-x @}
6346: @findex enlarge-window-horizontally
6347: @vindex window-min-height
6348: @vindex window-min-width
6349: To readjust the division of space among existing windows, use @kbd{C-x ^}
6350: (@code{enlarge-window}). It makes the currently selected window get one
6351: line bigger, or as many lines as is specified with a numeric argument.
6352: With a negative argument, it makes the selected window smaller. @kbd{C-x
6353: @}} (@code{enlarge-window-horizontally}) makes the selected window wider
6354: by the specified number of columns. The extra screen space given to a
6355: window comes from one of its neighbors, if that is possible; otherwise, all
6356: the competing windows are shrunk in the same proportion. If this makes any
6357: windows too small, those windows are deleted and their space is divided up.
6358: The minimum size is specified by the variables @code{window-min-height} and
6359: @code{window-min-width}.
6360:
6361: @node Major Modes, Indentation, Windows, Top
6362: @chapter Major Modes
6363: @cindex major modes
6364: @kindex TAB
6365: @kindex DEL
6366: @kindex LFD
6367:
6368: Emacs has many different @dfn{major modes}, each of which customizes
6369: Emacs for editing text of a particular sort. The major modes are mutually
6370: exclusive, and each buffer has one major mode at any time. The mode line
6371: normally contains the name of the current major mode, in parentheses.
6372: @xref{Mode Line}.
6373:
6374: The least specialized major mode is called @dfn{Fundamental mode}. This
6375: mode has no mode-specific redefinitions or variable settings, so that each
6376: Emacs command behaves in its most general manner, and each option is in its
6377: default state. For editing any specific type of text, such as Lisp code or
6378: English text, you should switch to the appropriate major mode, such as Lisp
6379: mode or Text mode.
6380:
6381: Selecting a major mode changes the meanings of a few keys to become more
6382: specifically adapted to the language being edited. The ones which are
6383: changed frequently are @key{TAB}, @key{DEL}, and @key{LFD}. In addition,
6384: the commands which handle comments use the mode to determine how comments
6385: are to be delimited. Many major modes redefine the syntactical properties
6386: of characters appearing in the buffer. @xref{Syntax}.
6387:
6388: The major modes fall into three major groups. Lisp mode (which has
6389: several variants), C mode and Muddle mode are for specific programming
6390: languages. Text mode, Nroff mode, @TeX{} mode and Outline mode are for
6391: editing English text. The remaining major modes are not intended for use
6392: on users' files; they are used in buffers created for specific purposes by
6393: Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), and
6394: Mail mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), and Shell
6395: mode for buffers used for communicating with an inferior shell process
6396: (@pxref{Interactive Shell}).
6397:
6398: Most programming language major modes specify that only blank lines
6399: separate paragraphs. This is so that the paragraph commands remain useful.
6400: @xref{Paragraphs}. They also cause Auto Fill mode to use the definition of
6401: @key{TAB} to indent the new lines it creates. This is because most lines
6402: in a program are usually indented. @xref{Indentation}.
6403:
6404: @menu
6405: * Choosing Modes:: How major modes are specified or chosen.
6406: @end menu
6407:
6408: @node Choosing Modes,,Major Modes,Major Modes
6409: @section How Major Modes are Chosen
6410: @cindex mode selection
6411: @cindex selection of mode
6412: @cindex choosing a mode
6413:
6414: You can select a major mode explicitly for the current buffer, but
6415: most of the time Emacs determines which mode to use based on the file
6416: name or some text in the file.
6417:
6418: Explicit selection of a new major mode is done with a @kbd{M-x} command.
6419: From the name of a major mode, add @code{-mode} to get the name of a
6420: command to select that mode. Thus, you can enter Lisp mode by executing
6421: @kbd{M-x lisp-mode}.
6422:
6423: @vindex auto-mode-alist
6424: When you visit a file, Emacs usually chooses the right major mode based
6425: on the file's name. For example, files whose names end in @code{.c} are
6426: edited in C mode. The correspondence between file names and major mode is
6427: controlled by the variable @code{auto-mode-alist}. Its value is a list in
6428: which each element has the form
6429:
6430: @example
6431: (@var{regexp} . @var{mode-function})
6432: @end example
6433:
6434: @noindent
6435: For example, one element normally found in the list has the form
6436: @code{(@t{"\\.c$"} . c-mode)}, and it is responsible for selecting C mode
6437: for files whose names end in @file{.c}. (Note that @samp{\\} is needed in
6438: Lisp syntax to include a @samp{\} in the string, which is needed to
6439: suppress the special meaning of @samp{.} in regexps.) The only practical
6440: way to change this variable is with Lisp code.
6441:
6442: You can specify which major mode should be used for editing a certain
6443: file by a special sort of text in the first nonblank line of the file. The
6444: mode name should appear in this line both preceded and followed by
6445: @samp{-*-}. Other text may appear on the line as well. For example,
6446:
6447: @example
6448: ;-*-Lisp-*-
6449: @end example
6450:
6451: @noindent
6452: tells Emacs to use Lisp mode. Note how the semicolon is used to make Lisp
6453: treat this line as a comment. Such an explicit specification overrides any
6454: defaulting based on the file name.
6455:
6456: Another format of mode specification is
6457:
6458: @example
6459: -*-Mode: @var{modename};-*-
6460: @end example
6461:
6462: @noindent
6463: which allows other things besides the major mode name to be specified.
6464: However, Emacs does not look for anything except the mode name.
6465:
6466: The major mode can also be specified in a local variables list.
6467: @xref{File Variables}.
6468:
6469: @vindex default-major-mode
6470: When a file is visited that does not specify a major mode to use, or when
6471: a new buffer is created with @kbd{C-x b}, the major mode used is that
6472: specified by the variable @code{default-major-mode}. Normally this value
6473: is the symbol @code{fundamental-mode}, which specifies Fundamental mode.
6474: If @code{default-major-mode} is @code{nil}, the major mode is taken from
6475: the previously selected buffer.
6476:
6477: @findex normal-mode
6478: The command @kbd{M-x normal-mode} recalculates the major mode from the
6479: visited file name and the contents of the buffer.
6480:
6481: @node Indentation, Text, Major Modes, Top
6482: @chapter Indentation
6483: @cindex indentation
6484:
6485: @c WideCommands
6486: @table @kbd
6487: @item @key{TAB}
6488: Indent current line ``appropriately'' in a mode-dependent fashion.
6489: @item @key{LFD}
6490: Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
6491: @item M-^
6492: Merge two lines (@code{delete-indentation}). This would cancel out
6493: the effect of @key{LFD}.
6494: @item C-M-o
6495: Split line at point; text on the line after point becomes a new line
6496: indented to the same column that it now starts in (@code{split-line}).
6497: @item M-m
6498: Move (forward or back) to the first nonblank character on the current
6499: line (@code{back-to-indentation}).
6500: @item C-M-\
6501: Indent several lines to same column (@code{indent-region}).
6502: @item C-x @key{TAB}
6503: Shift block of lines rigidly right or left (@code{indent-rigidly}).
6504: @item M-i
6505: Indent from point to the next prespecified tab stop column
6506: (@code{tab-to-tab-stop}).
6507: @item M-x indent-relative
6508: Indent from point to under an indentation point in the previous line.
6509: @end table
6510:
6511: @kindex TAB
6512: @cindex indentation
6513: Most programming languages have some indentation convention. For Lisp
6514: code, lines are indented according to their nesting in parentheses. The
6515: same general idea is used for C code, though many details are different.
6516:
6517: Whatever the language, to indent a line, use the @key{TAB} command. Each
6518: major mode defines this command to perform the sort of indentation
6519: appropriate for the particular language. In Lisp mode, @key{TAB} aligns
6520: the line according to its depth in parentheses. No matter where in the
6521: line you are when you type @key{TAB}, it aligns the line as a whole. In C
6522: mode, @key{TAB} implements a subtle and sophisticated indentation style that
6523: knows about many aspects of C syntax.
6524:
6525: @kindex TAB
6526: In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
6527: indents to the next tab stop column. You can set the tab stops with
6528: @kbd{M-x edit-tab-stops}.
6529:
6530: @menu
6531: * Indentation Commands:: Various commands and techniques for indentation.
6532: * Tab Stops:: You can set arbitrary "tab stops" and then
6533: indent to the next tab stop when you want to.
6534: * Just Spaces:: You can request indentation using just spaces.
6535: @end menu
6536:
6537: @node Indentation Commands, Tab Stops, Indentation, Indentation
6538: @section Indentation Commands and Techniques
6539: @c ??? Explain what Emacs has instead of space-indent-flag.
6540:
6541: If you just want to insert a tab character in the buffer, you can type
6542: @kbd{C-q @key{TAB}}.
6543:
6544: @kindex M-m
6545: @findex back-to-indentation
6546: @c !!! rewrote to prevent overfull hbox
6547: To move over the indentation on a line, type @kbd{Meta-m}.
6548: This command, given anywhere on a line,
6549: positions point at the first nonblank character on the line
6550: (@code{back-to-indentation}).
6551:
6552: To insert an indented line before the current line, do @kbd{C-a C-o
6553: @key{TAB}}. To make an indented line after the current line, use @kbd{C-e
6554: @key{LFD}}.
6555:
6556: @kindex C-M-o
6557: @findex split-line
6558: @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
6559: the line vertically down, so that the current line becomes two lines.
6560: @kbd{C-M-o} first moves point forward over any spaces and tabs. Then it
6561: inserts after point a newline and enough indentation to reach the same
6562: column point is on. Point remains before the inserted newline; in this
6563: regard, @kbd{C-M-o} resembles @kbd{C-o}.
6564:
6565: @kindex M-\
6566: @kindex M-^
6567: @findex delete-horizontal-space
6568: @findex delete-indentation
6569: To join two lines cleanly, use the @kbd{Meta-^}
6570: (@code{delete-indentation}) command to delete the indentation at the
6571: front of the current line, and the line boundary as well. They are
6572: replaced by a single space, or by no space if point after joining is at
6573: the beginning of a line or before a @samp{)} or after a @samp{(}. To
6574: delete just the indentation of a line, go to the beginning of the line
6575: and use @kbd{Meta-\} (@code{delete-horizontal-space}), which deletes all
6576: spaces and tabs around the cursor.
6577:
6578: @kindex C-M-\
6579: @kindex C-x TAB
6580: @findex indent-region
6581: @findex indent-rigidly
6582: There are also commands for changing the indentation of several lines at
6583: once. @kbd{Control-Meta-\} (@code{indent-region}) gives each line which
6584: begins in the region the ``usual'' indentation by invoking @key{TAB} at the
6585: beginning of the line. A numeric argument specifies the column to indent
6586: to, and each line is shifted left or right so that its first nonblank
6587: character appears in that column. @kbd{C-x @key{TAB}}
6588: (@code{indent-rigidly}) moves all of the lines in the region right by its
6589: argument (left, for negative arguments). The whole group of lines moves
6590: rigidly sideways, which is how the command gets its name.@refill
6591:
6592: @findex indent-relative
6593: @kbd{M-x indent-relative} indents at point based on the previous line
6594: (actually, the last nonempty line.) It inserts whitespace at point, moving
6595: point, until it is underneath an indentation point in the previous line.
6596: An indentation point is the end of a sequence of whitespace or the end of
6597: the line. If point is farther right than any indentation point in the
6598: previous line, the whitespace before point is deleted and the first
6599: indentation point then applicable is used. If no indentation point is
6600: applicable even then, @code{tab-to-tab-stop} is run (see next section).
6601:
6602: @code{indent-relative} is the definition of @key{TAB} in Indented Text
6603: mode. @xref{Text}.
6604:
6605: @node Tab Stops, Just Spaces, Indentation Commands, Indentation
6606: @section Tab Stops
6607:
6608: @kindex M-i
6609: @findex tab-to-tab-stop
6610: For typing in tables, you can use Text mode's definition of @key{TAB},
6611: @code{tab-to-tab-stop}. This command inserts indentation before point,
6612: enough to reach the next tab stop column. If you are not in Text mode,
6613: this function can be found on @kbd{M-i} anyway.
6614:
6615: @findex edit-tab-stops
6616: @findex edit-tab-stops-note-changes
6617: @kindex C-c C-c (Edit Tab Stops)
6618: @vindex tab-stop-list
6619: The tab stops used by @kbd{M-i} can be set arbitrarily by the user.
6620: They are stored in a variable called @code{tab-stop-list}, as a list of
6621: column-numbers in increasing order.
6622:
6623: The convenient way to set the tab stops is using @kbd{M-x edit-tab-stops},
6624: which creates and selects a buffer containing a description of the tab stop
6625: settings. You can edit this buffer to specify different tab stops, and
6626: then type @kbd{C-c C-c} to make those new tab stops take effect. In the
6627: tab stop buffer, @w{@kbd{C-c C-c}} runs the function
6628: @code{edit-tab-stops-note-changes} rather than its usual definition
6629: @code{save-buffer}. @code{edit-tab-stops} records which buffer was current
6630: when you invoked it, and stores the tab stops back in that buffer; normally
6631: all buffers share the same tab stops and changing them in one buffer
6632: affects all, but if you happen to make @code{tab-stop-list} local in one
6633: buffer then @code{edit-tab-stops} in that buffer will edit the local
6634: settings.
6635:
6636: Here is what the text representing the tab stops looks like for ordinary
6637: tab stops every eight columns.
6638:
6639: @example
6640: : : : : : :
6641: 0 1 2 3 4
6642: 0123456789012345678901234567890123456789012345678
6643: To install changes, type C-c C-c
6644: @end example
6645:
6646: The first line contains a colon at each tab stop. The remaining lines
6647: are present just to help you see where the colons are and know what to do.
6648:
6649: Note that the tab stops that control @code{tab-to-tab-stop} have nothing
6650: to do with displaying tab characters in the buffer. @xref{Display Vars},
6651: for more information on that.
6652:
6653: @node Just Spaces,, Tab Stops, Indentation
6654: @section Tabs vs. Spaces
6655:
6656: @vindex indent-tabs-mode
6657: Emacs normally uses both tabs and spaces to indent lines. If you prefer,
6658: all indentation can be made from spaces only. To request this, set
6659: @code{indent-tabs-mode} to @code{nil}. This is a per-buffer variable;
6660: altering the variable affects only the current buffer, but there is a
6661: default value which you can change as well. @xref{Locals}.
6662:
6663: @findex tabify
6664: @findex untabify
6665: There are also commands to convert tabs to spaces or vice versa, always
6666: preserving the columns of all nonblank text. @kbd{M-x tabify} scans the
6667: region for sequences of spaces, and converts sequences of at least three
6668: spaces to tabs if that can be done without changing indentation. @kbd{M-x
6669: untabify} changes all tabs in the region to appropriate numbers of spaces.
6670:
6671: @node Text, Programs, Indentation, Top
6672: @chapter Commands for Human Languages
6673: @cindex text
6674:
6675: The term @dfn{text} has two widespread meanings in our area of the
6676: computer field. One is data that is a sequence of characters. Any file
6677: that you edit with Emacs is text, in this sense of the word. The other
6678: meaning is more restrictive: a sequence of characters in a human language
6679: for humans to read (possibly after processing by a text formatter), as
6680: opposed to a program or commands for a program.
6681:
6682: Human languages have syntactic/stylistic conventions that can be
6683: supported or used to advantage by editor commands: conventions involving
6684: words, sentences, paragraphs, and capital letters. This chapter describes
6685: Emacs commands for all of these things. There are also commands for
6686: @dfn{filling}, or rearranging paragraphs into lines of approximately equal
6687: length. The commands for moving over and killing words, sentences
6688: and paragraphs, while intended primarily for editing text, are also often
6689: useful for editing programs.
6690:
6691: Emacs has several major modes for editing human language text.
6692: If the file contains text pure and simple, use Text mode, which customizes
6693: Emacs in small ways for the syntactic conventions of text. For text which
6694: contains embedded commands for text formatters, Emacs has other major modes,
6695: each for a particular text formatter. Thus, for input to @TeX{}, you would
6696: use @TeX{} mode; for input to nroff, Nroff mode.
6697:
6698: @menu
6699: * Text Mode:: The major modes for editing text files.
6700: * Nroff Mode:: The major mode for editing input to the formatter nroff.
6701: * TeX Mode:: The major modes for editing input to the formatter TeX.
6702: * Outline Mode::The major mode for editing outlines.
6703: * Words:: Moving over and killing words.
6704: * Sentences:: Moving over and killing sentences.
6705: * Paragraphs:: Moving over paragraphs.
6706: * Pages:: Moving over pages.
6707: * Filling:: Filling or justifying text
6708: * Case:: Changing the case of text
6709: @end menu
6710:
6711: @node Text Mode, Words, Text, Text
6712: @section Text Mode
6713:
6714: @findex tab-to-tab-stop
6715: @findex edit-tab-stops
6716: @cindex Text mode
6717: @kindex TAB
6718: @findex text-mode
6719: Editing files of text in a human language ought to be done using Text
6720: mode rather than Lisp or Fundamental mode. Invoke @kbd{M-x text-mode} to
6721: enter Text mode. In Text mode, @key{TAB} runs the function
6722: @code{tab-to-tab-stop}, which allows you to use arbitrary tab stops set
6723: with @kbd{M-x edit-tab-stops} (@pxref{Tab Stops}). Features concerned with
6724: comments in programs are turned off except when explicitly invoked. The
6725: syntax table is changed so that periods are not considered part of a word,
6726: while apostrophes, backspaces and underlines are.
6727:
6728: @findex indented-text-mode
6729: @cindex Indented Text mode
6730: A similar variant mode is Indented Text mode, intended for editing text
6731: in which most lines are indented. This mode defines @key{TAB} to run
6732: @code{indent-relative} (@pxref{Indentation}), and makes Auto Fill indent
6733: the lines it creates. The result is that normally a line made by Auto
6734: Filling, or by @key{LFD}, is indented just like the previous line. Use
6735: @kbd{M-x indented-text-mode} to select this mode.
6736:
6737: @vindex text-mode-hook
6738: Entering Text mode or Indented Text mode calls with no arguments the
6739: value of the variable @code{text-mode-hook}, if that value exists and is
6740: not @code{nil}. This value is also called when modes related to Text mode
6741: are entered; this includes Nroff mode, @TeX{} mode, Outline mode and Mail
6742: mode. Your hook can look at the value of @code{major-mode} to see which of
6743: these modes is actually being entered.
6744:
6745: @menu
6746: Three modes similar to Text mode are of use for editing text that is to
6747: be passed through a text formatter before achieving the form in which
6748: humans are to read it.
6749:
6750: * Nroff Mode:: The nroff formatter typesets text.
6751: * TeX Mode:: The TeX formatter typesets text and mathematics.
6752: * Texinfo Mode::Texinfo provides both on-line information and printed output
6753: from the same source file.
6754:
6755: Another similar mode is used for editing outlines. It allows you
6756: to view the text at various levels of detail. You can view either
6757: the outline headings alone or both headings and text; you can also
6758: hide some of the headings at lower levels from view to make the high
6759: level structure more visible.
6760:
6761: * Outline Mode::The major mode for editing outlines.
6762: @end menu
6763:
6764: @node Nroff Mode, TeX Mode, Text Mode, Text Mode
6765: @subsection Nroff Mode
6766:
6767: @cindex nroff
6768: @cindex Nroff mode
6769: @findex nroff-mode
6770: Nroff mode is a mode like Text mode but modified to handle nroff commands
6771: present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It
6772: differs from Text mode in only a few ways. All nroff command lines are
6773: considered paragraph separators, so that filling will never garble the
6774: nroff commands. Pages are separated by @samp{.bp} commands. Comments
6775: start with backslash-doublequote. Also, three special commands are
6776: provided that are not in Text mode:
6777:
6778: @findex forward-text-line
6779: @findex backward-text-line
6780: @findex count-text-lines
6781: @kindex M-n
6782: @kindex M-p
6783: @kindex M-?
6784: @table @kbd
6785: @item M-n
6786: Move to the beginning of the next line that isn't an nroff command
6787: (@code{forward-text-line}). An argument is a repeat count.
6788: @item M-p
6789: Like @kbd{M-n} but move up (@code{backward-text-line}).
6790: @item M-?
6791: Prints in the echo area the number of text lines (lines that are not
6792: nroff commands) in the region (@code{count-text-lines}).
6793: @end table
6794:
6795: @cindex Electric Nroff mode
6796: @findex electric-nroff-mode
6797: The other feature of Nroff mode is Electric Nroff newline mode. This
6798: is a minor mode that you can turn on or off with @kbd{M-x
6799: electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
6800: time you use @key{RET} to end a line that contains an nroff command that
6801: opens a kind of grouping, it also inserts the matching nroff command to
6802: close that grouping, on the following line. For example, if you are at
6803: the beginning of a line and type @kbd{.@: ( b @key{RET}}, this inserts
6804: the matching command @samp{.)b} on a new line following point.
6805:
6806: @vindex nroff-mode-hook
6807: Entering Nroff mode calls with no arguments the value of the variable
6808: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
6809: does the same with the variable @code{nroff-mode-hook}.
6810:
6811: @node TeX Mode, Texinfo Mode, Nroff Mode, Text Mode
6812: @subsection @TeX{} Mode
6813: @cindex TeX
6814: @cindex LaTeX
6815: @cindex TeX mode
6816: @findex TeX-mode
6817: @findex tex-mode
6818: @findex plain-tex-mode
6819: @findex LaTeX-mode
6820: @findex plain-TeX-mode
6821: @findex latex-mode
6822:
6823: @TeX{} is a powerful text formatter written by Donald Knuth; it is also
6824: free, like GNU Emacs. La@TeX{} is a simplified input format for @TeX{},
6825: implemented by @TeX{} macros. It comes with @TeX{}.@refill
6826:
6827: Emacs has a special @TeX{} mode for editing @TeX{} input files.
6828: It provides facilities for checking the balance of delimiters and for
6829: invoking @TeX{} on all or part of the file.
6830:
6831: @TeX{} mode has two variants, Plain @TeX{} mode and La@TeX{} mode
6832: (actually two distinct major modes which differ only slightly). They are
6833: designed for editing the two different input formats. The command @kbd{M-x
6834: tex-mode} looks at the contents of the buffer to determine whether the
6835: contents appear to be La@TeX{} input or not; it then selects the
6836: appropriate mode. If it can't tell which is right (e.g., the buffer is
6837: empty), the variable @code{TeX-default-mode} controls which mode is used.
6838:
6839: The commands @kbd{M-x plain-tex-mode} and @kbd{M-x latex-mode} explicitly
6840: select the two variants of @TeX{} mode. Use these commands when @kbd{M-x
6841: tex-mode} does not guess right.@refill
6842:
6843: @menu
6844: * Editing: TeX Editing. Special commands for editing in TeX mode.
6845: * Printing: TeX Print. Commands for printing part of a file with TeX.
6846: @end menu
6847:
6848: @c !!! Here is information about obtaining TeX. Update it whenever.
6849: @c Last updated by RJC on 8 October 1992
6850: @c based on message from elisabet@@u.washington.edu
6851: @TeX{} for Unix systems can be obtained from the University of Washington
6852: for a distribution fee.
6853:
6854: To order a full distribution, send $200.00 for a 1/2-inch 9-track 1600
6855: bpi (@code{tar} or @code{cpio}) tape reel, or $210.00 for a 1/4-inch
6856: 4-track QIC-24 (@code{tar} or @code{cpio}) cartridge, to:@refill
6857:
6858: @display
6859: Northwest Computing Support Center
6860: DR-10, Thomson Hall 35
6861: University of Washington
6862: Seattle, Washington 98195
6863: @end display
6864:
6865: @noindent
6866: Please make checks payable to the University of Washington.@refill
6867:
6868: Prepaid orders are preferred but purchase orders are acceptable;
6869: however, purchase orders carry an extra charge of $10.00, to pay for
6870: processing.@refill
6871:
6872: Overseas sites: please add to the base cost $20.00 for shipment via
6873: air parcel post, or $30.00 for shipment via courier.@refill
6874:
6875: Please check with the Northwest Computing Support Center at the
6876: University of Washington for current prices and formats:@refill
6877:
6878: @example
6879: @group
6880: @r{telephone:} (206) 543-6259
6881: @r{email:} elisabet@@u.washington.edu
6882: @end group
6883: @end example
6884:
6885: @node TeX Editing,TeX Print,TeX Mode,TeX Mode
6886: @subsubsection @TeX{} Editing Commands
6887:
6888: Here are the special commands provided in @TeX{} mode for editing the
6889: text of the file.
6890:
6891: @table @kbd
6892: @item "
6893: Insert, according to context, either @samp{@`@`} or @samp{"} or
6894: @samp{@'@'} (@code{TeX-insert-quote}).
6895: @item @key{LFD}
6896: Insert a paragraph break (two newlines) and check the previous
6897: paragraph for unbalanced braces or dollar signs
6898: (@code{TeX-terminate-paragraph}).
6899: @item M-x validate-TeX-buffer
6900: Check each paragraph in the buffer for unbalanced braces or dollar signs.
6901: @c !!! following generates acceptable underfull hbox
6902: @item M-@{
6903: Insert @samp{@{@}} and position point between them (@code{TeX-insert-braces}).
6904: @item M-@}
6905: Move forward past the next unmatched close brace (@code{up-list}).
6906: @item C-c C-f
6907: Close a block for La@TeX{} (@code{TeX-close-LaTeX-block}).
6908: @end table
6909:
6910: @findex TeX-insert-quote
6911: @kindex " (TeX mode)
6912: In @TeX{}, the character @samp{"} is not normally used; use @samp{``}
6913: to start a quotation and @samp{''} to end one. @TeX{} mode defines the key
6914: @kbd{"} to insert @samp{``} after whitespace or an open brace, @samp{"}
6915: after a backslash, or @samp{''} otherwise. This is done by the command
6916: @code{TeX-insert-quote}. If you need the character @samp{"} itself in
6917: unusual contexts, use @kbd{C-q} to insert it. Also, @kbd{"} with a
6918: numeric argument always inserts that number of @samp{"} characters.
6919:
6920: In @TeX{} mode, @samp{$} has a special syntax code which attempts to
6921: understand the way @TeX{} math mode delimiters match. When you insert a
6922: @samp{$} that is meant to exit math mode, the position of the matching
6923: @samp{$} that entered math mode is displayed for a second. This is the
6924: same feature that displays the open brace that matches a close brace that
6925: is inserted. However, there is no way to tell whether a @samp{$} enters
6926: math mode or leaves it; so when you insert a @samp{$} that enters math
6927: mode, the previous @samp{$} position is shown as if it were a match, even
6928: though they are actually unrelated.
6929:
6930: @findex TeX-insert-braces
6931: @kindex M-@{ (TeX mode)
6932: @findex up-list
6933: @kindex M-@} (TeX mode)
6934: If you prefer to keep braces balanced at all times, you can use @kbd{M-@{}
6935: (@code{TeX-insert-braces}) to insert a pair of braces. It leaves point
6936: between the two braces so you can insert the text that belongs inside.
6937: Afterward, use the command @kbd{M-@}} (@code{up-list}) to move forward
6938: past the close brace.
6939:
6940: @findex validate-TeX-buffer
6941: @findex TeX-terminate-paragraph
6942: @kindex LFD (TeX mode)
6943: There are two commands for checking the matching of braces. @key{LFD}
6944: (@code{TeX-terminate-paragraph}) checks the paragraph before point, and
6945: inserts two newlines to start a new paragraph. It prints a message in the
6946: echo area if any mismatch is found. @kbd{M-x validate-TeX-buffer} checks
6947: the entire buffer, paragraph by paragraph. When it finds a paragraph that
6948: contains a mismatch, it displays point at the beginning of the paragraph
6949: for a few seconds and pushes a mark at that spot. Scanning continues
6950: until the whole buffer has been checked or until you type another key.
6951: The positions of the last several paragraphs with mismatches can be
6952: found in the mark ring (@pxref{Mark Ring}).
6953:
6954: Note that square brackets and parentheses are matched in @TeX{} mode, not
6955: just braces. This is wrong for the purpose of checking @TeX{} syntax.
6956: However, parentheses and square brackets are likely to be used in text as
6957: matching delimiters and it is useful for the various motion commands and
6958: automatic match display to work with them.
6959:
6960: @findex TeX-close-LaTeX-block
6961: @kindex C-c C-f (LaTeX mode)
6962: In La@TeX{} input, @samp{\begin} and @samp{\end} commands must balance.
6963: After you insert a @samp{\begin}, use @kbd{C-c C-f}
6964: (@code{TeX-close-LaTeX-block}) to insert automatically a matching
6965: @samp{\end} (on a new line following the @samp{\begin}). A blank line is
6966: inserted between the two, and point is left there.@refill
6967:
6968: @node TeX Print,,TeX Editing,TeX Mode
6969: @subsubsection @TeX{} Printing Commands
6970:
6971: You can invoke @TeX{} as an inferior of Emacs on either the entire
6972: contents of the buffer or just a region at a time. Running @TeX{} in
6973: this way on just one chapter is a good way to see what your changes
6974: look like without taking the time to format the entire file.
6975:
6976: @table @kbd
6977: @item C-c C-r
6978: Invoke @TeX{} on the current region, plus the buffer's header
6979: (@code{TeX-region}).
6980: @item C-c C-b
6981: Invoke @TeX{} on the entire current buffer (@code{TeX-buffer}).
6982: @item C-c C-l
6983: Recenter the window showing output from the inferior @TeX{} so that
6984: the last line can be seen (@code{TeX-recenter-output-buffer}).
6985: @item C-c C-k
6986: Kill the inferior @TeX{} (@code{TeX-kill-job}).
6987: @item C-c C-p
6988: Print the output from the last @kbd{C-c C-r} or @kbd{C-c C-b} command
6989: (@code{TeX-print}).
6990: @item C-c C-q
6991: Show the printer queue (@code{TeX-show-print-queue}).
6992: @end table
6993:
6994: @findex TeX-buffer
6995: @kindex C-c C-b (TeX mode)
6996: @findex TeX-print
6997: @kindex C-c C-p (TeX mode)
6998: @findex TeX-show-print-queue
6999: @kindex C-c C-q (TeX mode)
7000: You can pass the current buffer through an inferior @TeX{} by means of
7001: @kbd{C-c C-b} (@code{TeX-buffer}). The formatted output appears in a file
7002: in @file{/tmp}; to print it, type @kbd{C-c C-p} (@code{TeX-print}).
7003: Afterward use @kbd{C-c C-q} (@code{TeX-show-print-queue}) to view the
7004: progress of your output towards being printed.
7005:
7006: @findex TeX-kill-job
7007: @kindex C-c C-k (TeX mode)
7008: @findex TeX-recenter-output-buffer
7009: @kindex C-c C-l (TeX mode)
7010: The console output from @TeX{}, including any error messages, appears in a
7011: buffer called @samp{*TeX-shell*}. If @TeX{} gets an error, you can switch
7012: to this buffer and feed it input (this works as in Shell mode;
7013: @pxref{Interactive Shell}). Without switching to this buffer you can scroll
7014: it so that its last line is visible by typing @kbd{C-c C-l}.
7015:
7016: Type @kbd{C-c C-k} (@code{TeX-kill-job}) to kill the @TeX{} process if
7017: you see that its output is no longer useful. Using @kbd{C-c C-b} or
7018: @kbd{C-c C-r} also kills any @TeX{} process still running.@refill
7019:
7020: @findex TeX-region
7021: @kindex C-c C-r (TeX mode)
7022: You can also pass an arbitrary region through an inferior @TeX{} by typing
7023: @kbd{C-c C-r} (@code{TeX-region}). This is tricky, however, because most files
7024: of @TeX{} input contain commands at the beginning to set parameters and
7025: define macros, without which no later part of the file will format
7026: correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a
7027: part of the file as containing essential commands; it is included before
7028: the specified region as part of the input to @TeX{}. The designated part
7029: of the file is called the @dfn{header}.
7030:
7031: @cindex header (TeX mode)
7032: To indicate the bounds of the header in Plain @TeX{} mode, you insert two
7033: special strings in the file. Insert @samp{%**start of header} before the
7034: header, and @samp{%**end of header} after it. Each string must appear
7035: entirely on one line, but there may be other text on the line before or
7036: after. The lines containing the two strings are included in the header.
7037: If @samp{%**start of header} does not appear within the first 100 lines of
7038: the buffer, @kbd{C-c C-r} assumes that there is no header.
7039:
7040: In La@TeX{} mode, the header begins with @samp{\documentstyle} and ends
7041: with @samp{\begin@{document@}}. These are commands that La@TeX{} requires
7042: you to use in any case, so nothing special needs to be done to identify the
7043: header.
7044:
7045: @vindex TeX-mode-hook
7046: @vindex LaTeX-mode-hook
7047: @vindex plain-TeX-mode-hook
7048: Entering either kind of @TeX{} mode calls with no arguments the value of
7049: the variable @code{text-mode-hook}, if that value exists and is not
7050: @code{nil}; then it does the same with the variable @code{TeX-mode-hook}.
7051: Finally it does the same with either @code{plain-TeX-mode-hook} or
7052: @code{LaTeX-mode-hook}.
7053:
7054: @node Texinfo Mode, Outline Mode, TeX Mode, Text Mode
7055: @subsection Texinfo Mode
7056: @cindex Texinfo mode
7057: @findex texinfo-mode
7058:
7059: Texinfo is a documentation system that uses a single source file to
7060: produce both on-line information and printed output. This means that
7061: instead of writing two different documents, one for the on-line help or
7062: other on-line information and the other for a typeset manual or other
7063: printed work, you need write only one document. When the work is
7064: revised, you need revise only one document. (You can read the on-line
7065: information, known as an @dfn{Info file}, with an Info
7066: documentation-reading program. @inforef{Top, info, info}, for more
7067: information about Info.) Texinfo is the format in which documentation
7068: for GNU utilities and libraries is written.
7069:
7070: Texinfo mode provides special features for working with Texinfo files
7071: including utilities to construct Info menus and pointers automatically,
7072: keybindings to insert frequently used formatting commands, and
7073: keybindings for commands to format both for Info and for printing.
7074:
7075: Texinfo mode is described in @ref{Texinfo Mode, , Using Texinfo Mode,
7076: texinfo, Texinfo; The GNU Documentation Format}.
7077:
7078: @node Outline Mode,, Texinfo Mode, Text Mode
7079: @subsection Outline Mode
7080: @cindex Outline mode
7081: @cindex outlines
7082: @cindex selective display
7083: @cindex invisible lines
7084:
7085: @findex outline-mode
7086: Outline mode is a major mode much like Text mode but intended for editing
7087: outlines. It allows you to make parts of the text temporarily invisible
7088: so that you can see just the overall structure of the outline. Type
7089: @kbd{M-x outline-mode} to turn on Outline mode in the current buffer.
7090:
7091: @vindex outline-mode-hook
7092: Entering Outline mode calls with no arguments the value of the variable
7093: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
7094: does the same with the variable @code{outline-mode-hook}.
7095:
7096: When a line is invisible in outline mode, it does not appear on the
7097: screen. The screen appears exactly as if the invisible line
7098: were deleted, except that an ellipsis (three periods in a row) appears
7099: at the end of the previous visible line (only one ellipsis no matter
7100: how many invisible lines follow).
7101:
7102: All editing commands treat the text of the invisible line as part of the
7103: previous visible line. For example, @kbd{C-n} moves onto the next visible
7104: line. Killing an entire visible line, including its terminating newline,
7105: really kills all the following invisible lines along with it; yanking it
7106: all back yanks the invisible lines and they remain invisible.
7107:
7108: @menu
7109: * Format: Outline Format. What the text of an outline looks like.
7110: * Motion: Outline Motion. Special commands for moving through outlines.
7111: * Visibility: Outline Visibility. Commands to control what is visible.
7112: @end menu
7113:
7114: @node Outline Format,Outline Motion,Outline Mode, Outline Mode
7115: @subsubsection Format of Outlines
7116:
7117: @cindex heading lines (Outline mode)
7118: @cindex body lines (Outline mode)
7119: Outline mode assumes that the lines in the buffer are of two types:
7120: @dfn{heading lines} and @dfn{body lines}. A heading line represents a topic in the
7121: outline. Heading lines start with one or more stars; the number of stars
7122: determines the depth of the heading in the outline structure. Thus, a
7123: heading line with one star is a major topic; all the heading lines with
7124: two stars between it and the next one-star heading are its subtopics; and
7125: so on. Any line that is not a heading line is a body line. Body lines
7126: belong to the preceding heading line. Here is an example:
7127:
7128: @example
7129: * Food
7130:
7131: This is the body,
7132: which says something about the topic of food.
7133:
7134: ** Delicious Food
7135:
7136: This is the body of the second-level header.
7137:
7138: ** Distasteful Food
7139:
7140: This could have
7141: a body too, with
7142: several lines.
7143:
7144: *** Dormitory Food
7145:
7146: * Shelter
7147:
7148: A second first-level topic with its header line.
7149: @end example
7150:
7151: A heading line together with all following body lines is called
7152: collectively an @dfn{entry}. A heading line together with all following
7153: deeper heading lines and their body lines is called a @dfn{subtree}.
7154:
7155: @vindex outline-regexp
7156: You can customize the criterion for distinguishing heading lines
7157: by setting the variable @code{outline-regexp}. Any line whose
7158: beginning has a match for this regexp is considered a heading line.
7159: Matches that start within a line (not at the beginning) do not count.
7160: The length of the matching text determines the level of the heading;
7161: longer matches make a more deeply nested level. Thus, for example,
7162: if a text formatter has commands @samp{@@chapter}, @samp{@@section}
7163: and @samp{@@subsection} to divide the document into chapters and
7164: sections, you could make those lines count as heading lines by
7165: setting @code{outline-regexp} to @samp{"@@chap\\|@@\$sub\$*section"}.
7166: Note the trick: the two words @samp{chapter} and @samp{section} are equally
7167: long, but by defining the regexp to match only @samp{chap} we ensure
7168: that the length of the text matched on a chapter heading is shorter,
7169: so that Outline mode will know that sections are contained in chapters.
7170: This works as long as no other command starts with @samp{@@chap}.
7171:
7172: Outline mode makes a line invisible by changing the newline before it
7173: into an @sc{ascii} Control-M (code 015). Most editing commands that work on
7174: lines treat an invisible line as part of the previous line because,
7175: strictly speaking, it @i{is} part of that line, since there is no longer a
7176: newline in between. When you save the file in Outline mode, Control-M
7177: characters are saved as newlines, so the invisible lines become ordinary
7178: lines in the file. But saving does not change the visibility status of a
7179: line inside Emacs.
7180:
7181: @node Outline Motion,Outline Visibility,Outline Format,Outline Mode
7182: @subsubsection Outline Motion Commands
7183:
7184: There are some special motion commands in Outline mode that move
7185: backward and forward to heading lines.
7186:
7187: @table @kbd
7188: @item C-c C-n
7189: Move point to the next visible heading line
7190: (@code{outline-next-visible-heading}).
7191: @c !!! following generates acceptable underfull hbox
7192: @item C-c C-p
7193: Move point to the previous visible heading line
7194: (@code{outline-previous-visible-heading}).
7195: @item C-c C-f
7196: Move point to the next visible heading line at the same level
7197: as the one point is on (@code{outline-forward-same-level}).
7198: @item C-c C-b
7199: Move point to the previous visible heading line at the same level
7200: (@code{outline-backward-same-level}).
7201: @item C-c C-u
7202: Move point up to a lower-level (more inclusive) visible heading line
7203: (@code{outline-up-heading}).
7204: @end table
7205:
7206: @findex outline-next-visible-heading
7207: @findex outline-previous-visible-heading
7208: @kindex C-c C-n (Outline mode)
7209: @kindex C-c C-p (Outline mode)
7210: @kbd{C-c C-n} (@code{next-visible-heading}) moves down to the next
7211: heading line. @kbd{C-c C-p} (@code{previous-visible-heading}) moves
7212: similarly backward. Both accept numeric arguments as repeat counts. The
7213: names emphasize that invisible headings are skipped, but this is not really
7214: a special feature. All editing commands that look for lines ignore the
7215: invisible lines automatically.@refill
7216:
7217: @findex outline-up-heading
7218: @findex outline-forward-same-level
7219: @findex outline-backward-same-level
7220: @kindex C-c C-f (Outline mode)
7221: @kindex C-c C-b (Outline mode)
7222: @kindex C-c C-u (Outline mode)
7223: @c !!! written verbosely to prevent overfull hbox
7224: More advanced motion commands understand the levels of headings.
7225: The two commands, @kbd{C-c C-f} (@code{outline-forward-same-level}) and
7226: @kbd{C-c C-b} (@code{outline-backward-same-level}), move from one
7227: heading line to another visible heading at the same depth in
7228: the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves
7229: backward to another heading that is less deeply nested.
7230:
7231: @node Outline Visibility,,Outline Motion,Outline Mode
7232: @subsubsection Outline Visibility Commands
7233:
7234: The other special commands of outline mode are used to make lines visible
7235: or invisible. Their names all start with @code{hide} or @code{show}.
7236: Most of them fall into pairs of opposites. They are not undoable; instead,
7237: you can undo right past them. Making lines visible or invisible is simply
7238: not recorded by the undo mechanism.
7239:
7240: @table @kbd
7241: @item M-x hide-body
7242: Make all body lines in the buffer invisible.
7243: @item M-x show-all
7244: Make all lines in the buffer visible.
7245: @item C-c C-h
7246: Make everything under this heading invisible, not including this
7247: heading itself (@code{hide-subtree}).
7248: @item C-c C-s
7249: Make everything under this heading visible, including body,
7250: subheadings, and their bodies (@code{show-subtree}).
7251: @item M-x hide-leaves
7252: Make the body of this heading line, and of all its subheadings,
7253: invisible.
7254: @item M-x show-branches
7255: Make all subheadings of this heading line, at all levels, visible.
7256: @item C-c C-i
7257: Make immediate subheadings (one level down) of this heading line
7258: visible (@code{show-children}).
7259: @item M-x hide-entry
7260: Make this heading line's body invisible.
7261: @item M-x show-entry
7262: Make this heading line's body visible.
7263: @end table
7264:
7265: @findex hide-entry
7266: @findex show-entry
7267: Two commands that are exact opposites are @kbd{M-x hide-entry} and
7268: @kbd{M-x show-entry}. They are used with point on a heading line, and
7269: apply only to the body lines of that heading. The subtopics and their
7270: bodies are not affected.
7271:
7272: @findex hide-subtree
7273: @findex show-subtree
7274: @kindex C-c C-s (Outline mode)
7275: @kindex C-c C-h (Outline mode)
7276: @cindex subtree (Outline mode)
7277: Two more powerful opposites are @kbd{C-c C-h} (@code{hide-subtree}) and
7278: @kbd{C-c C-s} (@code{show-subtree}). Both expect to be used when point is
7279: on a heading line, and both apply to all the lines of that heading's
7280: @dfn{subtree}: its body, all its subheadings, both direct and indirect, and
7281: all of their bodies. In other words, the subtree contains everything
7282: following this heading line, up to and not including the next heading of
7283: the same or higher rank.@refill
7284:
7285: @findex hide-leaves
7286: @findex show-branches
7287: Intermediate between a visible subtree and an invisible one is having
7288: all the subheadings visible but none of the body. There are two commands
7289: for doing this, depending on whether you want to hide the bodies or
7290: make the subheadings visible. They are @kbd{M-x hide-leaves} and
7291: @kbd{M-x show-branches}.
7292:
7293: @kindex C-c C-i (Outline mode)
7294: @findex show-children
7295: A little weaker than @code{show-branches} is @kbd{C-c C-i}
7296: (@code{show-children}). It makes just the direct subheadings
7297: visible---those one level down. Deeper subheadings remain invisible, if
7298: they were invisible.@refill
7299:
7300: @findex hide-body
7301: @findex show-all
7302: Two commands have a blanket effect on the whole file. @kbd{M-x hide-body}
7303: makes all body lines invisible, so that you see just the outline structure.
7304: @kbd{M-x show-all} makes all lines visible. These commands can be thought
7305: of as a pair of opposites even though @kbd{M-x show-all} applies to more
7306: than just body lines.
7307:
7308: @vindex selective-display-ellipses
7309: The use of ellipses at the ends of visible lines can be turned off
7310: by setting @code{selective-display-ellipses} to @code{nil}. Then there
7311: is no visible indication of the presence of invisible lines.
7312:
7313: @node Words, Sentences, Text Mode, Text
7314: @section Words
7315: @cindex words
7316: @cindex Meta
7317:
7318: Emacs has commands for moving over or operating on words. By convention,
7319: the keys for them are all @kbd{Meta-} characters.
7320:
7321: @c widecommands
7322: @table @kbd
7323: @item M-f
7324: Move forward over a word (@code{forward-word}).
7325: @item M-b
7326: Move backward over a word (@code{backward-word}).
7327: @item M-d
7328: Kill up to the end of a word (@code{kill-word}).
7329: @item M-@key{DEL}
7330: Kill back to the beginning of a word (@code{backward-kill-word}).
7331: @item M-@@
7332: Mark the end of the next word (@code{mark-word}).
7333: @item M-t
7334: Transpose two words; drag a word forward
7335: or backward across other words (@code{transpose-words}).
7336: @end table
7337:
7338: Notice how these keys form a series that parallels the
7339: character-based @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @kbd{C-t} and
7340: @key{DEL}. @kbd{M-@@} is related to @kbd{C-@@}, which is an alias for
7341: @kbd{C-@key{SPC}}.@refill
7342:
7343: @kindex M-f
7344: @kindex M-b
7345: @findex forward-word
7346: @findex backward-word
7347: The commands @kbd{Meta-f} (@code{forward-word}) and @kbd{Meta-b}
7348: (@code{backward-word}) move forward and backward over words. They are thus
7349: analogous to @kbd{Control-f} and @kbd{Control-b}, which move over single
7350: characters. Like their @kbd{Control-} analogues, @kbd{Meta-f} and
7351: @kbd{Meta-b} move several words if given an argument. @kbd{Meta-f} with a
7352: negative argument moves backward, and @kbd{Meta-b} with a negative argument
7353: moves forward. Forward motion stops right after the last letter of the
7354: word, while backward motion stops right before the first letter.@refill
7355:
7356: @kindex M-d
7357: @findex kill-word
7358: @kbd{Meta-d} (@code{kill-word}) kills the word after point. To be
7359: precise, it kills everything from point to the place @kbd{Meta-f} would
7360: move to. Thus, if point is in the middle of a word, @kbd{Meta-d} kills
7361: just the part after point. If some punctuation comes between point and the
7362: next word, it is killed along with the word. (If you wish to kill only the
7363: next word but not the punctuation before it, simply do @kbd{Meta-f} to get
7364: the end, and kill the word backwards with @kbd{Meta-@key{DEL}}.)
7365: @kbd{Meta-d} takes arguments just like @kbd{Meta-f}.
7366:
7367: @findex backward-kill-word
7368: @kindex M-DEL
7369: @kbd{Meta-@key{DEL}} (@code{backward-kill-word}) kills the word before
7370: point. It kills everything from point back to where @kbd{Meta-b} would
7371: move to. If point is after the space in @w{@samp{FOO, BAR}}, then
7372: @w{@samp{FOO, }} is killed. (If you wish to kill just @samp{FOO}, do
7373: @kbd{Meta-b Meta-d} instead of @kbd{Meta-@key{DEL}}.)
7374:
7375: @cindex transposition
7376: @kindex M-t
7377: @findex transpose-words
7378: @kbd{Meta-t} (@code{transpose-words}) exchanges the word before or
7379: containing point with the following word. The delimiter characters between
7380: the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
7381: @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
7382: more on transposition and on arguments to transposition commands.
7383:
7384: @kindex M-@@
7385: @findex mark-word
7386: To operate on the next @var{n} words with an operation which applies
7387: between point and mark, you can either set the mark at point and then move
7388: over the words, or you can use the command @kbd{Meta-@@} (@code{mark-word})
7389: which does not move point, but sets the mark where @kbd{Meta-f} would move
7390: to. It can be given arguments just like @kbd{Meta-f}.
7391:
7392: @cindex syntax table
7393: The word commands' understanding of syntax is completely controlled by
7394: the syntax table. Any character can, for example, be declared to be a word
7395: delimiter. @xref{Syntax}.
7396:
7397: @node Sentences, Paragraphs, Words, Text
7398: @section Sentences
7399: @cindex sentences
7400:
7401: The Emacs commands for manipulating sentences and paragraphs are mostly
7402: on @kbd{Meta-} keys, so as to be like the word-handling commands.
7403:
7404: @table @kbd
7405: @item M-a
7406: @c !!! added @* to prevent overfull hbox
7407: Move back to the beginning of the sentence@*
7408: (@code{backward-sentence}).
7409: @item M-e
7410: Move forward to the end of the sentence (@code{forward-sentence}).
7411: @item M-k
7412: Kill forward to the end of the sentence (@code{kill-sentence}).
7413: @item C-x @key{DEL}
7414: Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
7415: @end table
7416:
7417: @kindex M-a
7418: @kindex M-e
7419: @findex backward-sentence
7420: @findex forward-sentence
7421: The commands @kbd{Meta-a} and @kbd{Meta-e} (@code{backward-sentence} and
7422: @code{forward-sentence}) move to the beginning and end of the current
7423: sentence, respectively. They were chosen to resemble @kbd{Control-a} and
7424: @kbd{Control-e}, which move to the beginning and end of a line. Unlike
7425: them, @kbd{Meta-a} and @w{@kbd{Meta-e}} if repeated or given numeric arguments
7426: move over successive sentences. Emacs assumes that the typist's convention
7427: is followed, and thus considers a sentence to end wherever there is a
7428: @samp{.}, @samp{?} or @samp{!} followed by the end of a line or two spaces,
7429: with any number of @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters
7430: allowed in between. A sentence also begins or ends wherever a paragraph
7431: begins or ends.
7432:
7433: Neither @kbd{M-a} nor @kbd{M-e} moves past the newline or spaces beyond
7434: the sentence edge at which it is stopping.
7435:
7436: @kindex M-k
7437: @kindex C-x DEL
7438: @findex kill-sentence
7439: @findex backward-kill-sentence
7440: Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
7441: with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
7442: @kbd{M-k} (@code{kill-sentence}) which kills from point to the end of the
7443: sentence. With minus one as an argument it kills back to the beginning of
7444: the sentence. Larger arguments serve as a repeat count.@refill
7445:
7446: There is a special command, @kbd{C-x @key{DEL}}
7447: (@code{backward-kill-sentence}) for killing back to the beginning of a
7448: sentence, because this is useful when you change your mind in the middle of
7449: composing text.@refill
7450:
7451: @vindex sentence-end
7452: The variable @code{sentence-end} controls recognition of the end of a
7453: sentence. It is a regexp that matches the last few characters of a
7454: sentence, together with the whitespace following the sentence. Its
7455: normal value is
7456:
7457: @example
7458: "[.?!][]\"')]*\$$\\|\t\\| \$[ \t\n]*"
7459: @end example
7460:
7461: @noindent
7462: This example is explained in the section on regexps. @xref{Regexps}.
7463:
7464: @node Paragraphs, Pages, Sentences, Text
7465: @section Paragraphs
7466: @cindex paragraphs
7467: @kindex M-[
7468: @kindex M-]
7469: @findex backward-paragraph
7470: @findex forward-paragraph
7471:
7472: The Emacs commands for manipulating paragraphs are also @kbd{Meta-}
7473: keys.
7474:
7475: @table @kbd
7476: @item M-[
7477: @c !!! added @* to prevent overfull hbox
7478: Move back to previous paragraph beginning@*
7479: (@code{backward-paragraph}).
7480: @item M-]
7481: Move forward to next paragraph end (@code{forward-paragraph}).
7482: @item M-h
7483: Put point and mark around this or next paragraph (@code{mark-paragraph}).
7484: @end table
7485:
7486: @kbd{Meta-[} moves to the beginning of the current or previous paragraph,
7487: while @kbd{Meta-]} moves to the end of the current or next paragraph.
7488: Blank lines and text formatter command lines separate paragraphs and are
7489: not part of any paragraph. Also, an indented line starts a new
7490: paragraph.
7491:
7492: In major modes for programs (as opposed to Text mode), paragraphs begin
7493: and end only at blank lines. This makes the paragraph commands continue to
7494: be useful even though there are no paragraphs per se.
7495:
7496: When there is a fill prefix, then paragraphs are delimited by all lines
7497: which don't start with the fill prefix. @xref{Filling}.
7498:
7499: @kindex M-h
7500: @findex mark-paragraph
7501: When you wish to operate on a paragraph, you can use the command
7502: @kbd{Meta-h} (@code{mark-paragraph}) to set the region around it. This
7503: command puts point at the beginning and mark at the end of the paragraph
7504: point was in. If point is between paragraphs (in a run of blank lines, or
7505: at a boundary), the paragraph following point is surrounded by point and
7506: mark. If there are blank lines preceding the first line of the paragraph,
7507: one of these blank lines is included in the region. Thus, for example,
7508: @kbd{M-h C-w} kills the paragraph around or after point.
7509:
7510: @vindex paragraph-start
7511: @vindex paragraph-separate
7512: @c !!! Written verbosely to avoid overfull hbox
7513: The precise definition of a paragraph boundary is controlled by the
7514: two variables @code{paragraph-separate} and @code{paragraph-start}. The value
7515: of @code{paragraph-start} is a regexp that should match any line that
7516: either starts or separates paragraphs. The value of
7517: @code{paragraph-separate} is another regexp that should match only lines
7518: that separate paragraphs without being part of any paragraph. Lines that
7519: start a new paragraph and are contained in it must match both regexps. For
7520: example, normally @code{paragraph-start} is @w{@code{"^[ @t{\}t@t{\}n@t{\}f]"}}
7521: and @code{paragraph-separate} is @w{@code{"^[ @t{\}t@t{\}f]*$"}}.
7522:
7523: Normally it is desirable for page boundaries to separate paragraphs.
7524: The default values of these variables recognize the usual separator for
7525: pages.
7526:
7527: @node Pages, Filling, Paragraphs, Text
7528: @section Pages
7529:
7530: @cindex pages
7531: @cindex formfeed
7532: Files are often thought of as divided into @dfn{pages} by the
7533: @dfn{formfeed} character (@sc{ascii} Control-L, octal code 014). For example,
7534: if a file is printed on a line printer, each page of the file, in this
7535: sense, will start on a new page of paper. Emacs treats a page-separator
7536: character just like any other character. It can be inserted with @kbd{C-q
7537: C-l}, or deleted with @key{DEL}. Thus, you are free to paginate your file
7538: or not. However, since pages are often meaningful divisions of the file,
7539: commands are provided to move over them and operate on them.
7540:
7541: @c WideCommands
7542: @table @kbd
7543: @item C-x [
7544: Move point to previous page boundary (@code{backward-page}).
7545: @item C-x ]
7546: Move point to next page boundary (@code{forward-page}).
7547: @item C-x C-p
7548: Put point and mark around this page (or another page) (@code{mark-page}).
7549: @item C-x l
7550: Count the lines in this page (@code{count-lines-page}).
7551: @end table
7552:
7553: @kindex C-x [
7554: @kindex C-x ]
7555: @findex forward-page
7556: @findex backward-page
7557: The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
7558: after the previous page delimiter. If point is already right after a page
7559: delimiter, it skips that one and stops at the previous one. A numeric
7560: argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
7561: command moves forward past the next page delimiter.
7562:
7563: @kindex C-x C-p
7564: @findex mark-page
7565: The @kbd{C-x C-p} command (@code{mark-page}) puts point at the beginning
7566: of the current page and the mark at the end. The page delimiter at the end
7567: is included (the mark follows it). The page delimiter at the front is
7568: excluded (point follows it). This command can be followed by @kbd{C-w} to
7569: kill a page which is to be moved elsewhere. If it is inserted after a page
7570: delimiter, at a place where @kbd{C-x ]} or @kbd{C-x [} would take you, then
7571: the page will be properly delimited before and after once again.
7572:
7573: A numeric argument to @kbd{C-x C-p} is used to specify which page to go
7574: to, relative to the current one. Zero means the current page. One means
7575: the next page, and @minus{}1 means the previous one.
7576:
7577: @kindex C-x l
7578: @findex count-lines-page
7579: The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
7580: where to break a page in two. It prints in the echo area the total number
7581: of lines in the current page, and then divides it up into those preceding
7582: the current line and those following, as in
7583:
7584: @example
7585: Page has 96 (72+25) lines
7586: @end example
7587:
7588: @noindent
7589: Notice that the sum is off by one; this is correct if point is not at the
7590: beginning of a line.
7591:
7592: @vindex page-delimiter
7593: The variable @code{page-delimiter} should have as its value a regexp that
7594: matches the beginning of a line that separates pages. This is what defines
7595: where pages begin. The normal value of this variable is @code{"^@t{\}f"},
7596: which matches a formfeed character at the beginning of a line.
7597:
7598: @node Filling, Case, Pages, Text
7599: @section Filling Text
7600: @cindex filling
7601: @cindex wrapping
7602:
7603: With Auto Fill mode, text can be @dfn{filled} (broken up into lines
7604: that fit in a specified width) as you insert it. If you alter existing
7605: text it may no longer be properly filled; then explicit commands for
7606: filling can be used. (Filling is sometimes called ``wrapping'' in the
7607: terminology used for other text editors, but we don't use that term,
7608: because it could just as well refer to the continuation of long lines
7609: which happens in Emacs if you @emph{don't} fill them.)
7610:
7611: @menu
7612: * Auto Fill:: Auto Fill mode breaks long lines automatically.
7613: * Fill Commands:: Commands to refill paragraphs and center lines.
7614: * Fill Prefix:: Filling when every line is indented or in a comment, etc.
7615: @end menu
7616:
7617: @node Auto Fill, Fill Commands, Filling, Filling
7618: @subsection Auto Fill Mode
7619: @cindex Auto Fill mode
7620:
7621: @dfn{Auto Fill} mode is a minor mode in which lines are broken
7622: automatically when they become too wide. Breaking happens only when
7623: you type a @key{SPC} or @key{RET}.
7624:
7625: @table @kbd
7626: @item M-x auto-fill-mode
7627: Enable or disable Auto Fill mode.
7628: @item @key{SPC}
7629: @itemx @key{RET}
7630: In Auto Fill mode, break lines when appropriate.
7631: @end table
7632:
7633: @findex auto-fill-mode
7634: @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off if
7635: it was on. With a positive numeric argument it always turns Auto Fill mode
7636: on, and with a negative argument always turns it off. You can see when
7637: Auto Fill mode is in effect by the presence of the word @samp{Fill} in the
7638: mode line, inside the parentheses. Auto Fill mode is a minor mode, turned
7639: on or off for each buffer individually. @xref{Minor Modes}.
7640:
7641: In Auto Fill mode, lines are broken automatically at spaces when they get
7642: longer than the desired width. Line breaking and rearrangement takes place
7643: only when you type @key{SPC} or @key{RET}. If you wish to insert a space
7644: or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} or
7645: @kbd{C-q @key{LFD}} (recall that a newline is really a linefeed). Also,
7646: @kbd{C-o} inserts a newline without line breaking.
7647:
7648: Auto Fill mode works well with Lisp mode, because when it makes a new
7649: line in Lisp mode it indents that line with @key{TAB}. If a line ending in
7650: a comment gets too long, the text of the comment is split into two
7651: comment lines. Optionally new comment delimiters are inserted at the end of
7652: the first line and the beginning of the second so that each line is
7653: a separate comment; the variable @code{comment-multi-line} controls the
7654: choice (@pxref{Comments}).
7655:
7656: Auto Fill mode does not refill entire paragraphs. It can break lines but
7657: cannot merge lines. So editing in the middle of a paragraph can result in
7658: a paragraph that is not correctly filled. The easiest way to make the
7659: paragraph properly filled again is usually with the explicit fill commands.
7660:
7661: Many users like Auto Fill mode and want to use it in all text files.
7662: The section on init files says how to arrange this permanently for yourself.
7663: @xref{Init File}.
7664:
7665: @node Fill Commands, Fill Prefix, Auto Fill, Filling
7666: @subsection Explicit Fill Commands
7667:
7668: @table @kbd
7669: @item M-q
7670: Fill current paragraph (@code{fill-paragraph}).
7671: @item M-g
7672: Fill each paragraph in the region (@code{fill-region}).
7673: @item C-x f
7674: Set the fill column (@code{set-fill-column}).
7675: @item M-x fill-region-as-paragraph.
7676: Fill the region, considering it as one paragraph.
7677: @item M-s
7678: Center a line.
7679: @end table
7680:
7681: @kindex M-q
7682: @findex fill-paragraph
7683: To refill a paragraph, use the command @kbd{Meta-q}
7684: (@code{fill-paragraph}). It causes the paragraph that point is inside, or
7685: the one after point if point is between paragraphs, to be refilled. All
7686: the line-breaks are removed, and then new ones are inserted where
7687: necessary. @kbd{M-q} can be undone with @kbd{C-_}. @xref{Undo}.@refill
7688:
7689: @kindex M-g
7690: @findex fill-region
7691: To refill many paragraphs, use @kbd{M-g} (@code{fill-region}), which
7692: divides the region into paragraphs and fills each of them.
7693:
7694: @findex fill-region-as-paragraph
7695: @kbd{Meta-q} and @kbd{Meta-g} use the same criteria as @kbd{Meta-h}
7696: for finding paragraph boundaries (@pxref{Paragraphs}). For more
7697: control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
7698: everything between point and mark. This command recognizes no paragraph
7699: separators; it deletes any blank lines found within the region to be
7700: filled.@refill
7701:
7702: @cindex justification
7703: A numeric argument to @kbd{M-g} or @kbd{M-q} causes it to @dfn{justify}
7704: the text as well as filling it. This means that extra spaces are inserted
7705: to make the right margin line up exactly at the fill column. To remove the
7706: extra spaces, use @kbd{M-q} or @kbd{M-g} with no argument.@refill
7707:
7708: @kindex M-s
7709: @cindex centering
7710: @findex center-line
7711: The command @kbd{Meta-s} (@code{center-line}) centers the current line
7712: within the current fill column. With an argument, it centers several lines
7713: individually and moves past them.
7714:
7715: @vindex fill-column
7716: The maximum line width for filling is in the variable @code{fill-column}.
7717: Altering the value of @code{fill-column} makes it local to the current
7718: buffer; until that time, the default value is in effect. The default is
7719: initially 70. @xref{Locals}.
7720:
7721: @kindex C-x f
7722: @findex set-fill-column
7723: The easiest way to set @code{fill-column} is to use the command @kbd{C-x
7724: f} (@code{set-fill-column}). With no argument, it sets @code{fill-column}
7725: to the current horizontal position of point. With a numeric argument, it
7726: uses that as the new fill column.
7727:
7728: @node Fill Prefix,, Fill Commands, Filling
7729: @subsection The Fill Prefix
7730:
7731: @cindex fill prefix
7732: To fill a paragraph in which each line starts with a special marker
7733: (which might be a few spaces, giving an indented paragraph), use the
7734: @dfn{fill prefix} feature. The fill prefix is a string which Emacs expects
7735: every line to start with, and which is not included in filling.
7736:
7737: @table @kbd
7738: @item C-x .
7739: Set the fill prefix (@code{set-fill-prefix}).
7740: @item M-q
7741: Fill a paragraph using current fill prefix (@code{fill-paragraph}).
7742: @item M-x fill-individual-paragraphs
7743: Fill the region, considering each change of indentation as starting a
7744: new paragraph.
7745: @end table
7746:
7747: @kindex C-x .
7748: @findex set-fill-prefix
7749: To specify a fill prefix, move to a line that starts with the desired
7750: prefix, put point at the end of the prefix, and give the command
7751: @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). That's a period after the
7752: @kbd{C-x}. To turn off the fill prefix, specify an empty prefix: type
7753: @w{@kbd{C-x .}}@: with point at the beginning of a line.
7754:
7755: When a fill prefix is in effect, the fill commands remove the fill prefix
7756: from each line before filling and insert it on each line after filling.
7757: The fill prefix is also inserted on new lines made automatically by Auto
7758: Fill mode. Lines that do not start with the fill prefix are considered to
7759: start paragraphs, both in @kbd{M-q} and the paragraph commands; this is
7760: just right if you are using paragraphs with hanging indentation (every line
7761: indented except the first one). Lines which are blank or indented once the
7762: prefix is removed also separate or start paragraphs; this is what you want
7763: if you are writing multi-paragraph comments with a comment delimiter on
7764: each line.
7765:
7766: @vindex fill-prefix
7767: The fill prefix is stored in the variable @code{fill-prefix}. Its value
7768: is a string, or @code{nil} when there is no fill prefix. This is a
7769: per-buffer variable; altering the variable affects only the current buffer,
7770: but there is a default value which you can change as well. @xref{Locals}.
7771:
7772: @findex fill-individual-paragraphs
7773: Another way to use fill prefixes is through @kbd{M-x
7774: fill-individual-paragraphs}. This function divides the region into groups
7775: of consecutive lines with the same amount and kind of indentation and fills
7776: each group as a paragraph using its indentation as a fill prefix.
7777:
7778: @node Case,, Filling, Text
7779: @section Case Conversion Commands
7780: @cindex case conversion
7781:
7782: Emacs has commands for converting either a single word or any arbitrary
7783: range of text to upper case or to lower case.
7784:
7785: @c WideCommands
7786: @table @kbd
7787: @item M-l
7788: Convert following word to lower case (@code{downcase-word}).
7789: @item M-u
7790: Convert following word to upper case (@code{upcase-word}).
7791: @item M-c
7792: Capitalize the following word (@code{capitalize-word}).
7793: @item C-x C-l
7794: Convert region to lower case (@code{downcase-region}).
7795: @item C-x C-u
7796: Convert region to upper case (@code{upcase-region}).
7797: @end table
7798:
7799: @kindex M-l
7800: @kindex M-u
7801: @kindex M-c
7802: @cindex words
7803: @findex downcase-word
7804: @findex upcase-word
7805: @findex capitalize-word
7806: The word conversion commands are the most useful. @kbd{Meta-l}
7807: (@code{downcase-word}) converts the word after point to lower case,
7808: moving past it. Thus, repeating @kbd{Meta-l} converts successive
7809: words. @kbd{Meta-u} (@code{upcase-word}) converts to all capitals
7810: instead, while @kbd{Meta-c} (@code{capitalize-word}) puts the letter
7811: following point into upper case and the rest of the letters in the
7812: word into lower case. All these commands convert several words at
7813: once if given an argument. They are especially convenient for
7814: converting a large amount of text from all upper case to mixed case,
7815: because you can move through the text using @kbd{M-l}, @kbd{M-u} or
7816: @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f}
7817: instead to skip a word.
7818:
7819: When given a negative argument, the word case conversion commands apply
7820: to the appropriate number of words before point, but do not move point.
7821: This is convenient when you have just typed a word in the wrong case: you
7822: can give the case conversion command and continue typing.
7823:
7824: If a word case conversion command is given in the middle of a word, it
7825: applies only to the part of the word which follows point. This is just
7826: like what @kbd{Meta-d} (@code{kill-word}) does. With a negative argument,
7827: case conversion applies only to the part of the word before point.
7828:
7829: @kindex C-x C-l
7830: @kindex C-x C-u
7831: @cindex region
7832: @findex downcase-region
7833: @findex upcase-region
7834: The other case conversion commands are @kbd{C-x C-u}
7835: (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
7836: convert everything between point and mark to the specified case. Point and
7837: mark do not move.@refill
7838:
7839: @node Programs, Compiling/Testing, Text, Top
7840: @chapter Editing Programs
7841:
7842: Emacs has many commands designed to understand the syntax of programming
7843: languages such as Lisp and C. These commands can
7844:
7845: @itemize @bullet
7846: @item
7847: Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
7848: @item
7849: Move over or mark top-level balanced expressions (@dfn{defuns}, in Lisp;
7850: functions, in C).
7851: @item
7852: Show how parentheses balance (@pxref{Matching}).
7853: @item
7854: Insert, kill or align comments (@pxref{Comments}).
7855: @item
7856: Follow the usual indentation conventions of the language
7857: (@pxref{Grinding}).
7858: @end itemize
7859:
7860: The commands for words, sentences and paragraphs are very useful in
7861: editing code even though their canonical application is for editing human
7862: language text. Most symbols contain words (@pxref{Words}); sentences can
7863: be found in strings and comments (@pxref{Sentences}). Paragraphs per se
7864: are not present in code, but the paragraph commands are useful anyway,
7865: because Lisp mode and C mode define paragraphs to begin and end at blank
7866: lines (@pxref{Paragraphs}). Judicious use of blank lines to make the
7867: program clearer will also provide interesting chunks of text for the
7868: paragraph commands to work on.
7869:
7870: The selective display feature is useful for looking at the overall
7871: structure of a function (@pxref{Selective Display}). This feature causes
7872: only the lines that are indented less than a specified amount to appear
7873: on the screen.
7874:
7875: @menu
7876: * Program Modes:: Major modes for editing programs.
7877: * Lists:: Expressions with balanced parentheses.
7878: There are editing commands to operate on them.
7879: * Defuns:: Each program is made up of separate functions.
7880: There are editing commands to operate on them.
7881: * Grinding:: Adjusting indentation to show the nesting.
7882: * Matching:: Insertion of a close-delimiter flashes matching open.
7883: * Comments:: Inserting, killing and aligning comments.
7884: * Macro Expansion:: How to see the results of C macro expansion.
7885: * Balanced Editing:: Inserting two matching parentheses at once, etc.
7886: * Lisp Completion:: Completion on symbol names in Lisp code.
7887: * Documentation:: Getting documentation of functions you plan to call.
7888: * Change Log:: Maintaining a change history for your program.
7889: * Tags:: Go direct to any function in your program in one
7890: command. Tags remembers which file it is in.
7891: * Fortran:: Fortran mode and its special features.
7892: @end menu
7893:
7894: @node Program Modes, Lists, Programs, Programs
7895: @section Major Modes for Programming Languages
7896:
7897: @cindex Lisp mode
7898: @cindex C mode
7899: @cindex Scheme mode
7900: Emacs has major modes for the programming languages Lisp, Scheme (a
7901: variant of Lisp), C, Fortran and Muddle. Ideally, a major mode should be
7902: implemented for each programming language that you might want to edit with
7903: Emacs; but often the mode for one language can serve for other
7904: syntactically similar languages. The language modes that exist are those
7905: that someone decided to take the trouble to write.
7906:
7907: There are several forms of Lisp mode, which differ in the way they
7908: interface to Lisp execution. @xref{Lisp Modes}.
7909:
7910: Each of the programming language modes defines the @key{TAB} key to run
7911: an indentation function that knows the indentation conventions of that
7912: language and updates the current line's indentation accordingly. For
7913: example, in C mode @key{TAB} is bound to @code{c-indent-line}. @key{LFD}
7914: is normally defined to do @key{RET} followed by @key{TAB}; thus, it too
7915: indents in a mode-specific fashion.
7916:
7917: @kindex DEL
7918: @findex backward-delete-char-untabify
7919: In most programming languages, indentation is likely to vary from line to
7920: line. So the major modes for those languages rebind @key{DEL} to treat a
7921: tab as if it were the equivalent number of spaces (using the command
7922: @code{backward-delete-char-untabify}). This makes it possible to rub out
7923: indentation one column at a time without worrying whether it is made up of
7924: spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point,
7925: in these modes.
7926:
7927: Programming language modes define paragraphs to be separated only by
7928: blank lines, so that the paragraph commands remain useful. Auto Fill mode,
7929: if enabled in a programming language major mode, indents the new lines
7930: which it creates.
7931:
7932: @cindex mode hook
7933: @vindex c-mode-hook
7934: @vindex lisp-mode-hook
7935: @vindex emacs-lisp-mode-hook
7936: @vindex lisp-interaction-mode-hook
7937: @vindex scheme-mode-hook
7938: @vindex muddle-mode-hook
7939: Turning on a major mode calls a user-supplied function called the
7940: @dfn{mode hook}, which is the value of a Lisp variable. For example,
7941: turning on C mode calls the value of the variable @code{c-mode-hook} if
7942: that value exists and is non-@code{nil}. Mode hook variables for other
7943: programming language modes include @code{lisp-mode-hook},
7944: @code{emacs-lisp-mode-hook}, @code{lisp-interaction-mode-hook},
7945: @code{scheme-mode-hook} and @code{muddle-mode-hook}. The mode hook
7946: function receives no arguments.@refill
7947:
7948: @node Lists, Defuns, Program Modes, Programs
7949: @section Lists and Sexps
7950:
7951: @cindex Control-Meta
7952: By convention, Emacs keys for dealing with balanced expressions are
7953: usually @kbd{Control-Meta-} characters. They tend to be analogous in
7954: function to their @kbd{Control-} and @kbd{Meta-} equivalents. These commands
7955: are usually thought of as pertaining to expressions in programming
7956: languages, but can be useful with any language in which some sort of
7957: parentheses exist (including English).
7958:
7959: @cindex list
7960: @cindex sexp
7961: @cindex expression
7962: These commands fall into two classes. Some deal only with @dfn{lists}
7963: (parenthetical groupings). They see nothing except parentheses, brackets,
7964: braces (whichever ones must balance in the language you are working with),
7965: and escape characters that might be used to quote those.
7966:
7967: The other commands deal with expressions or @dfn{sexps}. The word `sexp'
7968: is derived from @dfn{s-expression}, the ancient term for an expression in
7969: Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It
7970: refers to an expression in whatever language your program is written in.
7971: Each programming language has its own major mode, which customizes the
7972: syntax tables so that expressions in that language count as sexps.
7973:
7974: Sexps typically include symbols, numbers, and string constants, as well
7975: as anything contained in parentheses, brackets or braces.
7976:
7977: In languages that use prefix and infix operators, such as C, it is not
7978: possible for all expressions to be sexps. For example, C mode does not
7979: recognize @samp{foo + bar} as a sexp, even though it @i{is} a C expression;
7980: it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
7981: @samp{+} as punctuation between them. This is a fundamental ambiguity:
7982: both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
7983: move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a
7984: sexp in C mode.
7985:
7986: Some languages have obscure forms of syntax for expressions that nobody
7987: has bothered to make Emacs understand properly.
7988:
7989: @c doublewidecommands
7990: @table @kbd
7991: @item C-M-f
7992: Move forward over a sexp (@code{forward-sexp}).
7993: @item C-M-b
7994: Move backward over a sexp (@code{backward-sexp}).
7995: @item C-M-k
7996: Kill sexp forward (@code{kill-sexp}).
7997: @item C-M-u
7998: Move up and backward in list structure (@code{backward-up-list}).
7999: @item C-M-d
8000: Move down and forward in list structure (@code{down-list}).
8001: @item C-M-n
8002: Move forward over a list (@code{forward-list}).
8003: @item C-M-p
8004: Move backward over a list (@code{backward-list}).
8005: @item C-M-t
8006: Transpose expressions (@code{transpose-sexps}).
8007: @item C-M-@@
8008: Put mark after following expression (@code{mark-sexp}).
8009: @end table
8010:
8011: @kindex C-M-f
8012: @kindex C-M-b
8013: @findex forward-sexp
8014: @findex backward-sexp
8015: To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If
8016: the first significant character after point is an opening delimiter
8017: (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
8018: moves past the matching closing delimiter. If the character begins a
8019: symbol, string, or number, @kbd{C-M-f} moves over that. If the character
8020: after point is a closing delimiter, @kbd{C-M-f} gets an error.
8021:
8022: The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
8023: sexp. The detailed rules are like those above for @kbd{C-M-f}, but with
8024: directions reversed. If there are any prefix characters (singlequote,
8025: backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
8026: over them as well.
8027:
8028: @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
8029: specified number of times; with a negative argument, it moves in the
8030: opposite direction.
8031:
8032: The sexp commands move across comments as if they were whitespace, in
8033: languages such as C where the comment-terminator can be recognized. In
8034: Lisp, and other languages where comments run until the end of a line, it is
8035: very difficult to ignore comments when parsing backwards; therefore, in
8036: such languages the sexp commands treat the text of comments as if it were
8037: code.
8038:
8039: @kindex C-M-k
8040: @findex kill-sexp
8041: Killing a sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}).
8042: @kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over.
8043:
8044: @kindex C-M-n
8045: @kindex C-M-p
8046: @findex forward-list
8047: @findex backward-list
8048: The @dfn{list commands} move over lists like the sexp commands but skip
8049: blithely over any number of other kinds of sexps (symbols, strings, etc).
8050: They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
8051: (@code{backward-list}). The main reason they are useful is that they
8052: usually ignore comments (since the comments usually do not contain any
8053: lists).@refill
8054:
8055: @kindex C-M-u
8056: @kindex C-M-d
8057: @findex backward-up-list
8058: @findex down-list
8059: @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
8060: that's possible. To move @i{up} one (or @var{n}) levels, use @kbd{C-M-u}
8061: (@code{backward-up-list}).
8062: @kbd{C-M-u} moves backward up past one unmatched opening delimiter. A
8063: positive argument serves as a repeat count; a negative argument reverses
8064: direction of motion and also requests repetition, so it moves forward and
8065: up one or more levels.@refill
8066:
8067: To move @i{down} in list structure, use @kbd{C-M-d} (@code{down-list}). In Lisp mode,
8068: where @samp{(} is the only opening delimiter, this is nearly the same as
8069: searching for a @samp{(}. An argument specifies the number of levels
8070: of parentheses to go down.
8071:
8072: @cindex transposition
8073: @kindex C-M-t
8074: @findex transpose-sexps
8075: A somewhat random-sounding command which is nevertheless easy to use is
8076: @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp across
8077: the next one. An argument serves as a repeat count, and a negative
8078: argument drags backwards (thus canceling out the effect of @kbd{C-M-t} with
8079: a positive argument). An argument of zero, rather than doing nothing,
8080: transposes the sexps ending after point and the mark.
8081:
8082: @kindex C-M-@@
8083: @findex mark-sexp
8084: To make the region be the next sexp in the buffer, use @kbd{C-M-@@}
8085: (@code{mark-sexp}) which sets mark at the same place that @kbd{C-M-f} would
8086: move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In particular, a
8087: negative argument is useful for putting the mark at the beginning of the
8088: previous sexp.
8089:
8090: The list and sexp commands' understanding of syntax is completely
8091: controlled by the syntax table. Any character can, for example, be
8092: declared to be an opening delimiter and act like an open parenthesis.
8093: @xref{Syntax}.
8094:
8095: @node Defuns, Grinding, Lists, Programs
8096: @section Defuns
8097: @cindex defuns
8098:
8099: In Emacs, a parenthetical grouping at the top level in the buffer is
8100: called a @dfn{defun}. The name derives from the fact that most top-level
8101: lists in a Lisp file are instances of the special form @code{defun}, but
8102: any top-level parenthetical grouping counts as a defun in Emacs parlance
8103: regardless of what its contents are, and regardless of the programming
8104: language in use. For example, in C, the body of a function definition is a
8105: defun.
8106:
8107: @c doublewidecommands
8108: @table @kbd
8109: @item C-M-a
8110: Move to beginning of current or preceding defun
8111: (@code{beginning-of-defun}).
8112: @item C-M-e
8113: Move to end of current or following defun (@code{end-of-defun}).
8114: @item C-M-h
8115: Put region around whole current or following defun (@code{mark-defun}).
8116: @end table
8117:
8118: @kindex C-M-a
8119: @kindex C-M-e
8120: @kindex C-M-h
8121: @findex beginning-of-defun
8122: @findex end-of-defun
8123: @findex mark-defun
8124: The commands to move to the beginning and end of the current defun are
8125: @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
8126:
8127: If you wish to operate on the current defun, use @kbd{C-M-h}
8128: (@code{mark-defun}) which puts point at the beginning and mark at the end
8129: of the current or next defun. For example, this is the easiest way to get
8130: ready to move the defun to a different place in the text. In C mode,
8131: @kbd{C-M-h} runs the function @code{mark-c-function}, which is almost the
8132: same as @code{mark-defun}; the difference is that it backs up over the
8133: argument declarations, function name and returned data type so that the
8134: entire C function is inside the region.
8135:
8136: Emacs assumes that any open-parenthesis found in the leftmost column is
8137: the start of a defun. Therefore, @b{never put an open-parenthesis at the
8138: left margin in a Lisp file unless it is the start of a top level list.
8139: Never put an open-brace or other opening delimiter at the beginning of a
8140: line of C code unless it starts the body of a function.} The most likely
8141: problem case is when you want an opening delimiter at the start of a line
8142: inside a string. To avoid trouble, put an escape character (@samp{\}, in C
8143: and Emacs Lisp, @samp{/} in some other Lisp dialects) before the opening
8144: delimiter. It will not affect the contents of the string.
8145:
8146: In the remotest past, the original Emacs found defuns by moving upward a
8147: level of parentheses until there were no more levels to go up. This always
8148: required scanning all the way back to the beginning of the buffer, even for
8149: a small function. To speed up the operation, Emacs was changed to assume
8150: that any @samp{(} (or other character assigned the syntactic class of
8151: opening-delimiter) at the left margin is the start of a defun. This
8152: heuristic was nearly always right and avoided the costly scan; however,
8153: it mandated the convention described above.
8154:
8155: @node Grinding, Matching, Defuns, Programs
8156: @section Indentation for Programs
8157: @cindex indentation
8158: @cindex grinding
8159:
8160: The best way to keep a program properly indented (``ground'') is to use
8161: Emacs to re-indent it as you change it. Emacs has commands to indent
8162: properly either a single line, a specified number of lines, or all of the
8163: lines inside a single parenthetical grouping.
8164:
8165: @menu
8166: * Basic Indent::
8167: * Multi-line Indent:: Commands to reindent many lines at once.
8168: * Lisp Indent:: Specifying how each Lisp function should be indented.
8169: * C Indent:: Choosing an indentation style for C code.
8170: @end menu
8171:
8172: @node Basic Indent, Multi-line Indent, Grinding, Grinding
8173: @subsection Basic Program Indentation Commands
8174:
8175: @c WideCommands
8176: @table @kbd
8177: @item @key{TAB}
8178: Adjust indentation of current line.
8179: @item @key{LFD}
8180: Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
8181: @end table
8182:
8183: @kindex TAB
8184: @findex c-indent-line
8185: @findex lisp-indent-line
8186: The basic indentation command is @key{TAB}, which gives the current line
8187: the correct indentation as determined from the previous lines. The
8188: function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
8189: in Lisp mode, @code{c-indent-line} in C mode, etc. These functions
8190: understand different syntaxes for different languages, but they all do
8191: about the same thing. @key{TAB} in any programming language major mode
8192: inserts or deletes whitespace at the beginning of the current line,
8193: independent of where point is in the line. If point is inside the
8194: whitespace at the beginning of the line, @key{TAB} leaves it at the end of
8195: that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
8196: the characters around it.
8197:
8198: Use @kbd{C-q @key{TAB}} to insert a tab at point.
8199:
8200: @kindex LFD
8201: @findex newline-and-indent
8202: When entering a large amount of new code, use @key{LFD} (@code{newline-and-indent}),
8203: which is equivalent to a @key{RET} followed by a @key{TAB}. @key{LFD} creates
8204: a blank line, and then gives it the appropriate indentation.
8205:
8206: @key{TAB} indents the second and following lines of the body of a
8207: parenthetical grouping each under the preceding one; therefore, if you
8208: alter one line's indentation to be nonstandard, the lines below will tend
8209: to follow it. This is the right behavior in cases where the standard
8210: result of @key{TAB} is unaesthetic.
8211:
8212: Remember that an open-parenthesis, open-brace or other opening delimiter
8213: at the left margin is assumed by Emacs (including the indentation routines)
8214: to be the start of a function. Therefore, you must never have an opening
8215: delimiter in column zero that is not the beginning of a function, not even
8216: inside a string. This restriction is vital for making the indentation
8217: commands fast; you must simply accept it. @xref{Defuns}, for more
8218: information on this.
8219:
8220: @node Multi-line Indent, Lisp Indent, Basic Indent, Grinding
8221: @subsection Indenting Several Lines
8222:
8223: When you wish to re-indent several lines of code which have been altered
8224: or moved to a different level in the list structure, you have several
8225: commands available.
8226:
8227: @table @kbd
8228: @item C-M-q
8229: Re-indent all the lines within one list (@code{indent-sexp}).
8230: @item C-u @key{TAB}
8231: Shift an entire list rigidly sideways so that its first line
8232: is properly indented.
8233: @item C-M-\
8234: Re-indent all lines in the region (@code{indent-region}).
8235: @end table
8236:
8237: @kindex C-M-q
8238: @findex indent-sexp
8239: @findex indent-c-exp
8240: You can re-indent the contents of a single list by positioning point
8241: before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
8242: Lisp mode, @code{indent-c-exp} in C mode; also bound to other suitable
8243: functions in other modes). The indentation of the line the sexp starts on
8244: is not changed; therefore, only the relative indentation within the list,
8245: and not its position, is changed. To correct the position as well, type a
8246: @key{TAB} before the @kbd{C-M-q}.
8247:
8248: @kindex C-u TAB
8249: If the relative indentation within a list is correct but the indentation
8250: of its beginning is not, go to the line the list begins on and type
8251: @kbd{C-u @key{TAB}}. When @key{TAB} is given a numeric argument, it moves all the
8252: lines in the grouping starting on the current line sideways the same amount
8253: that the current line moves. It is clever, though, and does not move lines
8254: that start inside strings, or C preprocessor lines when in C mode.
8255:
8256: @kindex C-M-\
8257: @findex indent-region
8258: Another way to specify the range to be re-indented is with point and
8259: mark. The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to every line
8260: whose first character is between point and mark.
8261:
8262: @node Lisp Indent, C Indent, Multi-line Indent, Grinding
8263: @subsection Customizing Lisp Indentation
8264: @cindex customization
8265:
8266: The indentation pattern for a Lisp expression can depend on the function
8267: called by the expression. For each Lisp function, you can choose among
8268: several predefined patterns of indentation, or define an arbitrary one with
8269: a Lisp program.
8270:
8271: The standard pattern of indentation is as follows: the second line of the
8272: expression is indented under the first argument, if that is on the same
8273: line as the beginning of the expression; otherwise, the second line is
8274: indented underneath the function name. Each following line is indented
8275: under the previous line whose nesting depth is the same.
8276:
8277: @vindex lisp-indent-offset
8278: If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
8279: the usual indentation pattern for the second line of an expression, so that
8280: such lines are always indented @code{lisp-indent-offset} more columns than
8281: the containing list.
8282:
8283: @vindex lisp-body-indent
8284: The standard pattern is overridden for certain functions. Functions
8285: whose names start with @code{def} always indent the second line by
8286: @code{lisp-body-indention} extra columns beyond the open-parenthesis
8287: starting the expression.
8288:
8289: The standard pattern can be overridden in various ways for individual
8290: functions, according to the @code{lisp-indent-hook} property of the
8291: function name. There are four possibilities for this property:
8292:
8293: @table @asis
8294: @item @code{nil}
8295: This is the same as no property; the standard indentation pattern is used.
8296: @item @code{defun}
8297: The pattern used for function names that start with @code{def} is used for
8298: this function also.
8299: @item a number, @var{number}
8300: The first @var{number} arguments of the function are
8301: @dfn{distinguished} arguments; the rest are considered the @dfn{body}
8302: of the expression. A line in the expression is indented according to
8303: whether the first argument on it is distinguished or not. If the
8304: argument is part of the body, the line is indented @code{lisp-body-indent}
8305: more columns than the open-parenthesis starting the containing
8306: expression. If the argument is distinguished and is either the first
8307: or second argument, it is indented @i{twice} that many extra columns.
8308: If the argument is distinguished and not the first or second argument,
8309: the standard pattern is followed for that line.
8310: @item a symbol, @var{symbol}
8311: @var{symbol} should be a function name; that function is called to
8312: calculate the indentation of a line within this expression. The
8313: function receives two arguments:
8314: @table @asis
8315: @item @var{state}
8316: The value returned by @code{parse-partial-sexp} (a Lisp primitive for
8317: indentation and nesting computation) when it parses up to the
8318: beginning of this line.
8319: @item @var{pos}
8320: The position at which the line being indented begins.
8321: @end table
8322: @noindent
8323: It should return either a number, which is the number of columns of
8324: indentation for that line, or a list whose @sc{car} is such a number. The
8325: difference between returning a number and returning a list is that a
8326: number says that all following lines at the same nesting level should
8327: be indented just like this one; a list says that following lines might
8328: call for different indentations. This makes a difference when the
8329: indentation is being computed by @kbd{C-M-q}; if the value is a
8330: number, @kbd{C-M-q} need not recalculate indentation for the following
8331: lines until the end of the list.
8332: @end table
8333:
8334: @node C Indent,, Lisp Indent, Grinding
8335: @subsection Customizing C Indentation
8336:
8337: Two variables control which commands perform C indentation and when.
8338:
8339: @vindex c-auto-newline
8340: If @code{c-auto-newline} is non-@code{nil}, newlines are inserted both
8341: before and after braces that you insert, and after colons and semicolons.
8342: Correct C indentation is done on all the lines that are made this way.
8343:
8344: @vindex c-tab-always-indent
8345: If @code{c-tab-always-indent} is @code{nil}, the @key{TAB} command
8346: in C mode does indentation only if point is at the left margin or within
8347: the line's indentation. If there is non-whitespace to the left of point,
8348: then @key{TAB} just inserts a tab character in the buffer. Normally,
8349: this variable is @code{t}, and @key{TAB} always reindents the current line.
8350:
8351: C does not have anything analogous to particular function names for which
8352: special forms of indentation are desirable. However, it has a different
8353: need for customization facilities: many different styles of C indentation
8354: are in common use.
8355:
8356: There are six variables you can set to control the style that Emacs C
8357: mode will use.
8358:
8359: @table @code
8360: @item c-indent-level
8361: Indentation of C statements within surrounding block. The surrounding
8362: block's indentation is the indentation of the line on which the
8363: open-brace appears.
8364: @item c-continued-statement-offset
8365: Extra indentation given to a substatement, such as the then-clause of
8366: an if or body of a while.
8367: @item c-brace-offset
8368: Extra indentation for line if it starts with an open brace.
8369: @item c-brace-imaginary-offset
8370: An open brace following other text is treated as if it were this far
8371: to the right of the start of its line.
8372: @item c-argdecl-indent
8373: Indentation level of declarations of C function arguments.
8374: @item c-label-offset
8375: Extra indentation for line that is a label, or case or default.
8376: @end table
8377:
8378: @vindex c-indent-level
8379: The variable @code{c-indent-level} controls the indentation for C
8380: statements with respect to the surrounding block. In the example
8381:
8382: @example
8383: @{
8384: foo ();
8385: @end example
8386:
8387: @noindent
8388: the difference in indentation between the lines is @code{c-indent-level}.
8389: Its standard value is 2.
8390:
8391: If the open-brace beginning the compound statement is not at the beginning
8392: of its line, the @code{c-indent-level} is added to the indentation of the
8393: line, not the column of the open-brace. For example,
8394:
8395: @example
8396: if (losing) @{
8397: do_this ();
8398: @end example
8399:
8400: @noindent
8401: One popular indentation style is that which results from setting
8402: @code{c-indent-level} to 8 and putting open-braces at the end of a line in
8403: this way. I prefer to put the open-brace on a separate line.
8404:
8405: @vindex c-brace-imaginary-offset
8406: In fact, the value of the variable @code{c-brace-imaginary-offset} is
8407: also added to the indentation of such a statement. Normally this variable
8408: is zero. Think of this variable as the imaginary position of the open
8409: brace, relative to the first nonblank character on the line. By setting
8410: this variable to 4 and @code{c-indent-level} to 0, you can get this style:
8411:
8412: @example
8413: if (x == y) @{
8414: do_it ();
8415: @}
8416: @end example
8417:
8418: When @code{c-indent-level} is zero, the statements inside most braces
8419: will line up right under the open brace. But there is an exception made
8420: for braces in column zero, such as surrounding a function's body. The
8421: statements just inside it do not go at column zero. Instead,
8422: @code{c-brace-offset} and @w{@code{c-continued-statement-offset}} (see below)
8423: are added to produce a typical offset between brace levels, and the
8424: statements are indented that far.
8425:
8426: @vindex c-continued-statement-offset
8427: @code{c-continued-statement-offset} controls the extra indentation for a
8428: line that starts within a statement (but not within parentheses or
8429: brackets). These lines are usually statements that are within other
8430: statements, such as the then-clauses of @code{if} statements and the bodies
8431: of @code{while} statements. This parameter is the difference in
8432: indentation between the two lines in
8433:
8434: @example
8435: if (x == y)
8436: do_it ();
8437: @end example
8438:
8439: @noindent
8440: Its standard value is 2. Some popular indentation styles correspond to a
8441: value of zero for @code{c-continued-statement-offset}.
8442:
8443: @vindex c-brace-offset
8444: @code{c-brace-offset} is the extra indentation given to a line that
8445: starts with an open-brace. Its standard value is zero;
8446: compare
8447:
8448: @example
8449: if (x == y)
8450: @{
8451: @end example
8452:
8453: @noindent
8454: with
8455:
8456: @example
8457: if (x == y)
8458: do_it ();
8459: @end example
8460:
8461: @noindent
8462: if @code{c-brace-offset} were set to 4, the first example would become
8463:
8464: @example
8465: if (x == y)
8466: @{
8467: @end example
8468:
8469: @vindex c-argdecl-indent
8470: @code{c-argdecl-indent} controls the indentation of declarations of the
8471: arguments of a C function. It is absolute: argument declarations receive
8472: exactly @code{c-argdecl-indent} spaces. The standard value is 5, resulting
8473: in code like this:
8474:
8475: @example
8476: char *
8477: index (string, c)
8478: char *string;
8479: int c;
8480: @end example
8481:
8482: @vindex c-label-offset
8483: @code{c-label-offset} is the extra indentation given to a line that
8484: contains a label, a case statement, or a @code{default:} statement. Its
8485: standard value is @minus{}2, resulting in code like this
8486:
8487: @example
8488: switch (c)
8489: @{
8490: case 'x':
8491: @end example
8492:
8493: @noindent
8494: If @code{c-label-offset} were zero, the same code would be indented as
8495:
8496: @example
8497: switch (c)
8498: @{
8499: case 'x':
8500: @end example
8501:
8502: @noindent
8503: This example assumes that the other variables above also have their
8504: standard values.
8505:
8506: I strongly recommend that you try out the indentation style produced by
8507: the standard settings of these variables, together with putting open braces
8508: on separate lines. You can see how it looks in all the C source files of
8509: GNU Emacs.
8510:
8511: @node Matching, Comments, Grinding, Programs
8512: @section Automatic Display Of Matching Parentheses
8513: @cindex matching parentheses
8514: @cindex parentheses
8515:
8516: The Emacs parenthesis-matching feature is designed to show automatically
8517: how parentheses match in the text. Whenever a self-inserting character
8518: that is a closing delimiter is typed, the cursor moves momentarily to the
8519: location of the matching opening delimiter, provided that is on the screen.
8520: If it is not on the screen, some text starting with that opening delimiter
8521: is displayed in the echo area. Either way, you can tell what grouping is
8522: being closed off.
8523:
8524: In Lisp, automatic matching applies only to parentheses. In C, it
8525: applies to braces and brackets too. Emacs knows which characters to regard
8526: as matching delimiters based on the syntax table, which is set by the major
8527: mode. @xref{Syntax}.
8528:
8529: If the opening delimiter and closing delimiter are mismatched---such as
8530: in @samp{[x)}---a warning message is displayed in the echo area. The
8531: correct matches are specified in the syntax table.
8532:
8533: @vindex blink-matching-paren
8534: @vindex blink-matching-paren-distance
8535: Two variables control parenthesis match display. @code{blink-matching-paren}
8536: turns the feature on or off; @code{nil} turns it off, but the default is
8537: @code{t} to turn match display on. @code{blink-matching-paren-distance}
8538: specifies how many characters back to search to find the matching opening
8539: delimiter. If the match is not found in that far, scanning stops, and
8540: nothing is displayed. This is to prevent scanning for the matching
8541: delimiter from wasting lots of time when there is no match. The default
8542: is 4000.
8543:
8544: @node Comments, Macro Expansion, Matching, Programs
8545: @section Manipulating Comments
8546: @cindex comments
8547: @kindex M-;
8548: @cindex indentation
8549: @findex indent-for-comment
8550:
8551: The comment commands insert, kill and align comments.
8552:
8553: @c WideCommands
8554: @table @kbd
8555: @item M-;
8556: Insert or align comment (@code{indent-for-comment}).
8557: @item C-x ;
8558: Set comment column (@code{set-comment-column}).
8559: @item C-u - C-x ;
8560: Kill comment on current line (@code{kill-comment}).
8561: @item M-@key{LFD}
8562: Like @key{RET} followed by inserting and aligning a comment
8563: (@code{indent-new-comment-line}).
8564: @end table
8565:
8566: The command that creates a comment is @kbd{Meta-;} (@code{indent-for-comment}).
8567: If there is no comment already on the line, a new comment is created,
8568: aligned at a specific column called the @dfn{comment column}. The comment
8569: is created by inserting the string Emacs thinks comments should start with
8570: (the value of @code{comment-start}; see below). Point is left after that
8571: string. If the text of the line extends past the comment column, then the
8572: indentation is done to a suitable boundary (usually, at least one space is
8573: inserted). If the major mode has specified a string to terminate comments,
8574: that is inserted after point, to keep the syntax valid.
8575:
8576: @kbd{Meta-;} can also be used to align an existing comment. If a line
8577: already contains the string that starts comments, then @kbd{M-;} just moves
8578: point after it and re-indents it to the conventional place. Exception:
8579: comments starting in column 0 are not moved.
8580:
8581: Some major modes have special rules for indenting certain kinds of
8582: comments in certain contexts. For example, in Lisp code, comments which
8583: start with two semicolons are indented as if they were lines of code,
8584: instead of at the comment column. Comments which start with three
8585: semicolons are supposed to start at the left margin. Emacs understands
8586: these conventions by indenting a double-semicolon comment using @key{TAB},
8587: and by not changing the indentation of a triple-semicolon comment at all.
8588:
8589: @example
8590: ;; This function is just an example
8591: ;;; Here either two or three semicolons are appropriate.
8592: (defun foo (x)
8593: ;;; And now, the first part of the function:
8594: ;; The following line adds one.
8595: (1+ x)) ; This line adds one.
8596: @end example
8597:
8598: In C code, a comment preceded on its line by nothing but whitespace
8599: is indented like a line of code.
8600:
8601: Even when an existing comment is properly aligned, @kbd{M-;} is still
8602: useful for moving directly to the start of the comment.
8603:
8604: @kindex C-u - C-x ;
8605: @findex kill-comment
8606: @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line,
8607: if there is one. The indentation before the start of the comment is killed
8608: as well. If there does not appear to be a comment in the line, nothing is
8609: done. To reinsert the comment on another line, move to the end of that
8610: line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that
8611: @kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
8612: with a negative argument. That command is programmed so that when it
8613: receives a negative argument it calls @code{kill-comment}. However,
8614: @code{kill-comment} is a valid command which you could bind directly to a
8615: key if you wanted to.
8616:
8617: @subsection Multiple Lines of Comments
8618:
8619: @kindex M-LFD
8620: @cindex blank lines
8621: @findex indent-new-comment-line
8622: If you are typing a comment and find that you wish to continue it on
8623: another line, you can use the command @kbd{Meta-@key{LFD}} (@code{indent-new-comment-line}),
8624: which terminates the comment you are typing, creates a new blank line
8625: afterward, and begins a new comment indented under the old one. When Auto
8626: Fill mode is on, going past the fill column while typing a comment causes
8627: the comment to be continued in just this fashion. If point is not at the
8628: end of the line when @kbd{M-@key{LFD}} is typed, the text on the rest of
8629: the line becomes part of the new comment line.
8630:
8631: @subsection Options Controlling Comments
8632:
8633: @vindex comment-column
8634: @kindex C-x ;
8635: @findex set-comment-column
8636: The comment column is stored in the variable @code{comment-column}. You
8637: can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
8638: (@code{set-comment-column}) sets the comment column to the column point is
8639: at. @w{@kbd{C-u C-x ;}} sets the comment column to match the last comment
8640: before point in the buffer, and then does a @kbd{Meta-;} to align the
8641: current line's comment under the previous one. Note that @kbd{C-u - C-x ;}
8642: runs the function @code{kill-comment} as described above.
8643:
8644: @code{comment-column} is a per-buffer variable; altering the variable
8645: affects only the current buffer, but there is a default value which you can
8646: change as well. @xref{Locals}. Many major modes initialize this variable
8647: for the current buffer.
8648:
8649: @vindex comment-start-skip
8650: The comment commands recognize comments based on the regular expression
8651: that is the value of the variable @code{comment-start-skip}. This regexp
8652: should not match the null string. It may match more than the comment
8653: starting delimiter in the strictest sense of the word; for example, in C
8654: mode the value of the variable is @code{@t{"/\\*+ *"}}, which matches extra
8655: stars and spaces after the @samp{/*} itself. (Note that @samp{\\} is
8656: needed in Lisp syntax to include a @samp{\} in the string, which is needed
8657: to deny the first star its special meaning in regexp syntax. @xref{Regexps}.)
8658:
8659: @vindex comment-start
8660: @vindex comment-end
8661: When a comment command makes a new comment, it inserts the value of
8662: @code{comment-start} to begin it. The value of @code{comment-end} is
8663: inserted after point, so that it will follow the text that you will insert
8664: into the comment. In C mode, @code{comment-start} has the value
8665: @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
8666:
8667: @vindex comment-multi-line
8668: @code{comment-multi-line} controls how @kbd{M-@key{LFD}} (@code{indent-new-comment-line})
8669: behaves when used inside a comment. If @code{comment-multi-line} is
8670: @code{nil}, as it normally is, then the comment on the starting line is
8671: terminated and a new comment is started on the new following line. If
8672: @code{comment-multi-line} is not @code{nil}, then the new following line is
8673: set up as part of the same comment that was found on the starting line.
8674: This is done by not inserting a terminator on the old line, and not
8675: inserting a starter on the new line. In languages where multi-line comments
8676: work, the choice of value for this variable is a matter of taste.
8677:
8678: @vindex comment-indent-hook
8679: The variable @code{comment-indent-hook} should contain a function that
8680: will be called to compute the indentation for a newly inserted comment or
8681: for aligning an existing comment. It is set differently by various major
8682: modes. The function is called with no arguments, but with point at the
8683: beginning of the comment, or at the end of a line if a new comment is to be
8684: inserted. It should return the column in which the comment ought to start.
8685: For example, in Lisp mode, the indent hook function bases its decision
8686: on how many semicolons begin an existing comment, and on the code in the
8687: preceding lines.
8688:
8689: @node Macro Expansion, Balanced Editing, Comments, Programs
8690: @section Viewing How C Macros Expand
8691: @cindex macro expansion in C
8692: @cindex expansion of C macros
8693:
8694: @findex c-macro-expand
8695: When you are debugging C code that uses macros, sometimes it is hard to
8696: figure out precisely how the macros expand. The command @kbd{M-x
8697: c-macro-expand}. It runs the C preprocessor and shows you what
8698: expansion results from the region. The portion of the buffer before the
8699: region is also included in preprocessing, for the sake of macros defined
8700: there, but the output from this part isn't shown.
8701:
8702: @node Balanced Editing, Lisp Completion, Macro Expansion, Programs
8703: @section Editing Without Unbalanced Parentheses
8704:
8705: @table @kbd
8706: @item M-(
8707: Put parentheses around next sexp(s) (@code{insert-parentheses}).
8708: @item M-)
8709: Move past next close parenthesis and re-indent
8710: (@code{move-over-close-and-reindent}).
8711: @end table
8712:
8713: @kindex M-(
8714: @kindex M-)
8715: @findex insert-parentheses
8716: @findex move-over-close-and-reindent
8717: The two commands, @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
8718: (@code{move-over-close-and-reindent}), are designed to facilitate a style of
8719: editing which keeps parentheses balanced at all times. @kbd{M-(} inserts a
8720: pair of parentheses, either together as in @samp{()}, or, if given an
8721: argument, around the next several sexps, and leaves point after the open
8722: parenthesis. Instead of typing @w{@kbd{( F O O )}}, you can type @kbd{M-( F O
8723: O}, which has the same effect except for leaving the cursor before the
8724: close parenthesis. Then you would type @kbd{M-)}, which moves past the
8725: close parenthesis, deleting any indentation preceding it (in this example
8726: there is none), and indenting with @key{LFD} after it.
8727:
8728: @node Lisp Completion, Documentation, Balanced Editing, Programs
8729: @section Completion for Lisp Symbols
8730: @cindex completion (symbol names)
8731:
8732: Usually completion happens in the minibuffer. But one kind of completion
8733: is available in all buffers: completion for Lisp symbol names.
8734:
8735: @kindex M-TAB
8736: @findex lisp-complete-symbol
8737: The command @kbd{M-@key{TAB}} (@code{lisp-complete-symbol}) takes the
8738: partial Lisp symbol before point to be an abbreviation, and compares it
8739: against all nontrivial Lisp symbols currently known to Emacs. Any
8740: additional characters that they all have in common are inserted at point.
8741: Nontrivial symbols are those that have function definitions, values or
8742: properties.
8743:
8744: If there is an open-parenthesis immediately before the beginning of
8745: the partial symbol, only symbols with function definitions are considered
8746: as completions.
8747:
8748: If the partial name in the buffer has more than one possible completion
8749: and they have no additional characters in common, a list of all possible
8750: completions is displayed in another window.
8751:
8752: @node Documentation, Change Log, Lisp Completion, Programs
8753: @section Documentation Commands
8754:
8755: @kindex C-h f
8756: @findex describe-function
8757: @kindex C-h v
8758: @findex describe-variable
8759: As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
8760: (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
8761: be used to print documentation of functions and variables that you want to
8762: call. These commands use the minibuffer to read the name of a function or
8763: variable to document, and display the documentation in a window.
8764:
8765: For extra convenience, these commands provide default arguments based on
8766: the code in the neighborhood of point. @kbd{C-h f} sets the default to the
8767: function called in the innermost list containing point. @kbd{C-h v} uses
8768: the symbol name around or adjacent to point as its default.
8769:
8770: @findex manual-entry
8771: Documentation on Unix commands, system calls and libraries can be
8772: obtained with the @kbd{M-x manual-entry} command. This reads a topic as an
8773: argument, and displays the text on that topic from the Unix manual.
8774: @code{manual-entry} always searches all 8 sections of the manual, and
8775: concatenates all the entries that are found. For example, the topic
8776: @samp{termcap} finds the description of the termcap library from section 3,
8777: followed by the description of the termcap data base from section 5.
8778:
8779: @node Change Log, Tags, Documentation, Programs
8780: @section Change Logs
8781:
8782: @cindex change log
8783: @findex add-change-log-entry
8784: The Emacs command @kbd{M-x add-change-log-entry} helps you keep a record
8785: of when and why you have changed a program. It assumes that you have a
8786: file in which you write a chronological sequence of entries describing
8787: individual changes. The default is to store the change entries in a file
8788: called @file{ChangeLog} in the same directory as the file you are editing.
8789: The same @file{ChangeLog} file therefore records changes for all the files
8790: in the directory.
8791:
8792: A change log entry starts with a header line that contains your name and
8793: the current date. Aside from these header lines, every line in the
8794: change log starts with a tab. One entry can describe several changes;
8795: each change starts with a line starting with a tab and a star.
8796: @kbd{M-x add-change-log-entry} visits the change log file and creates
8797: a new entry unless the most recent entry is for today's date and your
8798: name. In either case, it adds a new line to start the description of
8799: another change just after the header line of the entry. When @kbd{M-x
8800: add-change-log-entry} is finished, all is prepared for you to edit in
8801: the description of what you changed and how. You must then save the
8802: change log file yourself.
8803:
8804: The change log file is always visited in Indented Text mode, which means
8805: that @key{LFD} and auto-filling indent each new line like the previous
8806: line. This is convenient for entering the contents of an entry, which must
8807: all be indented. @xref{Text Mode}.
8808:
8809: @findex add-change-log-entry-other-window
8810: @kindex C-x 4 a
8811: An alternative convenient command for starting a change log entry is
8812: @w{@kbd{C-x 4 a}} (@code{add-change-log-entry-other-window}). It resembles
8813: @code{add-change-log-entry} except that it visits the change log in
8814: another window, and always uses the file @file{./ChangeLog}---it does
8815: not ask you for the file name.
8816:
8817: Here is an example of the formatting conventions used in the change log
8818: for Emacs:
8819:
8820: @smallexample
8821: @group
8822: Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep)
8823:
8824: * xdisp.c (try_window_id):
8825: If C-k is done at end of next-to-last line,
8826: this fn updates window_end_vpos and cannot leave
8827: window_end_pos nonnegative (it is zero, in fact).
8828: If display is preempted before lines are output,
8829: this is inconsistent. Fix by setting
8830: blank_end_of_window to nonzero.
8831: @end group
8832:
8833: @group
8834: Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep)
8835:
8836: * cmds.c (Fnewline):
8837: Call the auto fill hook if appropriate.
8838: @end group
8839:
8840: @group
8841: * xdisp.c (try_window_id):
8842: If point is found by compute_motion after xp, record that
8843: permanently. If display_text_line sets point position wrong
8844: (case where line is killed, point is at eob and that line is
8845: not displayed), set it again in final compute_motion.
8846: @end group
8847: @end smallexample
8848:
8849: @node Tags, Fortran, Change Log, Programs
8850: @section Tag Tables
8851: @cindex tag table
8852:
8853: A @dfn{tag table} is a description of how a multi-file program is broken
8854: up into files. It lists the names of the component files and the names and
8855: positions of the functions in each file. Grouping the related files makes
8856: it possible to search or replace through all the files with one command.
8857: Recording the function names and positions makes possible the @kbd{Meta-.}
8858: command which you can use to find the definition of a function without
8859: having to know which of the files it is in.
8860:
8861: Tag tables are stored in files called @dfn{tag table files}. The
8862: conventional name for a tag table file is @file{TAGS}.
8863:
8864: Each entry in the tag table records the name of one tag, the name of the
8865: file that the tag is defined in (implicitly), and the position in that file
8866: of the tag's definition.
8867:
8868: Just what names from the described files are recorded in the tag table
8869: depends on the programming language of the described file. They normally
8870: include all functions and subroutines, and may also include global
8871: variables, data types, and anything else convenient. In any case, each
8872: name recorded is called a @dfn{tag}.
8873:
8874: @menu
8875: * Tag Syntax::
8876: * Create Tag Table::
8877: * Select Tag Table::
8878: * Find Tag::
8879: * Tags Search::
8880: * Tags Stepping::
8881: * List Tags::
8882: @end menu
8883:
8884: @node Tag Syntax, Create Tag Table, Tags, Tags
8885: @subsection Source File Tag Syntax
8886:
8887: In Lisp code, any function defined with @code{defun}, any variable
8888: defined with @code{defvar} or @code{defconst}, and in general the first
8889: argument of any expression that starts with @samp{(def} in column zero, is
8890: a tag.
8891:
8892: In C code, any C function is a tag, and so is any typedef if @code{-t} is
8893: specified when the tag table is constructed.
8894:
8895: In Fortran code, functions and subroutines are tags.
8896:
8897: In La@TeX{} text, the argument of any of the commands @code{\chapter},
8898: @code{\section}, @code{\subsection}, @code{\subsubsection}, @code{\eqno},
8899: @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem} and
8900: @code{\typeout} is a tag.@refill
8901:
8902: @node Create Tag Table, Select Tag Table, Tag Syntax, Tags
8903: @subsection Creating Tag Tables
8904: @cindex etags program
8905:
8906: The @code{etags} program is used to create a tag table file. It knows
8907: the syntax of C, Fortran, La@TeX{}, Scheme and Emacs Lisp/Common Lisp. To
8908: use @code{etags}, type
8909:
8910: @example
8911: etags @var{inputfiles}@dots{}
8912: @end example
8913:
8914: @noindent
8915: as a shell command. It reads the specified files and writes a tag table
8916: named @file{TAGS} in the current working directory. @code{etags}
8917: recognizes the language used in an input file based on its file name and
8918: contents; there are no switches for specifying the language. The @code{-t}
8919: switch tells @code{etags} to record typedefs in C code as tags.
8920:
8921: If the tag table data become outdated due to changes in the files
8922: described in the table, the way to update the tag table is the same way it
8923: was made in the first place. It is not necessary to do this often.
8924:
8925: If the tag table fails to record a tag, or records it for the wrong file,
8926: then Emacs cannot possibly find its definition. However, if the position
8927: recorded in the tag table becomes a little bit wrong (due to some editing
8928: in the file that the tag definition is in), the only consequence is to slow
8929: down finding the tag slightly. Even if the stored position is very wrong,
8930: Emacs will still find the tag, but it must search the entire file for it.
8931:
8932: So you should update a tag table when you define new tags that you want
8933: to have listed, or when you move tag definitions from one file to another,
8934: or when changes become substantial. Normally there is no need to update
8935: the tag table after each edit, or even every day.
8936:
8937: @node Select Tag Table, Find Tag, Create Tag Table, Tags
8938: @subsection Selecting a Tag Table
8939:
8940: @vindex tags-file-name
8941: @findex visit-tags-table
8942: Emacs has at any time one @dfn{selected} tag table, and all the commands
8943: for working with tag tables use the selected one. To select a tag table,
8944: type @w{@kbd{M-x visit-tags-table}}, which reads the tag table file name as an
8945: argument. The name @file{TAGS} in the default directory is used as the
8946: default file name.
8947:
8948: All this command does is store the file name in the variable
8949: @code{tags-file-name}. Emacs does not actually read in the tag table
8950: contents until you try to use them. Setting this variable yourself is just
8951: as good as using @code{visit-tags-table}. The variable's initial value is
8952: @code{nil}; this value tells all the commands for working with tag tables
8953: that they must ask for a tag table file name to use.
8954:
8955: @node Find Tag, Tags Search, Select Tag Table, Tags
8956: @subsection Finding a Tag
8957:
8958: The most important thing that a tag table enables you to do is to find
8959: the definition of a specific tag.
8960:
8961: @table @kbd
8962: @item M-.@: @var{tag}
8963: Find first definition of @var{tag} (@code{find-tag}).
8964: @item C-u M-.
8965: Find next alternate definition of last tag specified.
8966: @item C-x 4 .@: @var{tag}
8967: Find first definition of @var{tag}, but display it in another window
8968: (@code{find-tag-other-window}).
8969: @end table
8970:
8971: @kindex M-.
8972: @findex find-tag
8973: @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of a
8974: specified tag. It searches through the tag table for that tag, as a
8975: string, and then uses the tag table info to determine the file that the
8976: definition is in and the approximate character position in the file of the
8977: definition. Then @code{find-tag} visits that file, moves point to the
8978: approximate character position, and starts searching ever-increasing
8979: distances away for the the text that should appear at the beginning of the
8980: definition.
8981:
8982: If an empty argument is given (just type @key{RET}), the sexp in the
8983: buffer before or around point is used as the name of the tag to find.
8984: @xref{Lists}, for info on sexps.
8985:
8986: The argument to @code{find-tag} need not be the whole tag name; it can be
8987: a substring of a tag name. However, there can be many tag names containing
8988: the substring you specify. Since @code{find-tag} works by searching the
8989: text of the tag table, it finds the first tag in the table that the
8990: specified substring appears in.
8991:
8992: The way to find other tags that match the substring is to give
8993: @code{find-tag} a numeric argument, as in @kbd{C-u M-.}; this does not
8994: read a tag name, but continues searching the tag table's text for
8995: another tag containing the same substring last used. If you have a real
8996: @key{META} key, @kbd{M-0 M-.}@: is an easier alternative to @kbd{C-u
8997: M-.}. (That is a zero in @kbd{M-0}.)
8998:
8999: @kindex C-x 4 .
9000: @findex find-tag-other-window
9001: Like most commands that can switch buffers, @code{find-tag} has another
9002: similar command that displays the new buffer in another window. @kbd{C-x 4
9003: .}@: invokes the function @code{find-tag-other-window}. (This key sequence
9004: ends with a period.)
9005:
9006: Emacs comes with a tag table file @file{TAGS}, in the @file{src}
9007: subdirectory, which includes all the Lisp libraries and all the C
9008: sources of Emacs. By specifying this file with @code{visit-tags-table}
9009: and then using @kbd{M-.}@: you can quickly look at the source of any
9010: Emacs function.
9011:
9012: @node Tags Search, Tags Stepping, Find Tag, Tags
9013: @subsection Searching and Replacing with Tag Tables
9014:
9015: The commands in this section visit and search all the files listed in the
9016: selected tag table, one by one. For these commands, the tag table serves
9017: only to specify a sequence of files to search. A related command is
9018: @kbd{M-x grep} (@pxref{Compilation}).
9019:
9020: @table @kbd
9021: @item M-x tags-search
9022: Search for the specified regexp through the files in the selected tag
9023: table.
9024: @item M-x tags-query-replace
9025: Perform a @code{query-replace} on each file in the selected tag table.
9026: @item M-,
9027: Restart one of the commands above, from the current location of point
9028: (@code{tags-loop-continue}).
9029: @end table
9030:
9031: @findex tags-search
9032: @kbd{M-x tags-search} reads a regexp using the minibuffer, then visits
9033: the files of the selected tag table one by one, and searches through each
9034: one for that regexp. It displays the name of the file being searched so
9035: you can follow its progress. As soon as an occurrence is found,
9036: @code{tags-search} returns.
9037:
9038: @kindex M-,
9039: @findex tags-loop-continue
9040: Having found one match, you probably want to find all the rest. To find
9041: one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
9042: @code{tags-search}. This searches the rest of the current buffer, followed
9043: by the remaining files of the tag table.
9044:
9045: @findex tags-query-replace
9046: @kbd{M-x tags-query-replace} performs a single @code{query-replace}
9047: through all the files in the tag table. It reads a string to search for
9048: and a string to replace with, just like ordinary @w{@kbd{M-x query-replace}}.
9049: It searches much like @kbd{M-x tags-search} but repeatedly, processing
9050: matches according to your input. @xref{Replace}, for more information on
9051: @code{query-replace}.@refill
9052:
9053: It is possible to get through all the files in the tag table with a
9054: single invocation of @kbd{M-x tags-query-replace}. But since any
9055: unrecognized character causes the command to exit, you may need to continue
9056: where you left off. @kbd{M-,} can be used for this. It resumes the last
9057: tags search or replace command that you did.
9058:
9059: It may have struck you that @code{tags-search} is a lot like @code{grep}.
9060: You can also run @code{grep} itself as an inferior of Emacs and have Emacs
9061: show you the matching lines one by one. This works mostly the same as
9062: running a compilation and having Emacs show you where the errors were.
9063: @xref{Compilation}.
9064:
9065: @node Tags Stepping, List Tags, Tags Search, Tags
9066: @subsection Stepping Through a Tag Table
9067: @findex next-file
9068:
9069: If you wish to process all the files in the selected tag table, but
9070: @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} in particular are not what
9071: you want, you can use @kbd{M-x next-file}.
9072:
9073: @table @kbd
9074: @item C-u M-x next-file
9075: With a numeric argument, regardless of its value, visit the first
9076: file in the tag table, and prepare to advance sequentially by files.
9077: @item M-x next-file
9078: Visit the next file in the selected tag table.
9079: @end table
9080:
9081: @node List Tags,, Tags Stepping, Tags
9082: @subsection Tag Table Inquiries
9083:
9084: @table @kbd
9085: @item M-x list-tags
9086: Display a list of the tags defined in a specific program file.
9087: @item M-x tags-apropos
9088: Display a list of all tags matching a specified regexp.
9089: @end table
9090:
9091: @findex list-tags
9092: @kbd{M-x list-tags} reads the name of one of the files described by the
9093: selected tag table, and displays a list of all the tags defined in that
9094: file. The ``file name'' argument is really just a string to compare
9095: against the names recorded in the tag table; it is read as a string rather
9096: than as a file name. Therefore, completion and defaulting are not
9097: available, and you must enter the string the same way it appears in the tag
9098: table. Do not include a directory as part of the file name unless the file
9099: name recorded in the tag table includes a directory.
9100:
9101: @findex tags-apropos
9102: @kbd{M-x tags-apropos} is like @code{apropos} for tags. It reads a regexp,
9103: then finds all the tags in the selected tag table whose entries match that
9104: regexp, and displays the tag names found.
9105:
9106: @node Fortran,, Tags, Programs
9107: @section Fortran Mode
9108: @cindex Fortran mode
9109:
9110: Fortran mode provides special motion commands for Fortran statements and
9111: subprograms, and indentation commands that understand Fortran conventions
9112: of nesting, line numbers and continuation statements.
9113:
9114: Special commands for comments are provided because Fortran comments are
9115: unlike those of other languages.
9116:
9117: Built-in abbrevs optionally save typing when you insert Fortran keywords.
9118:
9119: @findex fortran-mode
9120: Use @kbd{M-x fortran-mode} to switch to this major mode. Doing so calls
9121: the value of @code{fortran-mode-hook} as a function of no arguments if
9122: that variable has a value that is not @code{nil}.
9123:
9124: @menu
9125: * Motion: Fortran Motion. Moving point by statements or subprograms.
9126: * Indent: Fortran Indent. Indentation commands for Fortran.
9127: * Comments: Fortran Comments. Inserting and aligning comments.
9128: * Columns: Fortran Columns. Measuring columns for valid Fortran.
9129: * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
9130: @end menu
9131:
9132: Fortran mode was contributed by Michael Prange.
9133:
9134: @node Fortran Motion, Fortran Indent, Fortran, Fortran
9135: @subsection Motion Commands
9136:
9137: Fortran mode provides special commands to move by subprograms (functions
9138: and subroutines) and by statements. There is also a command to put the
9139: region around one subprogram, convenient for killing it or moving it.
9140:
9141: @kindex C-M-a (Fortran mode)
9142: @kindex C-M-e (Fortran mode)
9143: @kindex C-M-h (Fortran mode)
9144: @kindex C-c C-p (Fortran mode)
9145: @kindex C-c C-n (Fortran mode)
9146: @findex beginning-of-fortran-subprogram
9147: @findex end-of-fortran-subprogram
9148: @findex mark-fortran-subprogram
9149: @findex fortran-previous-statement
9150: @findex fortran-next-statement
9151:
9152: @table @kbd
9153: @c !!! following generates acceptable underfull hbox
9154: @item C-M-a
9155: Move to beginning of subprogram
9156: (@code{beginning-of-fortran-subprogram}).
9157: @item C-M-e
9158: Move to end of subprogram (@code{end-of-fortran-subprogram}).
9159: @item C-M-h
9160: Put point at beginning of subprogram and mark at end
9161: (@code{mark-fortran-subprogram}).
9162: @item C-c C-n
9163: Move to beginning of current or next statement
9164: (@code{fortran-next-statement}).
9165: @item C-c C-p
9166: Move to beginning of current or previous statement
9167: (@code{fortran-previous-statement}).
9168: @end table
9169:
9170: @node Fortran Indent, Fortran Comments, Fortran Motion, Fortran
9171: @subsection Fortran Indentation
9172:
9173: Special commands and features are needed for indenting Fortran code in
9174: order to make sure various syntactic entities (line numbers, comment line
9175: indicators and continuation line flags) appear in the columns that are
9176: required for standard Fortran.
9177:
9178: @menu
9179: * Commands: ForIndent Commands. Commands for indenting Fortran.
9180: * Numbers: ForIndent Num. How line numbers auto-indent.
9181: * Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
9182: * Vars: ForIndent Vars. Variables controlling Fortran indent style.
9183: @end menu
9184:
9185: @node ForIndent Commands, ForIndent Num, Fortran Indent, Fortran Indent
9186: @subsubsection Fortran Indentation Commands
9187:
9188: @table @kbd
9189: @item @key{TAB}
9190: Indent the current line (@code{fortran-indent-line}).
9191: @item M-@key{LFD}
9192: Break the current line and set up a continuation line.
9193: @item C-M-q
9194: Indent all the lines of the subprogram point is in
9195: (@code{fortran-indent-subprogram}).
9196: @end table
9197:
9198: @findex fortran-indent-line
9199: @key{TAB} is redefined by Fortran mode to reindent the current line for
9200: Fortran (@code{fortran-indent-line}). Line numbers and continuation
9201: markers are indented to their required columns, and the body of the
9202: statement is independently indented based on its nesting in the program.
9203:
9204: @kindex C-M-q (Fortran mode)
9205: @findex fortran-indent-subprogram
9206: The key @kbd{C-M-q} is redefined as @code{fortran-indent-subprogram}, a
9207: command to reindent all the lines of the Fortran subprogram (function or
9208: subroutine) containing point.
9209:
9210: @kindex M-LFD (Fortran mode)
9211: @findex fortran-split-line
9212: The key @kbd{M-@key{LFD}} is redefined as @code{fortran-split-line}, a
9213: command to split a line in the appropriate fashion for Fortran. In a
9214: non-comment line, the second half becomes a continuation line and is
9215: indented accordingly. In a comment line, both halves become separate
9216: comment lines.
9217:
9218: @node ForIndent Num, ForIndent Conv, ForIndent Commands, Fortran Indent
9219: @subsubsection Line Numbers and Continuation
9220:
9221: If a number is the first non-whitespace in the line, it is assumed to be
9222: a line number and is moved to columns 0 through 4. (Columns are always
9223: counted from 0 in GNU Emacs.) If the text on the line starts with the
9224: conventional Fortran continuation marker @samp{$}, it is moved to column 5.
9225: If the text begins with any non whitespace character in column 5, it is
9226: assumed to be an unconventional continuation marker and remains in column
9227: 5.
9228:
9229: @vindex fortran-line-number-indent
9230: Line numbers of four digits or less are normally indented one space.
9231: This amount is controlled by the variable @code{fortran-line-number-indent}
9232: which is the maximum indentation a line number can have. Line numbers
9233: are indented to right-justify them to end in column 4 unless that would
9234: require more than this maximum indentation. The default value of the
9235: variable is 1.
9236:
9237: @vindex fortran-electric-line-number
9238: Simply inserting a line number is enough to indent it according to these
9239: rules. As each digit is inserted, the indentation is recomputed. To turn
9240: off this feature, set the variable @code{fortran-electric-line-number} to
9241: @code{nil}. Then inserting line numbers is like inserting anything else.
9242:
9243: @node ForIndent Conv, ForIndent Vars, ForIndent Num, Fortran Indent
9244: @subsubsection Syntactic Conventions
9245:
9246: Fortran mode assumes that you follow certain conventions that simplify
9247: the task of understanding a Fortran program well enough to indent it
9248: properly:
9249:
9250: @vindex fortran-continuation-char
9251: @itemize @bullet
9252: @item
9253: Two nested @samp{do} loops never share a @samp{continue} statement.
9254:
9255: @item
9256: The same character appears in column 5 of all continuation lines, and
9257: this character is the value of the variable @code{fortran-continuation-char}.
9258: By default, this character is @samp{$}.
9259: @end itemize
9260:
9261: @noindent
9262: If you fail to follow these conventions, the indentation commands may
9263: indent some lines unaesthetically. However, a correct Fortran program will
9264: retain its meaning when reindented even if the conventions are not
9265: followed.
9266:
9267: @node ForIndent Vars,, ForIndent Conv, Fortran Indent
9268: @subsubsection Variables for Fortran Indentation
9269:
9270: @vindex fortran-do-indent
9271: @vindex fortran-if-indent
9272: @vindex fortran-continuation-indent
9273: @vindex fortran-check-all-num-for-matching-do
9274: @vindex fortran-minimum-statement-indent
9275: Several additional variables control how Fortran indentation works.
9276:
9277: @table @code
9278: @item fortran-do-indent
9279: Extra indentation within each level of @samp{do} statement @*(default 3).
9280:
9281: @item fortran-if-indent
9282: Extra indentation within each level of @samp{if} statement @*(default 3).
9283:
9284: @item fortran-continuation-indent
9285: Extra indentation for bodies of continuation lines (default 5).
9286:
9287: @item fortran-check-all-num-for-matching-do
9288: If this is @code{nil}, indentation assumes that each @samp{do}
9289: statement ends on a @samp{continue} statement. Therefore, when
9290: computing indentation for a statement other than @samp{continue}, it
9291: can save time by not checking for a @samp{do} statement ending there.
9292: If this is non-@code{nil}, indenting any numbered statement must check
9293: for a @samp{do} that ends there. The default is @code{nil}.
9294:
9295: @item fortran-minimum-statement-indent
9296: Minimum indentation for fortran statements. For standard Fortran,
9297: this is 6. Statement bodies will never be indented less than this
9298: much.
9299: @end table
9300:
9301: @node Fortran Comments, Fortran Columns, Fortran Indent, Fortran
9302: @subsection Comments
9303:
9304: The usual Emacs comment commands assume that a comment can follow a line
9305: of code. In Fortran, the standard comment syntax requires an entire line
9306: to be just a comment. Therefore, Fortran mode replaces the standard Emacs
9307: comment commands and defines some new variables.
9308:
9309: Fortran mode can also handle a nonstandard comment syntax where comments
9310: start with @samp{!} and can follow other text. Because only some Fortran
9311: compilers accept this syntax, Fortran mode will not insert such comments
9312: unless you have said in advance to do so. To do this, set the variable
9313: @code{comment-start} to @samp{"!"} (@pxref{Variables}).
9314:
9315: @table @kbd
9316: @item M-;
9317: Align comment or insert new comment (@code{fortran-comment-indent}).
9318:
9319: @item C-x ;
9320: Applies to nonstandard @samp{!} comments only.
9321:
9322: @item C-c ;
9323: Turn all lines of the region into comments, or (with arg)
9324: turn them back into real code (@code{fortran-comment-region}).
9325: @end table
9326:
9327: @kbd{M-;} in Fortran mode is redefined as the command
9328: @code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this
9329: recognizes any kind of existing comment and aligns its text appropriately;
9330: if there is no existing comment, a comment is inserted and aligned. But
9331: inserting and aligning comments are not the same in Fortran mode as in
9332: other modes.
9333:
9334: When a new comment must be inserted, if the current line is blank, a
9335: full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
9336: comment is inserted if you have said you want to use them. Otherwise a
9337: full-line comment is inserted on a new line before the current line.
9338:
9339: Nonstandard @samp{!} comments are aligned like comments in other
9340: languages, but full-line comments are different. In a standard full-line
9341: comment, the comment delimiter itself must always appear in column zero.
9342: What can be aligned is the text within the comment. You can choose from
9343: three styles of alignment by setting the variable
9344: @code{fortran-comment-indent-style} to one of these values:
9345:
9346: @vindex fortran-comment-indent-style
9347: @vindex fortran-comment-line-column
9348: @table @code
9349: @item fixed
9350: The text is aligned at a fixed column, which is the value of
9351: @code{fortran-comment-line-column}. This is the default.
9352: @item relative
9353: The text is aligned as if it were a line of code, but with an
9354: additional @code{fortran-comment-line-column} columns of indentation.
9355: @item nil
9356: Text in full-line columns is not moved automatically.
9357: @end table
9358:
9359: @vindex fortran-comment-indent-char
9360: In addition, you can specify the character to be used to indent within
9361: full-line comments by setting the variable @code{fortran-comment-indent-char}
9362: to the character you want to use.
9363:
9364: @vindex comment-line-start
9365: @vindex comment-line-start-skip
9366: Fortran mode introduces the two variables, @code{comment-line-start} and
9367: @code{comment-line-start-skip}, which play for full-line comments the same
9368: roles played by @code{comment-start} and @code{comment-start-skip} for
9369: ordinary text-following comments. Normally these are set properly by
9370: Fortran mode so you do not need to change them.
9371:
9372: The normal Emacs comment command @kbd{C-x ;} has not been redefined.
9373: If you use @samp{!} comments, this command can be used with them. Otherwise
9374: it is useless in Fortran mode.
9375:
9376: @kindex C-c ; (Fortran mode)
9377: @findex fortran-comment-region
9378: @vindex fortran-comment-region
9379: The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
9380: lines of the region into comments by inserting the string @samp{C$$$} at
9381: the front of each one. With a numeric arg, the region is turned back into
9382: live code by deleting @samp{C$$$} from the front of each line in it. The
9383: string used for these comments can be controlled by setting the variable
9384: @code{fortran-comment-region}. Note that here we have an example of a
9385: command and a variable with the same name; these two uses of the name never
9386: conflict because in Lisp and in Emacs it is always clear from the context
9387: which one is meant.
9388:
9389: @node Fortran Columns, Fortran Abbrev, Fortran Comments, Fortran
9390: @subsection Columns
9391:
9392: @table @kbd
9393: @item C-c C-r
9394: Displays a ``column ruler'' momentarily above the current line
9395: (@code{fortran-column-ruler}).
9396: @item C-c C-w
9397: Splits the current window horizontally so that it is 72 columns wide.
9398: This may help you avoid going over that limit (@code{fortran-window-create}).
9399: @end table
9400:
9401: @kindex C-c C-r (Fortran mode)
9402: @findex fortran-column-ruler
9403: @vindex fortran-column-ruler
9404: The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
9405: ruler momentarily above the current line. The comment ruler is two lines
9406: of text that show you the locations of columns with special significance
9407: in Fortran programs. Square brackets show the limits of the columns for
9408: line numbers, and curly brackets show the limits of the columns for the
9409: statement body. Column numbers appear above them.
9410:
9411: Note that the column numbers count from zero, as always in GNU Emacs. As
9412: a result, the numbers may not be those you are familiar with; but the
9413: actual positions in the line are standard Fortran.
9414:
9415: The text used to display the column ruler is the value of the variable
9416: @code{fortran-comment-ruler}. By changing this variable, you can change
9417: the display.
9418:
9419: @kindex C-c C-w (Fortran mode)
9420: @findex fortran-window-create
9421: For even more help, use @kbd{C-c C-w} (@code{fortran-window-create}), a
9422: command which splits the current window horizontally, making a window 72
9423: columns wide. By editing in this window you can immediately see when you
9424: make a line too wide to be correct Fortran.
9425:
9426: @node Fortran Abbrev,, Fortran Columns, Fortran
9427: @subsection Fortran Keyword Abbrevs
9428:
9429: Fortran mode provides many built-in abbrevs for common keywords and
9430: declarations. These are the same sort of abbrev that you can define
9431: yourself. To use them, you must turn on Abbrev mode (@pxref{Abbrevs}).
9432:
9433: The built-in abbrevs are unusual in one way: they all start with a
9434: semicolon. You cannot normally use semicolons in an abbrev, but Fortran
9435: mode makes this possible by changing the syntax of semicolon to ``word
9436: constituent''.
9437:
9438: For example, one built-in Fortran abbrev is @samp{;c} for
9439: @samp{continue}. If you insert @samp{;c} and then insert a punctuation
9440: character such as a space or a newline, the @samp{;c} will change
9441: automatically to @samp{continue}, provided Abbrev mode is enabled.@refill
9442:
9443: Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
9444: Fortran abbrevs and what they stand for.
9445:
9446: @node Compiling/Testing, Abbrevs, Programs, Top
9447: @chapter Compiling and Testing Programs
9448:
9449: The previous chapter discusses the Emacs commands that are useful for
9450: making changes in programs. This chapter deals with commands that assist
9451: in the larger process of developing and maintaining programs.
9452:
9453: @menu
9454: * Compilation:: Compiling programs in languages other than Lisp
9455: (C, Pascal, etc.)
9456: * Modes: Lisp Modes. Various modes for editing Lisp programs, with
9457: different facilities for running the Lisp programs.
9458: * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
9459: * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
9460: * Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
9461: * Debug: Lisp Debug. Debugging Lisp programs running in Emacs.
9462: * External Lisp:: Communicating through Emacs with a separate Lisp.
9463: @end menu
9464:
9465: @node Compilation, Lisp Modes, Compiling/Testing, Compiling/Testing
9466: @section Running `make', or Compilers Generally
9467: @cindex inferior process
9468: @cindex make
9469: @cindex compilation errors
9470: @cindex error log
9471:
9472: Emacs can run compilers for noninteractive languages such as C and
9473: Fortran as inferior processes, feeding the error log into an Emacs buffer.
9474: It can also parse the error messages and visit the files in which errors
9475: are found, moving point right to the line where the error occurred.
9476:
9477: @table @kbd
9478: @item M-x compile
9479: Run a compiler asynchronously under Emacs, with error messages to
9480: @samp{*compilation*} buffer.
9481: @item M-x grep
9482: Run @code{grep} asynchronously under Emacs, with matching lines
9483: listed in the buffer named @samp{*compilation*}.
9484: @item M-x kill-compilation
9485: @itemx M-x kill-grep
9486: Kill the running compilation or @code{grep} subprocess.
9487: @item C-x `
9488: Visit the locus of the next compiler error message or @code{grep} match.
9489: @end table
9490:
9491: @findex compile
9492: To run @code{make} or another compiler, do @kbd{M-x compile}. This command
9493: reads a shell command line using the minibuffer, and then executes the
9494: specified command line in an inferior shell with output going to the buffer
9495: named @samp{*compilation*}. The current buffer's default directory is used
9496: as the working directory for the execution of the command; normally,
9497: therefore, the makefile comes from this directory.
9498:
9499: @vindex compile-command
9500: When the shell command line is read, the minibuffer appears containing a
9501: default command line, which is the command you used the last time you did
9502: @kbd{M-x compile}. If you type just @key{RET}, the same command line is used
9503: again. The first @kbd{M-x compile} provides @code{make -k} as the default.
9504: The default is taken from the variable @code{compile-command}; if the
9505: appropriate compilation command for a file is something other than
9506: @code{make -k}, it can be useful to have the file specify a local value for
9507: @code{compile-command} (@pxref{File Variables}).
9508:
9509: Starting a compilation causes the buffer @samp{*compilation*} to be
9510: displayed in another window but not selected. Its mode line tells you
9511: whether compilation is finished, with the word @samp{run} or @samp{exit} inside
9512: the parentheses. You do not have to keep this buffer visible; compilation
9513: continues in any case.
9514:
9515: @findex kill-compilation
9516: To kill the compilation process, do @kbd{M-x kill-compilation}. You will
9517: see that the mode line of the @samp{*compilation*} buffer changes to say
9518: @samp{signal} instead of @samp{run}. Starting a new compilation also kills
9519: any running compilation, as only one can exist at any time. However, this
9520: requires confirmation before actually killing a compilation that is
9521: running.@refill
9522:
9523: @kindex C-x `
9524: @findex next-error
9525: To parse the compiler error messages, type @kbd{C-x `} (@code{next-error}). The
9526: character following the @kbd{C-x} is the grave accent, not the single
9527: quote. This command displays the buffer @samp{*compilation*} in one window
9528: and the buffer in which the next error occurred in another window. Point
9529: in that buffer is moved to the line where the error was found. The
9530: corresponding error message is scrolled to the top of the window in which
9531: @samp{*compilation*} is displayed.
9532:
9533: The first time @kbd{C-x `} is used after the start of a compilation, it
9534: parses all the error messages, visits all the files that have error
9535: messages, and makes markers pointing at the lines that the error messages
9536: refer to. Then it moves to the first error message location. Subsequent
9537: uses of @kbd{C-x `} advance down the data set up by the first use. When
9538: the preparsed error messages are exhausted, the next @kbd{C-x `} checks for
9539: any more error messages that have come in; this is useful if you start
9540: editing the compiler errors while the compilation is still going on. If no
9541: more error messages have come in, @kbd{C-x `} reports an error.
9542:
9543: @kbd{C-u C-x `} discards the preparsed error message data and parses the
9544: @samp{*compilation*} buffer over again, then displaying the first error.
9545: This way, you can process the same set of errors again.
9546:
9547: @findex grep
9548: Instead of running a compiler, you can run @code{grep} and see the lines
9549: on which matches were found. To do this, type @kbd{M-x grep} with an argument
9550: line that contains the same arguments you would give @code{grep} when running
9551: it normally: a @code{grep}-style regexp (usually in singlequotes to quote
9552: the shell's special characters) followed by filenames which may use wildcards.
9553: The output from @code{grep} goes in the @samp{*compilation*} buffer and the
9554: lines that matched can be found with @kbd{C-x `} as if they were compilation
9555: errors.
9556:
9557: Note: a shell is used to run the compile command, but the shell is told
9558: that it should be noninteractive. This means in particular that the shell
9559: starts up with no prompt. If you find your usual shell prompt making an
9560: unsightly appearance in the @samp{*compilation*} buffer, it means you have
9561: made a mistake in your shell's init file (@file{.cshrc} or @file{.shrc} or
9562: @dots{}) by setting the prompt unconditionally. The shell init file should
9563: set the prompt only if there already is a prompt.
9564:
9565: Here is how to do it in @code{csh}:
9566:
9567: @example
9568: if ($?prompt) set prompt = ...
9569: @end example
9570:
9571: Here is how to do it in the Bourne-Again shell:
9572:
9573: @example
9574: @group
9575: if [ ! "$PS1" ]; then
9576: PS1=@dots{}
9577: fi
9578: @end group
9579: @end example
9580:
9581: @node Lisp Modes, Lisp Libraries, Compilation, Compiling/Testing
9582: @section Major Modes for Lisp
9583:
9584: @cindex Lisp mode
9585: @cindex Scheme mode
9586: @cindex Inferior Scheme mode
9587: Emacs has four different major modes for Lisp. They are the same in
9588: terms of editing commands, but differ in the commands for executing Lisp
9589: expressions.
9590:
9591: @table @asis
9592: @item Emacs-Lisp mode
9593: The mode for editing source files of programs to run in Emacs Lisp.
9594: This mode defines @kbd{C-M-x} to evaluate the current defun.
9595: @xref{Lisp Libraries}.
9596: @item Lisp Interaction mode
9597: The mode for an interactive session with Emacs Lisp. It defines
9598: @key{LFD} to evaluate the sexp before point and insert its value in the
9599: buffer. @xref{Lisp Interaction}.
9600: @item Lisp mode
9601: The mode for editing source files of programs that run in Lisps other
9602: than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
9603: to an inferior Lisp process. @xref{External Lisp}.
9604: @item Inferior Lisp mode
9605: The mode for an interactive session with an inferior Lisp process.
9606: This mode combines the special features of Lisp mode and Shell mode
9607: (@pxref{Shell Mode}).
9608: @item Scheme mode
9609: Like Lisp mode but for Scheme programs.
9610: @item Inferior Scheme mode
9611: The mode for an interactive session with an inferior Scheme process.
9612: @end table
9613:
9614: @node Lisp Libraries, Lisp Eval, Lisp Modes, Compiling/Testing
9615: @section Libraries of Lisp Code for Emacs
9616: @cindex libraries
9617: @cindex loading Lisp code
9618:
9619: Lisp code for Emacs editing commands is stored in files whose names
9620: conventionally end in @file{.el}. This ending tells Emacs to edit them in
9621: Emacs-Lisp mode (@pxref{Lisp Modes}).
9622:
9623: @menu
9624: * Loading:: Loading libraries of Lisp code into Emacs for use.
9625: * Compiling Libraries:: Compiling a library makes it load and run faster.
9626: * Mocklisp:: Converting Mocklisp to Lisp so GNU Emacs can run it.
9627: @end menu
9628:
9629: @node Loading, Compiling Libraries, Lisp Libraries, Lisp Libraries
9630: @subsection Loading Libraries
9631:
9632: @findex load-file
9633: To execute a file of Emacs Lisp, use @kbd{M-x load-file}. This command
9634: reads a file name using the minibuffer and then executes the contents of
9635: that file as Lisp code. It is not necessary to visit the file first;
9636: in any case, this command reads the file as found on disk, not text in
9637: an Emacs buffer.
9638:
9639: @findex load
9640: @findex load-library
9641: Once a file of Lisp code is installed in the Emacs Lisp library
9642: directories, users can load it using @kbd{M-x load-library}. Programs can
9643: load it by calling @code{load-library}, or with @code{load}, a more primitive
9644: function that is similar but accepts some additional arguments.
9645:
9646: @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
9647: searches a sequence of directories and tries three file names in each
9648: directory. The three names are, first, the specified name with @file{.elc}
9649: appended; second, with @file{.el} appended; third, the specified
9650: name alone. A @file{.elc} file would be the result of compiling the Lisp
9651: file into byte code; it is loaded if possible in preference to the Lisp
9652: file itself because the compiled file will load and run faster.
9653:
9654: Because the argument to @code{load-library} is usually not in itself
9655: a valid file name, file name completion is not available. Indeed, when
9656: using this command, you usually do not know exactly what file name
9657: will be used.
9658:
9659: @vindex load-path
9660: The sequence of directories searched by @kbd{M-x load-library} is
9661: specified by the variable @code{load-path}, a list of strings that are
9662: directory names. The default value of the list contains the directory where
9663: the Lisp code for Emacs itself is stored. If you have libraries of
9664: your own, put them in a single directory and add that directory
9665: to @code{load-path}. @code{nil} in this list stands for the current default
9666: directory, but it is probably not a good idea to put @code{nil} in the
9667: list. If you find yourself wishing that @code{nil} were in the list,
9668: most likely what you really want to do is use @kbd{M-x load-file}
9669: this once.
9670:
9671: @cindex autoload
9672: Often you do not have to give any command to load a library, because the
9673: commands defined in the library are set up to @dfn{autoload} that library.
9674: Running any of those commands causes @code{load} to be called to load the
9675: library; this replaces the autoload definitions with the real ones from the
9676: library.
9677:
9678: If autoloading a file does not finish, either because of an error or
9679: because of a @kbd{C-g} quit, all function definitions made by the file are
9680: undone automatically. So are any calls to @code{provide}. As a consequence,
9681: if you use one of the autoloadable commands again, the entire file will be
9682: loaded a second time. This prevents problems where the command is no
9683: longer autoloading but it works wrong because not all the file was loaded.
9684: Function definitions are undone only for autoloading; explicit calls to
9685: @code{load} do not undo anything if loading is not completed.
9686:
9687: @node Compiling Libraries, Mocklisp, Loading, Lisp Libraries
9688: @subsection Compiling Libraries
9689:
9690: @cindex byte code
9691: Emacs Lisp code can be compiled into byte-code which loads faster,
9692: takes up less space when loaded, and executes faster.
9693:
9694: @findex byte-compile-file
9695: The way to make a byte-code compiled file from an Emacs-Lisp source file
9696: is with @kbd{M-x byte-compile-file}. The default argument for this
9697: function is the file visited in the current buffer. It reads the specified
9698: file, compiles it into byte code, and writes an output file whose name is
9699: made by appending @file{c} to the input file name. Thus, the file
9700: @file{rmail.el} would be compiled into @file{rmail.elc}.
9701:
9702: @findex byte-recompile-directory
9703: To recompile the changed Lisp files in a directory, use @kbd{M-x
9704: byte-recompile-directory}. Specify just the directory name as an argument.
9705: Each @file{.el} file that has been byte-compiled before is byte-compiled
9706: again if it has changed since the previous compilation. A numeric argument
9707: to this command tells it to offer to compile each @file{.el} file that has
9708: not already been compiled. You must answer @kbd{y} or @kbd{n} to each
9709: offer.
9710:
9711: @findex batch-byte-compile
9712: Emacs can be invoked noninteractively from the shell to do byte compilation
9713: with the aid of the function @code{batch-byte-compile}. In this case,
9714: the files to be compiled are specified with command-line arguments.
9715: Use a shell command of the form
9716:
9717: @example
9718: emacs -batch -f batch-byte-compile @var{files}...
9719: @end example
9720:
9721: Directory names may also be given as arguments;
9722: @code{byte-recompile-directory} is invoked (in effect) on each such directory.
9723: @code{batch-byte-compile} uses all the remaining command-line arguments as
9724: file or directory names, then kills the Emacs process.
9725:
9726: @cindex disassemble
9727: @findex disassemble
9728: @kbd{M-x disassemble} explains the result of byte compilation. Its
9729: argument is a function name. It displays the byte-compiled code in a help
9730: window in symbolic form, one instruction per line. If the instruction
9731: refers to a variable or constant, that is shown too.
9732:
9733: @node Mocklisp,,Compiling Libraries,Lisp Libraries
9734: @subsection Converting Mocklisp to Lisp
9735:
9736: @cindex mocklisp
9737: @findex convert-mocklisp-buffer
9738: GNU Emacs can run Mocklisp files by converting them to Emacs Lisp first.
9739: To convert a Mocklisp file, visit it and then type @kbd{M-x
9740: convert-mocklisp-buffer}. Then save the resulting buffer of Lisp file in a
9741: file whose name ends in @file{.el} and use the new file as a Lisp library.
9742:
9743: It does not currently work to byte-compile converted Mocklisp code.
9744: This is because converted Mocklisp code uses some special Lisp features
9745: to deal with Mocklisp's incompatible ideas of how arguments are evaluated
9746: and which values signify ``true'' or ``false''.
9747:
9748: @node Lisp Eval, Lisp Debug, Lisp Libraries, Compiling/Testing
9749: @section Evaluating Emacs-Lisp Expressions
9750: @cindex Emacs-Lisp mode
9751:
9752: @findex emacs-lisp-mode
9753: Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp
9754: mode; this will happen automatically for file names ending in @file{.el}.
9755: By contrast, Lisp mode itself is used for editing Lisp programs intended
9756: for other Lisp systems. Emacs-Lisp mode can be selected with the command
9757: @kbd{M-x emacs-lisp-mode}.
9758:
9759: For testing of Lisp programs to run in Emacs, it is useful to be able to
9760: evaluate part of the program as it is found in the Emacs buffer. For
9761: example, after changing the text of a Lisp function definition, evaluating
9762: the definition installs the change for future calls to the function.
9763: Evaluation of Lisp expressions is also useful in any kind of editing task
9764: for invoking noninteractive functions (functions that are not commands).
9765:
9766: @table @kbd
9767: @item M-@key{ESC}
9768: Read a Lisp expression in the minibuffer, evaluate it, and print the
9769: value in the minibuffer (@code{eval-expression}).
9770: @item C-x C-e
9771: Evaluate the Lisp expression before point, and print the value in the
9772: minibuffer (@code{eval-last-sexp}).
9773: @item C-M-x
9774: Evaluate the defun containing or after point, and print the value in
9775: the minibuffer (@code{eval-defun}).
9776: @item M-x eval-region
9777: Evaluate all the Lisp expressions in the region.
9778: @item M-x eval-current-buffer
9779: Evaluate all the Lisp expressions in the buffer.
9780: @end table
9781:
9782: @kindex M-ESC
9783: @findex eval-expression
9784: @kbd{M-@key{ESC}} (@code{eval-expression}) is the most basic command for evaluating
9785: a Lisp expression interactively. It reads the expression using the
9786: minibuffer, so you can execute any expression on a buffer regardless of
9787: what the buffer contains. When the expression is evaluated, the current
9788: buffer is once again the buffer that was current when @kbd{M-@key{ESC}} was
9789: typed.
9790:
9791: @kbd{M-@key{ESC}} can easily confuse users who do not understand it,
9792: especially on keyboards with autorepeat where it can result from holding
9793: down the @key{ESC} key for too long. Therefore, @code{eval-expression} is
9794: normally a disabled command. Attempting to use this command asks for
9795: confirmation and gives you the option of enabling it; once you enable the
9796: command, confirmation will no longer be required for it.
9797: @xref{Disabling}.@refill
9798:
9799: @kindex C-M-x
9800: @findex eval-defun
9801: In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the function @code{eval-defun},
9802: which parses the defun containing or following point as a Lisp expression
9803: and evaluates it. The value is printed in the echo area. This command is
9804: convenient for installing in the Lisp environment changes that you have
9805: just made in the text of a function definition.
9806:
9807: @kindex C-x C-e
9808: @findex eval-last-sexp
9809: The command @kbd{C-x C-e} (@code{eval-last-sexp}) performs a similar job
9810: but is available in all major modes, not just Emacs-Lisp mode. It finds
9811: the sexp before point, reads it as a Lisp expression, evaluates it, and
9812: prints the value in the echo area. It is sometimes useful to type in an
9813: expression and then, with point still after it, type @kbd{C-x C-e}.
9814:
9815: If @kbd{C-M-x} or @kbd{C-x C-e} is given a numeric argument, it prints the value
9816: by insertion into the current buffer at point, rather than in the echo
9817: area. The argument value does not matter.
9818:
9819: @findex eval-region
9820: @findex eval-current-buffer
9821: The most general command for evaluating Lisp expressions from a buffer is
9822: @code{eval-region}. @kbd{M-x eval-region} parses the text of the region as one or
9823: more Lisp expressions, evaluating them one by one. @kbd{M-x eval-current-buffer}
9824: is similar but evaluates the entire buffer. This is a reasonable way to
9825: install the contents of a file of Lisp code that you are just ready to
9826: test. After finding and fixing a bug, use @kbd{C-M-x} on each function
9827: that you change, to keep the Lisp world in step with the source file.
9828:
9829: @node Lisp Debug, Lisp Interaction, Lisp Eval, Compiling/Testing
9830: @section The Emacs-Lisp Debugger
9831: @cindex debugger
9832:
9833: @vindex debug-on-error
9834: @vindex debug-on-quit
9835: GNU Emacs contains a debugger for Lisp programs executing inside it.
9836: This debugger is normally not used; many commands frequently get Lisp
9837: errors when invoked in inappropriate contexts (such as @kbd{C-f} at the end
9838: of the buffer) and it would be very unpleasant for that to enter a special
9839: debugging mode. When you want to make Lisp errors invoke the debugger, you
9840: must set the variable @code{debug-on-error} to non-@code{nil}. Quitting
9841: with @kbd{C-g} is not considered an error, and @code{debug-on-error} has no
9842: effect on the handling of @kbd{C-g}. However, if you set
9843: @code{debug-on-quit} non-@code{nil}, @kbd{C-g} will invoke the debugger.
9844: This can be useful for debugging an infinite loop; type @kbd{C-g} once the
9845: loop has had time to reach its steady state. @code{debug-on-quit} has no
9846: effect on errors.@refill
9847:
9848: @findex debug-on-entry
9849: @findex cancel-debug-on-entry
9850: @findex debug
9851: You can also cause the debugger to be entered when a specified function
9852: is called, or at a particular place in Lisp code. Use @kbd{M-x
9853: debug-on-entry} with argument @var{fun-name} to cause function
9854: @var{fun-name} to enter the debugger as soon as it is called. Use
9855: @kbd{M-x cancel-debug-on-entry} to make the function stop entering the
9856: debugger when called. (Redefining the function also does this.) To enter
9857: the debugger from some other place in Lisp code, you must insert the
9858: expression @code{(debug)} there and install the changed code with
9859: @kbd{C-M-x}. @xref{Lisp Eval}.@refill
9860:
9861: When the debugger is entered, it displays the previously selected buffer
9862: in one window and a buffer named @samp{*Backtrace*} in another window. The
9863: backtrace buffer contains one line for each level of Lisp function
9864: execution currently going on. At the beginning of this buffer is a message
9865: describing the reason that the debugger was invoked (such as, what error
9866: message if it was invoked due to an error).
9867:
9868: @cindex Backtrace mode
9869: The backtrace buffer is read-only, and is in a special major mode,
9870: Backtrace mode, in which letters are defined as debugger commands. The
9871: usual Emacs editing commands are available; you can switch windows to
9872: examine the buffer that was being edited at the time of the error, and you
9873: can also switch buffers, visit files, and do any other sort of editing.
9874: However, the debugger is a recursive editing level (@pxref{Recursive Edit})
9875: and it is wise to go back to the backtrace buffer and exit the debugger
9876: officially when you don't want to use it any more. Exiting the debugger
9877: kills the backtrace buffer.
9878:
9879: @cindex current stack frame
9880: The contents of the backtrace buffer show you the functions that are
9881: executing and the arguments that were given to them. It has the additional
9882: purpose of allowing you to specify a stack frame by moving point to the line
9883: describing that frame. The frame whose line point is on is considered the
9884: @dfn{current frame}. Some of the debugger commands operate on the current
9885: frame. Debugger commands are mainly used for stepping through code an
9886: expression at a time. Here is a list of them.
9887:
9888: @table @kbd
9889: @item c
9890: Exit the debugger and continue execution. In most cases, execution of
9891: the program continues as if the debugger had never been entered (aside
9892: from the effect of any variables or data structures you may have
9893: changed while inside the debugger). This includes entry to the
9894: debugger due to function entry or exit, explicit invocation, quitting
9895: or certain errors. Most errors cannot be continued; trying to
9896: continue one of them causes the same error to occur again.
9897: @item d
9898: Continue execution, but enter the debugger the next time a Lisp
9899: function is called. This allows you to step through the
9900: subexpressions of an expression, seeing what values the subexpressions
9901: compute and what else they do.
9902:
9903: The stack frame made for the function call which enters the debugger
9904: in this way will be flagged automatically for the debugger to be called
9905: when the frame is exited. You can use the @kbd{u} command to cancel
9906: this flag.
9907: @item b
9908: Set up to enter the debugger when the current frame is exited. Frames
9909: that will invoke the debugger on exit are flagged with stars.
9910: @item u
9911: Don't enter the debugger when the current frame is exited. This
9912: cancels a @kbd{b} command on that frame.
9913: @item e
9914: Read a Lisp expression in the minibuffer, evaluate it, and print the
9915: value in the echo area. This is the same as the command @kbd{M-@key{ESC}},
9916: except that @kbd{e} is not normally disabled like @kbd{M-@key{ESC}}.
9917: @item q
9918: Terminate the program being debugged; return to top-level Emacs
9919: command execution.
9920:
9921: If the debugger was entered due to a @kbd{C-g} but you really want
9922: to quit, not to debug, use the @kbd{q} command.
9923: @item r
9924: Return a value from the debugger. The value is computed by reading an
9925: expression with the minibuffer and evaluating it.
9926:
9927: The value returned by the debugger makes a difference when the debugger
9928: was invoked due to exit from a Lisp call frame (as requested with @kbd{b});
9929: then the value specified in the @kbd{r} command is used as the value of
9930: that frame.
9931:
9932: The debugger's return value also matters with many errors. For example,
9933: @code{wrong-type-argument} errors will use the debugger's return value
9934: instead of the invalid argument; @code{no-catch} errors will use the
9935: debugger value as a throw tag instead of the tag that was not found.
9936: If an error was signaled by calling the Lisp function @code{signal},
9937: the debugger's return value is returned as the value of @code{signal}.
9938: @end table
9939:
9940: @node Lisp Interaction, External Lisp, Lisp Debug, Compiling/Testing
9941: @section Lisp Interaction Buffers
9942:
9943: @cindex Lisp Interaction mode
9944: @cindex scratch buffer
9945: The buffer @samp{*scratch*} which is selected when Emacs starts up is
9946: provided for evaluating Lisp expressions interactively inside Emacs. Both
9947: the expressions you evaluate and their output goes in the buffer.
9948:
9949: The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
9950: is the same as Emacs-Lisp mode except for one command, @key{LFD}. In
9951: Emacs-Lisp mode, @key{LFD} is an indentation command, as usual. In Lisp
9952: Interaction mode, @key{LFD} is bound to @code{eval-print-last-sexp}. This
9953: function reads the Lisp expression before point, evaluates it, and inserts
9954: the value in printed representation before point.
9955:
9956: Thus, the way to use the @samp{*scratch*} buffer is to insert Lisp expressions
9957: at the end, ending each one with @key{LFD} so that it will be evaluated.
9958: The result is a complete typescript of the expressions you have evaluated
9959: and their values.
9960:
9961: @findex lisp-interaction-mode
9962: The rationale for this feature is that Emacs must have a buffer when it
9963: starts up, but that buffer is not useful for editing files since a new
9964: buffer is made for every file that you visit. The Lisp interpreter
9965: typescript is the most useful thing I can think of for the initial buffer
9966: to do. @kbd{M-x lisp-interaction-mode} will put any buffer in Lisp
9967: Interaction mode.
9968:
9969: @node External Lisp,, Lisp Interaction, Compiling/Testing
9970: @section Running an External Lisp
9971:
9972: Emacs has facilities for running programs in other Lisp systems. You can
9973: run a Lisp process as an inferior of Emacs, and pass expressions to it to
9974: be evaluated. You can also pass changed function definitions directly from
9975: the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
9976: process.
9977:
9978: @findex run-lisp
9979: @cindex Inferior Lisp mode
9980: To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs the
9981: program named @code{lisp}, the same program you would run by typing
9982: @code{lisp} as a shell command, with both input and output going through an
9983: Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal output''
9984: from Lisp will go into the buffer, advancing point, and any ``terminal
9985: input'' for Lisp comes from text in the buffer. To give input to Lisp, go
9986: to the end of the buffer and type the input, terminated by @key{RET}. The
9987: @samp{*lisp*} buffer is in Inferior Lisp mode, a mode which has all the
9988: special characteristics of Lisp mode and Shell mode (@pxref{Shell Mode}).
9989:
9990: @findex lisp-mode
9991: For the source files of programs to run in external Lisps, use Lisp mode.
9992: This mode can be selected with @kbd{M-x lisp-mode}, and is used automatically
9993: for files whose names end in @file{.l} or @file{.lisp}, as most Lisp
9994: systems usually expect.
9995:
9996: @kindex C-M-x
9997: @findex lisp-send-defun
9998: When you edit a function in a Lisp program you are running, the easiest
9999: way to send the changed definition to the inferior Lisp process is the key
10000: @kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-send-defun},
10001: which finds the defun around or following point and sends it as input to
10002: the Lisp process. (Emacs can send input to any inferior process regardless
10003: of what buffer is current.)
10004:
10005: Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs
10006: to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
10007: programs to be run in Emacs): in both modes it has the effect of installing
10008: the function definition that point is in, but the way of doing so is
10009: different according to where the relevant Lisp environment is found.
10010: @xref{Lisp Modes}.
10011:
10012: @node Abbrevs, Picture, Compiling/Testing, Top
10013: @chapter Abbrevs
10014: @cindex abbrevs
10015: @cindex expansion (of abbrevs)
10016:
10017: An @dfn{abbrev} is a word which @dfn{expands}, if you insert it, into some
10018: different text. Abbrevs are defined by the user to expand in specific
10019: ways. For example, you might define @samp{foo} as an abbrev expanding to
10020: @samp{find outer otter}. With this abbrev defined, you would be able to
10021: get @samp{find outer otter } into the buffer by typing @kbd{f o o @key{SPC}}.
10022:
10023: @cindex Abbrev mode
10024: @findex abbrev-mode
10025: @vindex abbrev-mode
10026: Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
10027: Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
10028: but they do not expand until Abbrev mode is enabled again. The command
10029: @kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
10030: turns Abbrev mode on if the argument is positive, off otherwise.
10031: @xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is
10032: on when the variable is non-@code{nil}. The variable @code{abbrev-mode}
10033: automatically becomes local to the current buffer when it is set.
10034:
10035: Abbrev definitions can be @dfn{mode-specific}---active only in one major
10036: mode. Abbrevs can also have @dfn{global} definitions that are active in
10037: all major modes. The same abbrev can have a global definition and various
10038: mode-specific definitions for different major modes. A mode specific
10039: definition for the current major mode overrides a global definition.
10040:
10041: Abbrevs can be defined interactively during the editing session. Lists
10042: of abbrev definitions can also be saved in files and reloaded in later
10043: sessions. Some users keep extensive lists of abbrevs that they load in
10044: every session.
10045:
10046: A second kind of abbreviation facility is called the @dfn{dynamic
10047: expansion}. Dynamic abbrev expansion happens only when you give an
10048: explicit command and the result of the expansion depends only on the
10049: current contents of the buffer. @xref{Dynamic Abbrevs}.
10050:
10051: @menu
10052: * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
10053: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
10054: * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
10055: * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
10056: * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
10057: @end menu
10058:
10059: @node Defining Abbrevs, Expanding Abbrevs, Abbrevs, Abbrevs
10060: @section Defining Abbrevs
10061:
10062: @table @kbd
10063: @item C-x +
10064: Define an abbrev to expand into some text before point
10065: (@code{add-global-abbrev}).
10066: @item C-x C-a
10067: Similar, but define an abbrev available only in the current major mode
10068: (@code{add-mode-abbrev}).
10069: @item C-x -
10070: Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
10071: @item C-x C-h
10072: Define a word in the buffer as a mode-specific abbrev
10073: (@code{inverse-add-mode-abbrev}).
10074: @item M-x kill-all-abbrevs
10075: After this command, there are no abbrev definitions in effect.
10076: @end table
10077:
10078: @kindex C-x +
10079: @findex add-global-abbrev
10080: The usual way to define an abbrev is to enter the text you want the
10081: abbrev to expand to, position point after it, and type @kbd{C-x +}
10082: (@code{add-global-abbrev}). This reads the abbrev itself using the
10083: minibuffer, and then defines it as an abbrev for one or more words before
10084: point. Use a numeric argument to say how many words before point should be
10085: taken as the expansion. For example, to define the abbrev @samp{foo} as
10086: mentioned above, insert the text @samp{find outer otter} and then type
10087: @kbd{C-u 3 C-x + f o o @key{RET}}.
10088:
10089: An argument of zero to @kbd{C-x +} means to use the contents of the
10090: region as the expansion of the abbrev being defined.
10091:
10092: @kindex C-x C-a
10093: @findex add-mode-abbrev
10094: The command @kbd{C-x C-a} (@code{add-mode-abbrev}) is similar, but
10095: defines a mode-specific abbrev. Mode specific abbrevs are active only in a
10096: particular major mode. @kbd{C-x C-a} defines an abbrev for the major mode
10097: in effect at the time @kbd{C-x C-a} is typed. The arguments work the same
10098: as for @kbd{C-x +}.
10099:
10100: @kindex C-x -
10101: @findex inverse-add-global-abbrev
10102: @kindex C-x C-h
10103: @findex inverse-add-mode-abbrev
10104: If the text of the abbrev you want is already in the buffer instead of
10105: the expansion, use command @kbd{C-x -} (@code{inverse-add-global-abbrev})
10106: instead of @kbd{C-x +}, or use @kbd{C-x C-h}
10107: (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x C-a}. These commands
10108: are called ``inverse'' because they invert the meaning of the argument
10109: found in the buffer and the argument read using the minibuffer.@refill
10110:
10111: To change the definition of an abbrev, just add the new definition. You
10112: will be asked to confirm if the abbrev has a prior definition. To remove
10113: an abbrev definition, give a negative argument to @kbd{C-x +} or @kbd{C-x
10114: C-a}. You must choose the command to specify whether to kill a global
10115: definition or a mode-specific definition for the current mode, since those
10116: two definitions are independent for one abbrev.
10117:
10118: @findex kill-all-abbrevs
10119: @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there are.
10120:
10121: @node Expanding Abbrevs, Editing Abbrevs, Defining Abbrevs, Abbrevs
10122: @section Controlling Abbrev Expansion
10123:
10124: An abbrev expands whenever it is present in the buffer just before point
10125: and a self-inserting punctuation character (@key{SPC}, comma, etc.@:) is
10126: typed. Most often the way an abbrev is used is to insert the abbrev
10127: followed by punctuation.
10128:
10129: @vindex abbrev-all-caps
10130: Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
10131: outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
10132: @samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
10133: variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first
10134: of the two expansions).@refill
10135:
10136: These two commands are used to control abbrev expansion:
10137:
10138: @table @kbd
10139: @item M-'
10140: Separate a prefix from a following abbrev to be expanded
10141: (@code{abbrev-prefix-mark}).
10142: @item C-x '
10143: @findex expand-abbrev
10144: Expand the abbrev before point (@code{expand-abbrev}).
10145: This is effective even when Abbrev mode is not enabled.
10146: @item M-x unexpand-abbrev
10147: Undo last abbrev expansion.
10148: @item M-x expand-region-abbrevs
10149: Expand some or all abbrevs found in the region.
10150: @end table
10151:
10152: @kindex M-'
10153: @findex abbrev-prefix-mark
10154: You may wish to expand an abbrev with a prefix attached; for example, if
10155: @samp{cnst} expands into @samp{construction}, you might want to use it to
10156: enter @samp{reconstruction}. It does not work to type @kbd{recnst},
10157: because that is not necessarily a defined abbrev. What does work is to use
10158: the command @kbd{M-'} (@code{abbrev-prefix-mark}) in between the prefix
10159: @samp{re} and the abbrev @samp{cnst}. First, insert @samp{re}. Then type
10160: @kbd{M-'}; this inserts a minus sign in the buffer to indicate that it has
10161: done its work. Then insert the abbrev @samp{cnst}; the buffer now contains
10162: @samp{re-cnst}. Now insert a punctuation character to expand the abbrev
10163: @samp{cnst} into @samp{construction}. The minus sign is deleted at this
10164: point, because @kbd{M-'} left word for this to be done. The resulting text
10165: is the desired @samp{reconstruction}.@refill
10166:
10167: If you actually want the text of the abbrev in the buffer, rather than
10168: its expansion, you can accomplish this by inserting the following
10169: punctuation with @kbd{C-q}. Thus, @kbd{foo C-q -} leaves @samp{foo-} in the
10170: buffer.
10171:
10172: @findex unexpand-abbrev
10173: If you expand an abbrev by mistake, you can undo the expansion (replace
10174: the expansion by the original abbrev text) with @kbd{M-x unexpand-abbrev}.
10175: @kbd{C-_} (@code{undo}) can also be used to undo the expansion; but first
10176: it will undo the insertion of the following punctuation character!
10177:
10178: @findex expand-region-abbrevs
10179: @kbd{M-x expand-region-abbrevs} searches through the region for defined
10180: abbrevs, and for each one found offers to replace it with its expansion.
10181: This command is useful if you have typed in text using abbrevs but forgot
10182: to turn on Abbrev mode first. It may also be useful together with a
10183: special set of abbrev definitions for making several global replacements at
10184: once. This command is effective even if Abbrev mode is not enabled.
10185:
10186: @node Editing Abbrevs, Saving Abbrevs, Expanding Abbrevs, Abbrevs
10187: @section Examining and Editing Abbrevs
10188:
10189: @table @kbd
10190: @item M-x list-abbrevs
10191: Print a list of all abbrev definitions.
10192: @item M-x edit-abbrevs
10193: Edit a list of abbrevs; you can add, alter or remove definitions.
10194: @end table
10195:
10196: @findex list-abbrevs
10197: The output from @kbd{M-x list-abbrevs} looks like this:
10198:
10199: @example
10200: (lisp-mode-abbrev-table)
10201: "dk" 0 "define-key"
10202: (global-abbrev-table)
10203: "dfn" 0 "definition"
10204: @end example
10205:
10206: @noindent
10207: (Some blank lines of no semantic significance, and some other abbrev
10208: tables, have been omitted.)
10209:
10210: A line containing a name in parentheses is the header for abbrevs in a
10211: particular abbrev table; @code{global-abbrev-table} contains all the global
10212: abbrevs, and the other abbrev tables that are named after major modes
10213: contain the mode-specific abbrevs.
10214:
10215: Within each abbrev table, each nonblank line defines one abbrev. The
10216: word at the beginning is the abbrev. The number that appears is the number
10217: of times the abbrev has been expanded. Emacs keeps track of this to help
10218: you see which abbrevs you actually use, in case you decide to eliminate
10219: those that you don't use often. The string at the end of the line is the
10220: expansion.
10221:
10222: @findex edit-abbrevs
10223: @kindex C-c C-c (Edit Abbrevs)
10224: @findex edit-abbrevs-redefine
10225: @cindex Edit-Abbrevs mode
10226: @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
10227: definitions by editing a list of them in an Emacs buffer. The list has the
10228: same format described above. The buffer of abbrevs is called @samp{*Abbrevs*},
10229: and is in Edit-Abbrevs mode. This mode redefines the key @kbd{C-c C-c} to
10230: install the abbrev definitions as specified in the buffer. The command
10231: that does this is @code{edit-abbrevs-redefine}. Any abbrevs not described
10232: in the buffer are eliminated when this is done.
10233:
10234: @code{edit-abbrevs} is actually the same as @code{list-abbrevs} except
10235: that it selects the buffer @samp{*Abbrevs*} whereas @code{list-abbrevs}
10236: merely displays it in another window.
10237:
10238: @node Saving Abbrevs, Dynamic Abbrevs, Editing Abbrevs, Abbrevs
10239: @section Saving Abbrevs
10240:
10241: These commands allow you to keep abbrev definitions between editing
10242: sessions.
10243:
10244: @table @kbd
10245: @item M-x write-abbrev-file
10246: Write a file describing all defined abbrevs.
10247: @item M-x read-abbrev-file
10248: Read such a file and define abbrevs as specified there.
10249: @item M-x quietly-read-abbrev-file
10250: Similar but do not display a message about what is going on.
10251: @item M-x define-abbrevs
10252: Define abbrevs from buffer.
10253: @item M-x insert-abbrevs
10254: Insert all abbrevs and their expansions into the buffer.
10255: @end table
10256:
10257: @findex write-abbrev-file
10258: @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and
10259: writes a description of all current abbrev definitions into that file. The
10260: text stored in the file looks like the output of @kbd{M-x list-abbrevs}.
10261: This is used to save abbrev definitions for use in a later session.
10262:
10263: @findex read-abbrev-file
10264: @findex quietly-read-abbrev-file
10265: @vindex abbrev-file-name
10266: @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and
10267: reads the file, defining abbrevs according to the contents of the file.
10268: @kbd{M-x quietly-read-abbrev-file} is the same except that it does not
10269: display a message in the echo area saying that it is doing its work; it
10270: is actually useful primarily in the @file{.emacs} file. If an empty
10271: argument is given to either of these functions, the file name used is the
10272: value of the variable @code{abbrev-file-name}, which is by default
10273: @code{"~/.abbrev_defs"}.
10274:
10275: @vindex save-abbrevs
10276: Emacs will offer to save abbrevs automatically if you have changed any of
10277: them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
10278: C-c}). This feature can be inhibited by setting the variable
10279: @code{save-abbrevs} to @code{nil}.
10280:
10281: @findex insert-abbrevs
10282: @findex define-abbrevs
10283: The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
10284: similar to the previous commands but work on text in an Emacs buffer.
10285: @kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
10286: describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
10287: the entire current buffer and defines abbrevs accordingly.@refill
10288:
10289: @node Dynamic Abbrevs,, Saving Abbrevs, Abbrevs
10290: @section Dynamic Abbrev Expansion
10291: @cindex dynamic abbrevs
10292:
10293: The abbrev facility described above operates automatically as you insert
10294: text, but all abbrevs must be defined explicitly. By contrast,
10295: @dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined
10296: automatically from the contents of the buffer, but dynamic abbrev expansion
10297: happens only when you request it explicitly.
10298:
10299: @kindex M-/
10300: @findex dabbrev-expand
10301: @table @kbd
10302: @item M-/
10303: Expand the word in the buffer before point as a @dfn{dynamic abbrev},
10304: by searching in the buffer for words starting with that abbreviation
10305: (@code{dabbrev-expand}).
10306: @end table
10307:
10308: For example, if the buffer contains @samp{does this follow } and you type
10309: @w{@kbd{f o M-/}}, the effect is to insert @samp{follow} because that is
10310: the last word in the buffer that starts with @samp{fo}. A numeric
10311: argument to @kbd{M-/} says to take the second, third, etc.@: distinct
10312: expansion found looking backward from point. Repeating @kbd{M-/}
10313: searches for an alternative expansion by looking farther back. After
10314: the part of the buffer preceding point has been considered, the part
10315: of the buffer after point is searched.
10316:
10317: Dynamic abbrev expansion is completely independent of Abbrev mode; the
10318: expansion of a word with @kbd{M-/} is completely independent of whether it
10319: has a definition as an ordinary abbrev.
10320:
10321: @node Picture, Sending Mail, Abbrevs, Top
10322: @chapter Editing Pictures
10323: @cindex pictures
10324: @findex edit-picture
10325: @cindex Picture mode
10326:
10327: If you want to create a picture made out of text characters (for example,
10328: a picture of the division of a register into fields, as a comment in a
10329: program), use the command @code{edit-picture} to enter Picture mode.
10330:
10331: In Picture mode, editing is based on the @dfn{quarter-plane} model of
10332: text, according to which the text characters lie studded on an area that
10333: stretches infinitely far to the right and downward. The concept of the end
10334: of a line does not exist in this model; the most you can say is where the
10335: last nonblank character on the line is found.
10336:
10337: Of course, Emacs really always considers text as a sequence of
10338: characters, and lines really do have ends. But in Picture mode most
10339: frequently-used keys are rebound to commands that simulate the
10340: quarter-plane model of text. They do this by inserting spaces or by
10341: converting tabs to spaces.
10342:
10343: Most of the basic editing commands of Emacs are redefined by Picture mode
10344: to do essentially the same thing but in a quarter-plane way. In addition,
10345: Picture mode defines various keys starting with the @kbd{C-c} prefix to
10346: run special picture editing commands.
10347:
10348: One of these keys, @kbd{C-c C-c}, is pretty important. Often a picture
10349: is part of a larger file that is usually edited in some other major mode.
10350: @kbd{M-x edit-picture} records the name of the previous major mode, and
10351: then you can use the @kbd{C-c C-c} command (@code{picture-mode-exit}) to
10352: restore that mode. @kbd{C-c C-c} also deletes spaces from the ends of
10353: lines, unless given a numeric argument.
10354:
10355: The commands used in Picture mode all work in other modes (provided the
10356: @file{picture} library is loaded), but are not bound to keys except in
10357: Picture mode. Note that the descriptions below talk of moving ``one
10358: column'' and so on, but all the picture mode commands handle numeric
10359: arguments as their normal equivalents do.
10360:
10361: @vindex picture-mode-hook
10362: Turning on Picture mode calls the value of the variable @code{picture-mode-hook}
10363: as a function, with no arguments, if that value exists and is non-@code{nil}.
10364:
10365: @menu
10366: * Basic Picture:: Basic concepts and simple commands of Picture Mode.
10367: * Insert in Picture:: Controlling direction of cursor motion
10368: after "self-inserting" characters.
10369: * Tabs in Picture:: Various features for tab stops and indentation.
10370: * Rectangles in Picture:: Clearing and superimposing rectangles.
10371: @end menu
10372:
10373: @node Basic Picture, Insert in Picture, Picture, Picture
10374: @section Basic Editing in Picture Mode
10375:
10376: @findex picture-forward-column
10377: @findex picture-backward-column
10378: @findex picture-move-down
10379: @findex picture-move-up
10380: Most keys do the same thing in Picture mode that they usually do, but do
10381: it in a quarter-plane style. For example, @kbd{C-f} is rebound to run
10382: @code{picture-forward-column}, which is defined to move point one column to
10383: the right, by inserting a space if necessary, so that the actual end of the
10384: line makes no difference. @kbd{C-b} is rebound to run
10385: @code{picture-backward-column}, which always moves point left one column,
10386: converting a tab to multiple spaces if necessary. @kbd{C-n} and @kbd{C-p}
10387: are rebound to run @code{picture-move-down} and @code{picture-move-up},
10388: which can either insert spaces or convert tabs as necessary to make sure
10389: that point stays in exactly the same column. @kbd{C-e} runs
10390: @code{picture-end-of-line}, which moves to after the last nonblank
10391: character on the line. There is no need to change @kbd{C-a}, as the choice
10392: of screen model does not affect beginnings of lines.@refill
10393:
10394: @findex picture-newline
10395: Insertion of text is adapted to the quarter-plane screen model through
10396: the use of Overwrite mode (@pxref{Minor Modes}). Self-inserting characters
10397: replace existing text, column by column, rather than pushing existing text
10398: to the right. @key{RET} runs @code{picture-newline}, which just moves to
10399: the beginning of the following line so that new text will replace that
10400: line.
10401:
10402: @findex picture-backward-clear-column
10403: @findex picture-clear-column
10404: @findex picture-clear-line
10405: Deletion and killing of text are replaced with erasure. @key{DEL}
10406: (@code{picture-backward-clear-column}) replaces the preceding character
10407: with a space rather than removing it. @kbd{C-d}
10408: (@code{picture-clear-column}) does the same thing in a forward direction.
10409: @kbd{C-k} (@code{picture-clear-line}) really kills the contents of lines,
10410: but does not ever remove the newlines from the buffer.@refill
10411:
10412: @findex picture-open-line
10413: To do actual insertion, you must use special commands. @kbd{C-o}
10414: (@code{picture-open-line}) still creates a blank line, but does so after
10415: the current line; it never splits a line. @kbd{C-M-o}, @code{split-line},
10416: makes sense in Picture mode, so it is not changed. @key{LFD}
10417: (@code{picture-duplicate-line}) inserts below the current line another line
10418: with the same contents.@refill
10419:
10420: @kindex C-c C-d (Picture mode)
10421: @findex delete-char
10422: Real deletion can be done with @kbd{C-w}, or with @kbd{C-c C-d} (which is
10423: defined as @code{delete-char}, as @kbd{C-d} is in other modes), or with one
10424: of the picture rectangle commands (@pxref{Rectangles in Picture}).
10425:
10426: @node Insert in Picture, Tabs in Picture, Basic Picture, Picture
10427: @section Controlling Motion after Insert
10428:
10429: @findex picture-movement-up
10430: @findex picture-movement-down
10431: @findex picture-movement-left
10432: @findex picture-movement-right
10433: @findex picture-movement-nw
10434: @findex picture-movement-ne
10435: @findex picture-movement-sw
10436: @findex picture-movement-se
10437: @kindex C-c < (Picture mode)
10438: @kindex C-c > (Picture mode)
10439: @kindex C-c ^ (Picture mode)
10440: @kindex C-c . (Picture mode)
10441: @kindex C-c ` (Picture mode)
10442: @kindex C-c ' (Picture mode)
10443: @kindex C-c / (Picture mode)
10444: @kindex C-c \ (Picture mode)
10445: Since ``self-inserting'' characters in Picture mode just overwrite and
10446: move point, there is no essential restriction on how point should be moved.
10447: Normally point moves right, but you can specify any of the eight orthogonal
10448: or diagonal directions for motion after a ``self-inserting'' character.
10449: This is useful for drawing lines in the buffer.
10450:
10451: @table @kbd
10452: @item C-c <
10453: Move left after insertion (@code{picture-movement-left}).
10454: @item C-c >
10455: Move right after insertion (@code{picture-movement-right}).
10456: @item C-c ^
10457: Move up after insertion (@code{picture-movement-up}).
10458: @item C-c .
10459: Move down after insertion (@code{picture-movement-down}).
10460: @c !!! added @* to prevent overfull hbox
10461: @item C-c `
10462: Move up and left (``northwest'') after insertion@*
10463: (@code{picture-movement-nw}).
10464: @item C-c '
10465: Move up and right (``northeast'') after insertion
10466: (@code{picture-movement-ne}).
10467: @item C-c /
10468: Move down and left (``southwest'') after insertion
10469: (@code{picture-movement-sw}).
10470: @item C-c \
10471: Move down and right (``southeast'') after insertion
10472: (@code{picture-movement-se}).
10473: @end table
10474:
10475: @kindex C-c C-f (Picture mode)
10476: @kindex C-c C-b (Picture mode)
10477: @findex picture-motion
10478: @findex picture-motion-reverse
10479: Two motion commands move based on the current Picture insertion
10480: direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
10481: same direction as motion after ``insertion'' currently does, while @kbd{C-c
10482: C-b} (@code{picture-motion-reverse}) moves in the opposite direction.
10483:
10484: @node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
10485: @section Picture Mode Tabs
10486:
10487: @kindex M-TAB
10488: @findex picture-tab-search
10489: @vindex picture-tab-chars
10490: Two kinds of tab-like action are provided in Picture mode.
10491: Context-based tabbing is done with @kbd{M-@key{TAB}}
10492: (@code{picture-tab-search}). With no argument, it moves to a point
10493: underneath the next ``interesting'' character that follows whitespace in
10494: the previous nonblank line. ``Next'' here means ``appearing at a
10495: horizontal position greater than the one point starts out at''. With an
10496: argument, as in @kbd{C-u M-@key{TAB}}, this command moves to the next such
10497: interesting character in the current line. @kbd{M-@key{TAB}} does not
10498: change the text; it only moves point. ``Interesting'' characters are
10499: defined by the variable @code{picture-tab-chars}, which contains a string
10500: whose characters are all considered interesting. Its default value is
10501: @code{"!-~"}.@refill
10502:
10503: @findex picture-tab
10504: @key{TAB} itself runs @code{picture-tab}, which operates based on the
10505: current tab stop settings; it is the Picture mode equivalent of
10506: @code{tab-to-tab-stop}. Normally it just moves point, but with a numeric
10507: argument it clears the text that it moves over.
10508:
10509: @kindex C-c TAB (Picture mode)
10510: @findex picture-set-tab-stops
10511: The context-based and tab-stop-based forms of tabbing are brought
10512: together by the command @kbd{C-c @key{TAB}}, @code{picture-set-tab-stops}.
10513: This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
10514: would consider significant in the current line. The use of this command,
10515: together with @key{TAB}, can get the effect of context-based tabbing. But
10516: @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
10517:
10518: @node Rectangles in Picture,, Tabs in Picture, Picture
10519: @section Picture Mode Rectangle Commands
10520: @cindex rectangles and Picture mode
10521:
10522: Picture mode defines commands for working on rectangular pieces of the
10523: text in ways that fit with the quarter-plane model. The standard rectangle
10524: commands may also be useful (@pxref{Rectangles}).
10525:
10526: @table @kbd
10527: @item C-c C-k
10528: Clear out the region-rectangle (@code{picture-clear-rectangle}). With
10529: argument, kill it.
10530: @item C-c C-w @var{r}
10531: Similar but save rectangle contents in register @var{r} first
10532: (@code{picture-clear-rectangle-to-register}).
10533: @item C-c C-y
10534: Copy last killed rectangle into the buffer by overwriting, with upper
10535: left corner at point (@code{picture-yank-rectangle}). With argument,
10536: insert instead.
10537: @item C-c C-x @var{r}
10538: Similar, but use the rectangle in register @var{r}
10539: (@code{picture-yank-rectangle-from-register}).
10540: @end table
10541:
10542: @kindex C-c C-k (Picture mode)
10543: @kindex C-c C-w (Picture mode)
10544: @findex picture-clear-rectangle
10545: @findex picture-clear-rectangle-to-register
10546: The picture rectangle commands @kbd{C-c C-k}
10547: (@code{picture-clear-rectangle}) and @kbd{C-c C-w}
10548: (@code{picture-clear-rectangle-to-register}) differ from the standard
10549: rectangle commands in that they normally clear the rectangle instead of
10550: deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
10551: mode.@refill
10552:
10553: However, deletion of rectangles can be useful in Picture mode, so these
10554: commands delete the rectangle if given a numeric argument.
10555:
10556: @kindex C-c C-y (Picture mode)
10557: @kindex C-c C-x (Picture mode)
10558: @findex picture-yank-rectangle
10559: @findex picture-yank-rectangle-from-register
10560: The Picture mode commands for yanking rectangles differ from the standard
10561: ones in overwriting instead of inserting. This is the same way that
10562: Picture mode insertion of other text is different from other modes.
10563: @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts (by overwriting) the
10564: rectangle that was most recently killed, while @kbd{C-c C-x}
10565: (@code{picture-yank-rectangle-from-register}) does likewise for the
10566: rectangle found in a specified register.
10567:
10568: @node Sending Mail, Rmail, Picture, Top
10569: @chapter Sending Mail
10570: @cindex mail
10571: @cindex message
10572:
10573: To send a message in Emacs, you start by typing a command (@kbd{C-x m})
10574: to select and initialize the @samp{*mail*} buffer. Then you edit the text
10575: and headers of the message in this buffer, and type another command
10576: (@kbd{C-c C-c}) to send the message.
10577:
10578: @table @kbd
10579: @item C-x m
10580: Begin composing a message to send (@code{mail}).
10581: @item C-x 4 m
10582: Likewise, but display the message in another window
10583: (@code{mail-other-window}).
10584: @item C-c C-c
10585: In Mail mode, send the message and switch to another buffer
10586: (@code{mail-send-and-exit}).
10587: @end table
10588:
10589: @kindex C-x m
10590: @findex mail
10591: @kindex C-x 4 m
10592: @findex mail-other-window
10593: The command @kbd{C-x m} (@code{mail}) selects a buffer named
10594: @samp{*mail*} and initializes it with the skeleton of an outgoing message.
10595: @kbd{C-x 4 m} (@code{mail-other-window}) selects the @samp{*mail*} buffer
10596: in a different window, leaving the previous current buffer visible.@refill
10597:
10598: Because the mail composition buffer is an ordinary Emacs buffer, you can
10599: switch to other buffers while in the middle of composing mail, and switch
10600: back later (or never). If you use the @kbd{C-x m} command again when you
10601: have been composing another message but have not sent it, you are asked to
10602: confirm before the old message is erased. If you answer @kbd{n}, the
10603: @samp{*mail*} buffer is left selected with its old contents, so you can
10604: finish the old message and send it. @kbd{C-u C-x m} is another way to do
10605: this. Sending the message marks the @samp{*mail*} buffer ``unmodified'',
10606: which avoids the need for confirmation when @kbd{C-x m} is next used.
10607:
10608: If you are composing a message in the @samp{*mail*} buffer and want to
10609: send another message before finishing the first, rename the @samp{*mail*}
10610: buffer using @kbd{M-x rename-buffer} (@pxref{Misc Buffer}).
10611:
10612: @menu
10613: * Format: Mail Format. Format of the mail being composed.
10614: * Headers: Mail Headers. Details of allowed mail header fields.
10615: * Mode: Mail Mode. Special commands for editing mail being composed.
10616: @end menu
10617:
10618: @node Mail Format, Mail Headers, Sending Mail, Sending Mail
10619: @section The Format of the Mail Buffer
10620:
10621: In addition to the @dfn{text} or contents, a message has @dfn{header
10622: fields} which say who sent it, when, to whom, why, and so on. Some header
10623: fields such as the date and sender are created automatically after the
10624: message is sent. Others, such as the recipient names, must be specified by
10625: you in order to send the message properly.
10626:
10627: Mail mode provides a few commands to help you edit some header fields,
10628: and some are preinitialized in the buffer automatically at times. You can
10629: insert or edit any header fields using ordinary editing commands.
10630:
10631: The line in the buffer that says
10632:
10633: @example
10634: --text follows this line--
10635: @end example
10636:
10637: @vindex mail-header-separator
10638: @noindent
10639: is a special delimiter that separates the headers you have specified from
10640: the text. Whatever follows this line is the text of the message; the
10641: headers precede it. The delimiter line itself does not appear in the
10642: message actually sent. The text used for the delimiter line is controlled
10643: by the variable @code{mail-header-separator}.
10644:
10645: Here is an example of what the headers and text in the @samp{*mail*} buffer
10646: might look like.
10647:
10648: @example
10649: To: rms@@mc
10650: CC: mly@@mc, rg@@oz
10651: Subject: The Emacs Manual
10652: --Text follows this line--
10653: Please ignore this message.
10654: @end example
10655:
10656: @node Mail Headers, Mail Mode, Mail Format, Sending Mail
10657: @section Mail Header Fields
10658: @cindex headers (of mail message)
10659:
10660: There are several header fields you can use in the @samp{*mail*} buffer.
10661: Each header field starts with a field name at the beginning of a line,
10662: terminated by a colon. It does not matter whether you use upper or lower
10663: case in the field name. After the colon and optional whitespace comes the
10664: contents of the field.
10665:
10666: @table @samp
10667: @item To
10668: This field contains the mailing addresses to which the message is
10669: addressed.
10670:
10671: @item Subject
10672: The contents of the @samp{Subject} field should be a piece of text
10673: that says what the message is about. The reason @samp{Subject} fields
10674: are useful is that most mail-reading programs can provide a summary of
10675: messages, listing the subject of each message but not its text.
10676:
10677: @item CC
10678: This field contains additional mailing addresses to send the message
10679: to, but whose readers should not regard the message as addressed to
10680: them.
10681:
10682: @item BCC
10683: This field contains additional mailing addresses to send the message
10684: to, but which should not appear in the header of the message actually
10685: sent.
10686:
10687: @item FCC
10688: This field contains the name of one file (in Unix mail file format) to
10689: which a copy of the message should be appended when the message is
10690: sent.
10691:
10692: @item From
10693: Use the @samp{From} field to say who you are, when the account you are
10694: using to send the mail is not your own. The contents of the
10695: @samp{From} field should be a valid mailing address, since replies
10696: will normally go there.
10697:
10698: @item Reply-To
10699: Use the @samp{Reply-to} field to direct replies to a different
10700: address, not your own. There is no difference between @samp{From} and
10701: @samp{Reply-to} in their effect on where replies go, but they convey a
10702: different meaning to the human who reads the message.
10703:
10704: @vindex mail-default-reply-to
10705: If you set the variable @code{mail-default-reply-to} to a non-@code{nil}
10706: value, then every message you begin to edit will have a @samp{Reply-to}
10707: field whose contents are the value of the variable.
10708:
10709: @item In-Reply-To
10710: This field contains a piece of text describing a message you are
10711: replying to. Some mail systems can use this information to correlate
10712: related pieces of mail. Normally this field is filled in by Rmail
10713: when you are replying to a message in Rmail, and you never need to
10714: think about it (@pxref{Rmail}).
10715: @end table
10716:
10717: The @samp{To}, @samp{CC}, @samp{BCC} and @samp{FCC} fields can appear
10718: any number of times, to specify many places to send the message.
10719:
10720: The @samp{To}, @samp{CC}, and @samp{BCC} fields can have continuation
10721: lines. All the lines starting with whitespace, following the line on
10722: which the field starts, are considered part of the field. For
10723: example,@refill
10724:
10725: @example
10726: @group
10727: To: foo@@here, this@@there,
10728: me@@gnu.cambridge.mass.usa.earth.spiral3281
10729: @end group
10730: @end example
10731:
10732: If you have a @file{~/.mailrc} file, Emacs will scan it for mail aliases
10733: the first time you try to send mail in an Emacs session. Aliases found
10734: in the @samp{To}, @samp{CC}, and @samp{BCC} fields will be expanded where
10735: appropriate.
10736:
10737: @vindex mail-archive-file-name
10738: If the variable @code{mail-archive-file-name} is non-@code{nil}, it should be a
10739: string naming a file; every time you start to edit a message to send,
10740: an @samp{FCC} field will be put in for that file. Unless you remove the
10741: @samp{FCC} field, every message will be written into that file when it is
10742: sent.
10743:
10744: @node Mail Mode,, Mail Headers, Sending Mail
10745: @section Mail Mode
10746: @cindex Mail mode
10747:
10748: The major mode used in the @samp{*mail*} buffer is Mail mode, which is
10749: much like Text mode except that various special commands are provided on
10750: the @w{@kbd{C-c}} prefix. These commands all have to do specifically with
10751: editing or sending the message.
10752:
10753: @table @kbd
10754: @item C-c C-s
10755: Send the message, and leave the @samp{*mail*} buffer selected
10756: (@code{mail-send}).
10757: @item C-c C-c
10758: Send the message, and select some other buffer (@code{mail-send-and-exit}).
10759: @item C-c C-f C-t
10760: Move to the @samp{To} header field, creating one if there is none
10761: (@code{mail-to}).
10762: @item C-c C-f C-s
10763: Move to the @samp{Subject} header field, creating one if there is
10764: none (@code{mail-subject}).
10765: @item C-c C-f C-c
10766: Move to the @samp{CC} header field, creating one if there is none
10767: (@code{mail-cc}).
10768: @item C-c C-w
10769: Insert the file @file{~/.signature} at the end of the message text
10770: (@code{mail-signature}).
10771: @item C-c C-y
10772: Yank the selected message from Rmail (@code{mail-yank-original}).
10773: This command does nothing unless your command to start sending a
10774: message was issued with Rmail.
10775: @item C-c C-q
10776: Fill all paragraphs of yanked old messages, each individually
10777: (@code{mail-fill-yanked-message}).
10778: @end table
10779:
10780: @kindex C-c C-s (Mail mode)
10781: @kindex C-c C-c (Mail mode)
10782: @findex mail-send
10783: @findex mail-send-and-exit
10784: There are two ways to send the message. @kbd{C-c C-s} (@code{mail-send})
10785: sends the message and marks the @samp{*mail*} buffer unmodified, but leaves
10786: that buffer selected so that you can modify the message (perhaps with new
10787: recipients) and send it again. @kbd{C-c C-c} (@code{mail-send-and-exit})
10788: sends and then deletes the window (if there is another window) or switches
10789: to another buffer. It puts the @samp{*mail*} buffer at the lowest priority
10790: for automatic reselection, since you are finished with using it. This is
10791: the usual way to send the message.
10792:
10793: @kindex C-c C-f C-t (Mail mode)
10794: @findex mail-to
10795: @kindex C-c C-f C-s (Mail mode)
10796: @findex mail-subject
10797: @kindex C-c C-f C-c (Mail mode)
10798: @findex mail-cc
10799: Mail mode provides some other special commands that are useful for
10800: editing the headers and text of the message before you send it. There are
10801: three commands defined to move point to particular header fields, all based
10802: on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). They are
10803: @kbd{C-c C-f C-t} (@code{mail-to}) to move to the @samp{To} field, @kbd{C-c
10804: C-f C-s} (@code{mail-subject}) for the @samp{Subject} field, and @kbd{C-c
10805: C-f C-c} (@code{mail-cc}) for the @samp{CC} field. These fields have
10806: special motion commands because they are the most common fields for the
10807: user to want to edit.
10808:
10809: @kindex C-c C-w (Mail mode)
10810: @findex mail-signature
10811: @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece text at the end of the
10812: message to say more about who you are. The text comes from the file
10813: @file{.signature} in your home directory.
10814:
10815: @kindex C-c C-y (Mail mode)
10816: @findex mail-yank-original
10817: When mail sending is invoked from the Rmail mail reader using an Rmail
10818: command, @kbd{C-c C-y} can be used inside the @samp{*mail*} buffer to insert
10819: the text of the message you are replying to. Normally it indents each line
10820: of that message four spaces and eliminates most header fields. A numeric
10821: argument specifies the number of spaces to indent. An argument of just
10822: @kbd{C-u} says not to indent at all and not to eliminate anything.
10823: @kbd{C-c C-y} always uses the current message from the @samp{RMAIL} buffer,
10824: so you can insert several old messages by selecting one in @samp{RMAIL},
10825: switching to @samp{*mail*} and yanking it, then switching back to
10826: @samp{RMAIL} to select another.@refill
10827:
10828: @kindex C-c C-q (Mail mode)
10829: @findex mail-fill-yanked-message
10830: @c !!! the following is verbose to prevent an overfull hbox
10831: After using @kbd{C-c C-y}, you can type
10832: the command @kbd{C-c C-q} (@code{mail-fill-yanked-message}) to
10833: fill the paragraphs of the yanked old message or messages. One
10834: use of @kbd{C-c C-q} fills all such paragraphs, each one separately.
10835:
10836: @vindex mail-mode-hook
10837: @vindex mail-setup-hook
10838: Turning on Mail mode (which @kbd{C-x m} does automatically) calls the
10839: value of @code{text-mode-hook}, if it is not void or @code{nil}, and
10840: then calls the value of @code{mail-mode-hook} if that is not void or
10841: @code{nil}. Aside from these, the @code{mail} command runs
10842: @code{mail-setup-hook} whenever it initializes the @samp{*mail*} buffer
10843: for editing a message.
10844:
10845: @node Rmail, Recursive Edit, Sending Mail, Top
10846: @chapter Reading Mail with Rmail
10847: @cindex Rmail
10848: @cindex message
10849: @findex rmail
10850: @cindex Rmail mode
10851:
10852: Rmail is an Emacs subsystem for reading and disposing of mail that you
10853: receive. Rmail stores mail messages in files called @dfn{Rmail
10854: files}. Reading the message in an Rmail file is done in a special
10855: major mode, Rmail mode, which redefines most letters to run commands
10856: for managing mail. To enter Rmail, type @kbd{M-x rmail}. This reads
10857: your primary mail file, merges new mail in from your inboxes, displays
10858: the first new message, and lets you begin reading.
10859:
10860: @cindex primary mail file
10861: Using Rmail in the simplest fashion, you have one Rmail file, @file{~/RMAIL},
10862: in which all of your mail is saved. It is called your @dfn{primary mail
10863: file}. In more sophisticated usage, you can copy messages into other Rmail
10864: files and then edit those files with Rmail.
10865:
10866: Rmail displays only one message at a time. It is called the @dfn{current
10867: message}. Rmail mode's special commands can do such things as move to
10868: another message, delete the message, copy the message into another file, or
10869: send a reply.
10870:
10871: @cindex message number
10872: Within the Rmail file, messages are arranged sequentially in order
10873: of receipt. They are also assigned consecutive integers as their
10874: @dfn{message numbers}. The number of the current message is displayed
10875: in Rmail's mode line, followed by the total number of messages in the
10876: file. You can move to a message by specifying its message number
10877: using the @kbd{j} key (@pxref{Rmail Motion}).
10878:
10879: @kindex s (Rmail)
10880: @findex rmail-save
10881: Following the usual conventions of Emacs, changes in an Rmail file become
10882: permanent only when the file is saved. You can do this with @kbd{s}
10883: (@code{rmail-save}), which also expunges deleted messages from the file
10884: first (@pxref{Rmail Deletion}). To save the file without expunging, use
10885: @kbd{C-x C-s}. Rmail saves the Rmail file spontaneously when moving new
10886: mail from an inbox file (@pxref{Rmail Inbox}).
10887:
10888: @kindex q (Rmail)
10889: @findex rmail-quit
10890: You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and saves the
10891: Rmail file and then switches to another buffer. But there is no need to
10892: `exit' formally. If you switch from Rmail to editing in other buffers, and
10893: never happen to switch back, you have exited. Just make sure to save the
10894: Rmail file eventually (like any other file you have changed). @kbd{C-x s}
10895: is a good enough way to do this (@pxref{Saving}).
10896:
10897: @menu
10898: * Scroll: Rmail Scrolling. Scrolling through a message.
10899: * Motion: Rmail Motion. Moving to another message.
10900: * Deletion: Rmail Deletion. Deleting and expunging messages.
10901: * Inbox: Rmail Inbox. How mail gets into the Rmail file.
10902: * Files: Rmail Files. Using multiple Rmail files.
10903: * Output: Rmail Output. Copying message out to files.
10904: * Labels: Rmail Labels. Classifying messages by labeling them.
10905: * Summary: Rmail Summary. Summaries show brief info on many messages.
10906: * Reply: Rmail Reply. Sending replies to messages you are viewing.
10907: * Editing: Rmail Editing. Editing message text and headers in Rmail.
10908: * Digest: Rmail Digest. Extracting the messages from a digest message.
10909: @end menu
10910:
10911: @node Rmail Scrolling, Rmail Motion, Rmail, Rmail
10912: @section Scrolling Within a Message
10913:
10914: When Rmail displays a message that does not fit on the screen, it is
10915: necessary to scroll through it. This could be done with @kbd{C-v}, @kbd{M-v}
10916: and @kbd{M-<}, but in Rmail scrolling is so frequent that it deserves to be
10917: easier to type.
10918:
10919: @need 1800
10920: @table @kbd
10921: @item @key{SPC}
10922: Scroll forward (@code{scroll-up}).
10923: @item @key{DEL}
10924: Scroll backward (@code{scroll-down}).
10925: @item .
10926: Scroll to start of message (@code{rmail-beginning-of-message}).
10927: @end table
10928:
10929: @kindex SPC (Rmail)
10930: @kindex DEL (Rmail)
10931: Since the most common thing to do while reading a message is to scroll
10932: through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
10933: @kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down}).
10934:
10935: @kindex . (Rmail)
10936: @findex rmail-beginning-of-message
10937: The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
10938: beginning of the selected message. This is not quite the same as @kbd{M-<}:
10939: for one thing, it does not set the mark; for another, it resets the buffer
10940: boundaries to the current message if you have changed them.
10941:
10942: @node Rmail Motion, Rmail Deletion, Rmail Scrolling, Rmail
10943: @section Moving Among Messages
10944:
10945: The most basic thing to do with a message is to read it. The way to do
10946: this in Rmail is to make the message current. You can make any message
10947: current given its message number using the @kbd{j} command, but the usual
10948: thing to do is to move sequentially through the file, since this is the
10949: order of receipt of messages. When you enter Rmail, you are positioned at
10950: the first new message (new messages are those received since the previous
10951: use of Rmail), or at the last message if there are no new messages this
10952: time. Move forward to see the other new messages; move backward to
10953: reexamine old messages.
10954:
10955: @table @kbd
10956: @item n
10957: Move to the next nondeleted message, skipping any intervening deleted
10958: messages (@code{rmail-next-undeleted-message}).
10959: @item p
10960: @c !!! added @* to prevent overfull hbox
10961: Move to the previous nondeleted message@*
10962: (@code{rmail-previous-undeleted-message}).
10963: @item M-n
10964: @c !!! added @* to prevent overfull hbox
10965: Move to the next message, including deleted messages@*
10966: (@code{rmail-next-message}).
10967: @item M-p
10968: @c !!! added @* to prevent overfull hbox
10969: Move to the previous message, including deleted messages@*
10970: (@code{rmail-previous-message}).
10971: @item j
10972: Move to the first message. With argument @var{n}, move to
10973: message number @var{n} (@code{rmail-show-message}).
10974: @item >
10975: Move to the last message (@code{rmail-last-message}).
10976:
10977: @item M-s @var{regexp} @key{RET}
10978: Move to the next message containing a match for @var{regexp}
10979: (@code{rmail-search}). If @var{regexp} is empty, the last regexp used is
10980: used again.
10981:
10982: @item - M-s @var{regexp} @key{RET}
10983: Move to the previous message containing a match for @var{regexp}.
10984: If @var{regexp} is empty, the last regexp used is used again.
10985: @end table
10986:
10987: @kindex n (Rmail)
10988: @kindex p (Rmail)
10989: @kindex M-n (Rmail)
10990: @kindex M-p (Rmail)
10991: @findex rmail-next-undeleted-message
10992: @findex rmail-previous-undeleted-message
10993: @findex rmail-next-message
10994: @findex rmail-previous-message
10995: @kbd{n} and @kbd{p} are the usual way of moving among messages in Rmail. They
10996: move through the messages sequentially, but skip over deleted messages,
10997: which is usually what you want to do. Their command definitions are named
10998: @code{rmail-next-undeleted-message} and @code{rmail-previous-undeleted-message}. If
10999: you do not want to skip deleted messages---for example, if you want to move
11000: to a message to undelete it---use the variants @kbd{M-n} and @kbd{M-p}
11001: (@code{rmail-next-message} and @code{rmail-previous-message}). A numeric
11002: argument to any of these commands serves as a repeat count.@refill
11003:
11004: In Rmail, you can specify a numeric argument by typing the digits.
11005: It is not necessary to type @kbd{C-u} first.
11006:
11007: @kindex M-s (Rmail)
11008: @findex rmail-search
11009: The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of search. The
11010: usual incremental search command @kbd{C-s} works in Rmail, but it searches
11011: only within the current message. The purpose of @kbd{M-s} is to search for
11012: another message. It reads a regular expression (@pxref{Regexps})
11013: nonincrementally, then searches starting at the beginning of the following
11014: message for a match. The message containing the match is selected.
11015:
11016: To search backward in the file for another message, give @kbd{M-s} a
11017: negative argument. In Rmail this can be done with @kbd{- M-s}.
11018:
11019: It is also possible to search for a message based on labels.
11020: @xref{Rmail Labels}.
11021:
11022: @kindex j (Rmail)
11023: @kindex > (Rmail)
11024: @findex rmail-show-message
11025: @findex rmail-last-message
11026: To move to a message specified by absolute message number, use @kbd{j}
11027: (@code{rmail-show-message}) with the message number as argument. With no
11028: argument, @kbd{j} selects the first message. @kbd{>} (@code{rmail-last-message}) selects
11029: the last message.
11030:
11031: Each time Rmail selects a message, it calls (with no arguments) the
11032: value of the variable @code{rmail-show-message-hook}, if that is
11033: non-@code{nil}.
11034:
11035: @node Rmail Deletion, Rmail Inbox, Rmail Motion, Rmail
11036: @section Deleting Messages
11037:
11038: @cindex deletion (Rmail)
11039: When you no longer need to keep a message, you can @dfn{delete} it. This
11040: flags it as ignorable, and some Rmail commands will pretend it is no longer
11041: present; but it still has its place in the Rmail file, and still has its
11042: message number.
11043:
11044: @cindex expunging (Rmail)
11045: @dfn{Expunging} the Rmail file actually removes the deleted messages.
11046: The remaining messages are renumbered consecutively. Expunging is the only
11047: action that changes the message number of any message, except for
11048: undigestifying (@pxref{Rmail Digest}).
11049:
11050: @table @kbd
11051: @item d
11052: Delete the current message, and move to the next nondeleted message
11053: (@code{rmail-delete-forward}).
11054: @item C-d
11055: Delete the current message, and move to the previous nondeleted
11056: message (@code{rmail-delete-backward}).
11057: @item u
11058: Undelete the current message, or move back to a deleted message and
11059: undelete it (@code{rmail-undelete-previous-message}).
11060: @item x
11061: @itemx e
11062: Expunge the Rmail file (@code{rmail-expunge}). These two
11063: commands are synonyms.
11064: @end table
11065:
11066: @kindex d (Rmail)
11067: @kindex C-d (Rmail)
11068: @findex rmail-delete-forward
11069: @findex rmail-delete-backward
11070: There are two Rmail commands for deleting messages. Both delete the
11071: current message and select another message. @kbd{d} (@code{rmail-delete-forward})
11072: moves to the following message, skipping messages already deleted, while
11073: @kbd{C-d} (@code{rmail-delete-backward}) moves to the previous nondeleted message.
11074: If there is no nondeleted message to move to in the specified direction,
11075: the message that was just deleted remains current.
11076:
11077: @cindex undeletion (Rmail)
11078: @kindex e (Rmail)
11079: @findex rmail-expunge
11080: To make all the deleted messages finally vanish from the Rmail file,
11081: type @kbd{e} (@code{rmail-expunge}). Until you do this, you can still @dfn{undelete}
11082: the deleted messages.
11083:
11084: @kindex u (Rmail)
11085: @findex rmail-undelete-previous-message
11086: To undelete, type
11087: @kbd{u} (@code{rmail-undelete-previous-message}), which is designed to cancel the
11088: effect of a @kbd{d} command (usually). It undeletes the current message
11089: if the current message is deleted. Otherwise it moves backward to previous
11090: messages until a deleted message is found, and undeletes that message.
11091:
11092: You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} moves
11093: back to and undeletes the message that the @kbd{d} deleted. But this does
11094: not work when the @kbd{d} skips a few already-deleted messages that follow
11095: the message being deleted; then the @kbd{u} command will undelete the last
11096: of the messages that were skipped. There is no clean way to avoid this
11097: problem. However, by repeating the @kbd{u} command, you can eventually get
11098: back to the message that you intended to undelete. You can also reach that
11099: message with @kbd{M-p} commands and then type @kbd{u}.@refill
11100:
11101: A deleted message has the @samp{deleted} attribute, and as a result
11102: @samp{deleted} appears in the mode line when the current message is
11103: deleted. In fact, deleting or undeleting a message is nothing more than
11104: adding or removing this attribute. @xref{Rmail Labels}.
11105:
11106: @node Rmail Inbox, Rmail Files, Rmail Deletion, Rmail
11107: @section Rmail Files and Inboxes
11108: @cindex inbox file
11109:
11110: Unix places incoming mail for you in a file that we call your @dfn{inbox}.
11111: When you start up Rmail, it copies the new messages from your inbox into
11112: your primary mail file, an Rmail file, which also contains other messages
11113: saved from previous Rmail sessions. It is in this file that you actually
11114: read the mail with Rmail. This operation is called @dfn{getting new mail}.
11115: It can be repeated at any time using the @kbd{g} key in Rmail. The inbox
11116: file name is @file{/usr/spool/mail/@var{username}} in Berkeley Unix,
11117: @file{/usr/mail/@var{username}} in System V.
11118:
11119: There are two reasons for having separate Rmail files and inboxes.
11120:
11121: @enumerate
11122: @item
11123: The format in which Unix delivers the mail in the inbox is not
11124: adequate for Rmail mail storage. It has no way to record attributes
11125: (such as @samp{deleted}) or user-specified labels; it has no way to record
11126: old headers and reformatted headers; it has no way to record cached
11127: summary line information.
11128:
11129: @item
11130: It is very cumbersome to access an inbox file without danger of losing
11131: mail, because it is necessary to interlock with mail delivery.
11132: Moreover, different Unix systems use different interlocking
11133: techniques. The strategy of moving mail out of the inbox once and for
11134: all into a separate Rmail file avoids the need for interlocking in all
11135: the rest of Rmail, since only Rmail operates on the Rmail file.
11136: @end enumerate
11137:
11138: When getting new mail, Rmail first copies the new mail from the inbox
11139: file to the Rmail file; then it saves the Rmail file; then it deletes the
11140: inbox file. This way, a system crash may cause duplication of mail between
11141: the inbox and the Rmail file, but cannot lose mail.
11142:
11143: Copying mail from an inbox in the system's mailer directory actually puts
11144: it in an intermediate file @file{~/.newmail}. This is because the
11145: interlocking is done by a C program that copies to another file.
11146: @file{~/.newmail} is deleted after mail merging is successful. If there is
11147: a crash at the wrong time, this file will continue to exist and will be
11148: used as an inbox the next time you get new mail.
11149:
11150: @node Rmail Files, Rmail Output, Rmail Inbox, Rmail
11151: @section Multiple Mail Files
11152:
11153: Rmail operates by default on your @dfn{primary mail file}, which is named
11154: @file{~/RMAIL} and receives your incoming mail from your system inbox file.
11155: But you can also have other mail files and edit them with Rmail. These
11156: files can receive mail through their own inboxes, or you can move messages
11157: into them by explicit command in Rmail (@pxref{Rmail Output}).
11158:
11159: @table @kbd
11160: @item i @var{file} @key{RET}
11161: Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
11162:
11163: @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
11164: Specify inbox file names for current Rmail file to get mail from.
11165:
11166: @item g
11167: Merge new mail from current Rmail file's inboxes
11168: (@code{rmail-get-new-mail}).
11169:
11170: @item C-u g @var{file}
11171: Merge new mail from inbox file @var{file}.
11172: @end table
11173:
11174: @kindex i (Rmail)
11175: @findex rmail-input
11176: To run Rmail on a file other than your primary mail file, you may use the
11177: @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file, puts it in
11178: Rmail mode, and then gets new mail from the file's inboxes if any.
11179: You can also use @kbd{M-x rmail-input} even when not in Rmail.
11180:
11181: The file you read with @kbd{i} does not have to be in Rmail file format.
11182: It could also be Unix mail format, or @code{mmdf} format; or it could
11183: be a mixture of all three, as long as each message belongs to one of
11184: the three formats. Rmail recognizes all three and converts all the
11185: messages to proper Rmail format before showing you the file.
11186:
11187: @findex set-rmail-inbox-list
11188: Each Rmail file can contain a list of inbox file names; you can specify
11189: this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
11190: @key{RET}}. The argument can contain any number of file names, separated
11191: by commas. It can also be empty, which specifies that this file should
11192: have no inboxes. Once a list of inboxes is specified, the Rmail file
11193: remembers it permanently until it is explicitly changed.@refill
11194:
11195: @kindex g (Rmail)
11196: @findex rmail-get-new-mail
11197: If an Rmail file has inboxes, new mail is merged in from the inboxes when
11198: the Rmail file is brought into Rmail, and when the @kbd{g} (@code{rmail-get-new-mail})
11199: command is used. If the Rmail file specifies no inboxes, then no new mail
11200: is merged in at these times. A special exception is made for your primary
11201: mail file in using the standard system inbox for it if it does not specify
11202: any.
11203:
11204: To merge mail from a file that is not the usual inbox, give the @kbd{g}
11205: key a numeric argument, as in @kbd{C-u g}. Then it reads a file name and
11206: merges mail from that file. The inbox file is not deleted or changed in
11207: any way when @kbd{g} with an argument is used. This is, therefore, a
11208: general way of merging one file of messages into another.
11209:
11210: @node Rmail Output, Rmail Labels, Rmail Files, Rmail
11211: @section Copying Messages Out to Files
11212:
11213: @table @kbd
11214: @item o @var{file} @key{RET}
11215: Append a copy of the current message to the file @var{file},
11216: writing it in Rmail file format (@code{rmail-output-to-rmail-file}).
11217:
11218: @item C-o @var{file} @key{RET}
11219: Append a copy of the current message to the file @var{file},
11220: writing it in Unix mail file format (@code{rmail-output}).
11221: @end table
11222:
11223: @kindex o (Rmail)
11224: @findex rmail-output-to-rmail-file
11225: @kindex C-o (Rmail)
11226: @findex rmail-output
11227: If an Rmail file has no inboxes, how does it get anything in it? By
11228: explicit @kbd{o} commands.
11229:
11230: @kbd{o} (@code{rmail-output-to-rmail-file}) appends the current message
11231: in Rmail format to the end of the specified file. This is the best command
11232: to use to move messages between Rmail files. If the other Rmail file is
11233: currently visited, the copying is done into the other file's Emacs buffer
11234: instead. You should eventually save it on disk.
11235:
11236: The @kbd{C-o} (@code{rmail-output}) command in Rmail appends a copy of the current
11237: message to a specified file, in Unix mail file format. This is useful for
11238: moving messages into files to be read by other mail processors that do not
11239: understand Rmail format.
11240:
11241: Copying a message with @kbd{o} or @kbd{C-o} gives the original copy of the
11242: message the @samp{filed} attribute, so that @samp{filed} appears in the mode
11243: line when such a message is current.
11244:
11245: Normally you should use only @kbd{o} to output messages to other Rmail
11246: files, never @kbd{C-o}. But it is also safe if you always use @kbd{C-o},
11247: never @kbd{o}. When a file is visited in Rmail, the last message is
11248: checked, and if it is in Unix format, the entire file is scanned and all
11249: Unix-format messages are converted to Rmail format. (The reason for
11250: checking the last message is that scanning the file is slow and most Rmail
11251: files have only Rmail format messages.) If you use @kbd{C-o} consistently,
11252: the last message is sure to be in Unix format, so Rmail will convert all
11253: messages properly.
11254:
11255: The case where you might want to use @kbd{C-o} always, instead of @kbd{o}
11256: always, is when you or other users want to append mail to the same file
11257: from other mail processors. Other mail processors probably do not know
11258: Rmail format but do know Unix format.
11259:
11260: In any case, always use @kbd{o} to add to an Rmail file that is being
11261: visited in Rmail. Adding messages with @kbd{C-o} to the actual disk file
11262: will trigger a ``simultaneous editing'' warning when you ask to save the
11263: Emacs buffer, and will be lost if you do save.
11264:
11265: @node Rmail Labels, Rmail Summary, Rmail Output, Rmail
11266: @section Labels
11267: @cindex label (Rmail)
11268: @cindex attribute (Rmail)
11269:
11270: Each message can have various @dfn{labels} assigned to it as a means of
11271: classification. A label has a name; different names mean different labels.
11272: Any given label is either present or absent on a particular message. A few
11273: label names have standard meanings and are given to messages automatically
11274: by Rmail when appropriate; these special labels are called @dfn{attributes}.
11275: All other labels are assigned by the user.
11276:
11277: @table @kbd
11278: @item a @var{label} @key{RET}
11279: Assign the label @var{label} to the current message (@code{rmail-add-label}).
11280: @item k @var{label} @key{RET}
11281: Remove the label @var{label} from the current message (@code{rmail-kill-label}).
11282: @item C-M-n @var{labels} @key{RET}
11283: Move to the next message that has one of the labels @var{labels}
11284: (@code{rmail-next-labeled-message}).
11285: @item C-M-p @var{labels} @key{RET}
11286: Move to the previous message that has one of the labels @var{labels}
11287: (@code{rmail-previous-labeled-message}).
11288: @item C-M-l @var{labels} @key{RET}
11289: Make a summary of all messages containing any of the labels @var{labels}
11290: (@code{rmail-summary-by-labels}).
11291: @end table
11292:
11293: @noindent
11294: Specifying an empty string for one these commands means to use the last
11295: label specified for any of these commands.
11296:
11297: @kindex a (Rmail)
11298: @kindex k (rmail)
11299: @findex rmail-add-label
11300: @findex rmail-kill-label
11301: The @kbd{a} (@code{rmail-add-label}) and @kbd{k} (@code{rmail-kill-label}) commands allow
11302: you to assign or remove any label on the current message. If the @var{label}
11303: argument is empty, it means to assign or remove the same label most
11304: recently assigned or removed.
11305:
11306: Once you have given messages labels to classify them as you wish, there
11307: are two ways to use the labels: in moving and in summaries.
11308:
11309: @kindex C-M-n (Rmail)
11310: @kindex C-M-p (Rmail)
11311: @findex rmail-next-labeled-message
11312: @findex rmail-previous-labeled-message
11313: The command @kbd{C-M-n @var{labels} @key{RET}}
11314: (@code{rmail-next-labeled-message}) moves to the next message that has one
11315: of the labels @var{labels}. @var{labels} is one or more label names,
11316: separated by commas. @kbd{C-M-p} (@code{rmail-previous-labeled-message})
11317: is similar, but moves backwards to previous messages. A preceding numeric
11318: argument to either one serves as a repeat count.@refill
11319:
11320: @kindex C-M-l (Rmail)
11321: @findex rmail-summary-by-labels
11322: The command @kbd{C-M-l @var{labels} @key{RET}}
11323: (@code{rmail-summary-by-labels}) displays a summary containing only the
11324: messages that have at least one of a specified set of messages. The
11325: argument @var{labels} is one or more label names, separated by commas.
11326: @xref{Rmail Summary}, for information on summaries.@refill
11327:
11328: If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or @kbd{C-M-l} is empty, it means
11329: to use the last set of labels specified for any of these commands.
11330:
11331: Some labels such as @samp{deleted} and @samp{filed} have built-in meanings and
11332: are assigned to or removed from messages automatically at appropriate
11333: times; these labels are called @dfn{attributes}. Here is a list of Rmail
11334: attributes:
11335:
11336: @table @samp
11337: @item unseen
11338: Means the message has never been current. Assigned to messages when
11339: they come from an inbox file, and removed when a message is made
11340: current.
11341: @item deleted
11342: Means the message is deleted. Assigned by deletion commands and
11343: removed by undeletion commands (@pxref{Rmail Deletion}).
11344: @item filed
11345: Means the message has been copied to some other file. Assigned by the
11346: file output commands (@pxref{Rmail Files}).
11347: @item answered
11348: Means you have mailed an answer to the message. Assigned by the @kbd{r}
11349: command (@code{rmail-reply}). @xref{Rmail Reply}.
11350: @item forwarded
11351: Means you have forwarded the message to other users. Assigned by the
11352: @kbd{f} command (@code{rmail-forward}). @xref{Rmail Reply}.
11353: @item edited
11354: Means you have edited the text of the message within Rmail.
11355: @xref{Rmail Editing}.
11356: @end table
11357:
11358: All other labels are assigned or removed only by the user, and it is up
11359: to the user to decide what they mean.
11360:
11361: @node Rmail Summary, Rmail Reply, Rmail Labels, Rmail
11362: @section Summaries
11363: @cindex summary (Rmail)
11364:
11365: A @dfn{summary} is a buffer containing one line per message that Rmail
11366: can make and display to give you an overview of the mail in an Rmail file.
11367: Each line shows the message number, the sender, the labels, and the
11368: subject. When the summary buffer is selected, various commands can be used
11369: to select messages by moving in the summary buffer, or delete or undelete
11370: messages.
11371:
11372: A summary buffer applies to a single Rmail file only; if you are
11373: editing multiple Rmail files, they have separate summary buffers. The
11374: summary buffer name is made by appending @samp{-summary} to the Rmail buffer's
11375: name. Only one summary buffer will be displayed at a time unless you make
11376: several windows and select the summary buffers by hand.
11377:
11378: @menu
11379: * Rmail Make Summary:: Making various sorts of summaries.
11380: * Rmail Summary Edit:: Manipulating messages from the summary.
11381: @end menu
11382:
11383: @node Rmail Make Summary, Rmail Summary Edit, Rmail Summary, Rmail Summary
11384: @subsection Making Summaries
11385:
11386: Here are the commands to create a summary for the current Rmail file.
11387: Summaries do not update automatically; to make an updated summary, you
11388: must use one of these commands again.
11389:
11390: @table @kbd
11391: @item h
11392: @itemx C-M-h
11393: Summarize all messages (@code{rmail-summary}).
11394: @item l @var{labels} @key{RET}
11395: @itemx C-M-l @var{labels} @key{RET}
11396: Summarize message that have one or more of the specified labels
11397: (@code{rmail-summary-by-labels}).
11398: @item C-M-r @var{rcpts} @key{RET}
11399: Summarize messages that have one or more of the specified recipients
11400: (@code{rmail-summary-by-recipients}).
11401: @end table
11402:
11403: @kindex h (Rmail)
11404: @findex rmail-summary
11405: The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
11406: for the current Rmail file with a summary of all the messages in the file.
11407: It then displays and selects the summary buffer in another window.
11408:
11409: @kindex l (Rmail)
11410: @kindex C-M-l (Rmail)
11411: @findex rmail-summary-by-labels
11412: @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
11413: a partial summary mentioning only the messages that have one or more of the
11414: labels @var{labels}. @var{labels} should contain label names separated by
11415: commas.@refill
11416:
11417: @kindex C-M-r (Rmail)
11418: @findex rmail-summary-by-recipients
11419: @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
11420: makes a partial summary mentioning only the messages that have one or more
11421: of the recipients @var{rcpts}. @var{rcpts} should contain mailing
11422: addresses separated by commas.@refill
11423:
11424: Note that there is only one summary buffer for any Rmail file; making one
11425: kind of summary discards any previously made summary.
11426:
11427: @node Rmail Summary Edit,, Rmail Make Summary, Rmail Summary
11428: @subsection Editing in Summaries
11429: @cindex Rmail Summary mode
11430: @cindex summaries in Rmail
11431:
11432: Summary buffers are given the major mode Rmail Summary mode, which
11433: provides the following special commands:
11434:
11435: @table @kbd
11436: @item j
11437: Select the message described by the line that point is on
11438: (@code{rmail-summary-goto-msg}).
11439: @item C-n
11440: Move to next line and select its message in Rmail
11441: (@code{rmail-summary-next-all}).
11442: @item C-p
11443: Move to previous line and select its message
11444: (@code{rmail-summary-previous-all}).
11445: @item n
11446: Move to next line, skipping lines saying `deleted', and select its
11447: message (@code{rmail-summary-next-msg}).
11448: @item p
11449: Move to previous line, skipping lines saying `deleted', and select
11450: its message (@code{rmail-summary-previous-msg}).
11451: @c !!! following generates acceptable underfull hbox
11452: @item d
11453: Delete the current line's message, then do like @kbd{n}
11454: (@code{rmail-summary-delete-forward}).
11455: @item u
11456: Undelete and select this message or the previous deleted message in
11457: the summary (@code{rmail-summary-undelete}).
11458: @item @key{SPC}
11459: Scroll the other window (presumably Rmail) forward
11460: (@code{rmail-summary-scroll-msg-up}).
11461: @item @key{DEL}
11462: Scroll the other window backward (@code{rmail-summary-scroll-msg-down}).
11463: @item x
11464: Kill the summary window (@code{rmail-summary-exit}).
11465: @item q
11466: Exit Rmail (@code{rmail-summary-quit}).
11467: @end table
11468:
11469: @kindex C-n (Rmail summary)
11470: @kindex C-p (Rmail summary)
11471: @findex rmail-summary-next-all
11472: @findex rmail-summary-previous-all
11473: The keys @kbd{C-n} and @kbd{C-p} are modified in Rmail Summary mode so that in
11474: addition to moving point in the summary buffer they also cause the line's
11475: message to become current in the associated Rmail buffer. That buffer is
11476: also made visible in another window if it is not already so.
11477:
11478: @kindex n (Rmail summary)
11479: @kindex p (Rmail summary)
11480: @findex rmail-summary-next-msg
11481: @findex rmail-summary-previous-msg
11482: @kbd{n} and @kbd{p} are similar to @kbd{C-n} and @kbd{C-p}, but skip
11483: lines that say `message deleted'. They are like the @kbd{n} and @kbd{p}
11484: keys of Rmail itself. Note, however, that in a partial summary these
11485: commands move only among the message listed in the summary.@refill
11486:
11487: @kindex j (Rmail summary)
11488: @findex rmail-summary-goto-msg
11489: The other Emacs cursor motion commands are not changed in Rmail Summary
11490: mode, so it is easy to get the point on a line whose message is not
11491: selected in Rmail. This can also happen if you switch to the Rmail window
11492: and switch messages there. To get the Rmail buffer back in sync with the
11493: summary, use the @kbd{j} (@code{rmail-summary-goto-msg}) command, which selects
11494: in Rmail the message of the current summary line.
11495:
11496: @kindex d (Rmail summary)
11497: @kindex u (Rmail summary)
11498: @findex rmail-summary-delete-forward
11499: @findex rmail-summary-undelete
11500: Deletion and undeletion can also be done from the summary buffer. They
11501: always work based on where point is located in the summary buffer, ignoring
11502: which message is selected in Rmail. @kbd{d} (@code{rmail-summary-delete-forward})
11503: deletes the current line's message, then moves to the next line whose
11504: message is not deleted and selects that message. The inverse of this is
11505: @kbd{u} (@code{rmail-summary-undelete}), which moves back (if necessary) to a line
11506: whose message is deleted, undeletes that message, and selects it in Rmail.
11507:
11508: @kindex SPC (Rmail summary)
11509: @kindex DEL (Rmail summary)
11510: @findex rmail-summary-scroll-msg-down
11511: @findex rmail-summary-scroll-msg-up
11512: When moving through messages with the summary buffer, it is convenient to
11513: be able to scroll the message while remaining in the summary window.
11514: The commands @key{SPC} (@code{rmail-summary-scroll-msg-up}) and @key{DEL}
11515: (@code{rmail-summary-scroll-msg-down}) do this. They scroll the message just
11516: as those same keys do when the Rmail buffer is selected.@refill
11517:
11518: @kindex x (Rmail summary)
11519: @findex rmail-summary-exit
11520: When you are finished using the summary, type @kbd{x} (@code{rmail-summary-exit})
11521: to kill the summary buffer's window.
11522:
11523: @kindex q (Rmail summary)
11524: @findex rmail-summary-quit
11525: You can also exit Rmail while in the summary. @kbd{q} (@code{rmail-summary-quit})
11526: kills the summary window, then saves the Rmail file and switches to another
11527: buffer.
11528:
11529: @node Rmail Reply, Rmail Editing, Rmail Summary, Rmail
11530: @section Sending Replies
11531:
11532: Rmail has several commands that use Mail mode to send outgoing mail.
11533: @xref{Sending Mail}, for information on using Mail mode. What are
11534: documented here are the special commands of Rmail for entering Mail mode.
11535: Note that the usual keys for sending mail, @kbd{C-x m} and @kbd{C-x 4 m},
11536: are available in Rmail mode and work just as they usually do.@refill
11537:
11538: @table @kbd
11539: @item m
11540: Send a message (@code{rmail-mail}).
11541: @c !!! following generates acceptable underfull hbox
11542: @item c
11543: Continue editing already started outgoing message (@code{rmail-continue}).
11544: @item r
11545: Send a reply to the current Rmail message (@code{rmail-reply}).
11546: @item f
11547: Forward current message to other users (@code{rmail-forward}).
11548: @end table
11549:
11550: @kindex r (Rmail)
11551: @findex rmail-reply
11552: @vindex rmail-dont-reply-to
11553: @cindex reply to a message
11554: The most common reason to send a message while in Rmail is to reply to
11555: the message you are reading. To do this, type @kbd{r}
11556: (@code{rmail-reply}). This displays the @samp{*mail*} buffer in another
11557: window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject},
11558: @samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the
11559: message being replied to. The @samp{To} field is given the sender of that
11560: message, and the @samp{CC} gets all the recipients of that message (but
11561: recipients that match elements of the list @code{rmail-dont-reply-to} are
11562: omitted; by default, this list contains your own mailing address).@refill
11563:
11564: If you don't want to include the other recipients in the @samp{cc} field,
11565: you can use a prefix argument to the @kbd{r} command. In Rmail, you can
11566: do this with @w{@kbd{1 r}}.
11567:
11568: Once you have initialized the @samp{*mail*} buffer this way, sending the
11569: mail goes as usual (@pxref{Sending Mail}). You can edit the presupplied
11570: header fields if they are not right for you.
11571:
11572: @kindex C-c C-y (Mail mode)
11573: @findex mail-yank-original
11574: One additional Mail mode command is available when mailing is invoked
11575: from Rmail: @kbd{C-c C-y} (@code{mail-yank-original}) inserts into the outgoing
11576: message a copy of the current Rmail message; normally this is the message
11577: you are replying to, but you can also switch to the Rmail buffer, select a
11578: different message, switch back, and yank new current message. Normally the
11579: yanked message is indented four spaces and has most header fields deleted
11580: from it; an argument to @kbd{C-c C-y} specifies the amount to indent, and
11581: @kbd{C-u C-c C-y} does not indent at all and does not delete any header
11582: fields.@refill
11583:
11584: @kindex f (Rmail)
11585: @findex rmail-forward
11586: @cindex forward a message
11587: Another frequent reason to send mail in Rmail is to forward the current
11588: message to other users. @kbd{f} (@code{rmail-forward}) makes this easy by
11589: preinitializing the @samp{*mail*} buffer with the current message as the
11590: text, and a subject designating a forwarded message. All you have to do is
11591: fill in the recipients and send.@refill
11592:
11593: @kindex m (Rmail)
11594: @findex rmail-mail
11595: The @kbd{m} (@code{rmail-mail}) command is used to start editing an
11596: outgoing message that is not a reply. It leaves the header fields empty.
11597: Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
11598: accessible for @kbd{C-c y}, just as @kbd{r} does. Thus, @kbd{m} can be
11599: used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
11600: can do.@refill
11601:
11602: @kindex c (Rmail)
11603: @findex rmail-continue
11604: The @kbd{c} (@code{rmail-continue}) command resumes editing the
11605: @samp{*mail*} buffer, to finish editing an outgoing message you were
11606: already composing, or to alter a message you have sent.@refill
11607:
11608: @node Rmail Editing, Rmail Digest, Rmail Reply, Rmail
11609: @section Editing Within a Message
11610:
11611: Rmail mode provides a few special commands for moving within and editing
11612: the current message. In addition, the usual Emacs commands are available
11613: (except for a few, such as @kbd{C-M-n} and @kbd{C-M-h}, that are redefined by Rmail for
11614: other purposes). However, the Rmail buffer is normally read-only, and to
11615: alter it you must use the Rmail command @kbd{w} described below.
11616:
11617: @table @kbd
11618: @item t
11619: Toggle display of original headers (@code{rmail-toggle-headers}).
11620: @item w
11621: Edit current message (@code{rmail-edit-current-message}).
11622: @end table
11623:
11624: @kindex t (Rmail)
11625: @findex rmail-toggle-header
11626: @vindex rmail-ignored-headers
11627: Rmail reformats the header of each message before displaying it.
11628: Normally this involves deleting most header fields, on the grounds that
11629: they are not interesting. The variable @code{rmail-ignored-headers} should
11630: contain a regexp that matches the header fields to discard in this way.
11631: The original headers are saved permanently, and to see what they look like,
11632: use the @kbd{t} (@code{rmail-toggle-headers}) command. This discards the reformatted
11633: headers of the current message and displays it with the original headers.
11634: Repeating @kbd{t} reformats the message again. Selecting the message again
11635: also reformats.
11636:
11637: @kindex w (Rmail)
11638: @findex rmail-edit-current-message
11639: The Rmail buffer is normally read-only, and most of the characters you
11640: would type to modify it (including most letters) are redefined as Rmail
11641: commands. This is usually not a problem since it is rare to want to change
11642: the text of a message. When you do want to do this, the way is to type
11643: @kbd{w} (@code{rmail-edit-current-message}), which changes from Rmail mode into
11644: Rmail Edit mode, another major mode which is nearly the same as Text mode.
11645: The mode line illustrates this change.
11646:
11647: In Rmail Edit mode, letters insert themselves as usual and the Rmail
11648: commands are not available. When you are finished editing the message and
11649: are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to
11650: Rmail mode. Alternatively, you can return to Rmail mode but cancel all the
11651: editing that you have done by typing @kbd{C-c C-]}.
11652:
11653: @vindex rmail-edit-mode-hook
11654: Entering Rmail Edit mode calls with no arguments the value of the variable
11655: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
11656: does the same with the variable @code{rmail-edit-mode-hook}. It adds the
11657: attribute @samp{edited} to the message.
11658:
11659: @node Rmail Digest,, Rmail Editing, Rmail
11660: @section Digest Messages
11661: @cindex digest message
11662: @cindex undigestify
11663:
11664: A @dfn{digest message} is a message which exists to contain and carry
11665: several other messages. Digests are used on moderated mailing lists; all
11666: the messages that arrive for the list during a period of time such as one
11667: day are put inside a single digest which is then sent to the subscribers.
11668: Transmitting the single digest uses much less computer time than
11669: transmitting the individual messages even though the total size is the
11670: same, because the per-message overhead in network mail transmission is
11671: considerable.
11672:
11673: @findex undigestify-rmail-message
11674: When you receive a digest message, the most convenient way to read it is
11675: to @dfn{undigestify} it: to turn it back into many individual messages.
11676: Then you can read and delete the individual messages as it suits you.
11677:
11678: To undigestify a message, select it and then type @kbd{M-x
11679: undigestify-rmail-message}. This copies each submessage as a separate
11680: Rmail message and inserts them all following the digest. The digest
11681: message itself is flagged as deleted.
11682:
11683: @iftex
11684: @chapter Miscellaneous Commands
11685:
11686: This chapter contains several brief topics that do not fit anywhere else.
11687:
11688: @end iftex
11689: @node Recursive Edit, Narrowing, Rmail, Top
11690: @section Recursive Editing Levels
11691: @cindex recursive editing level
11692: @cindex editing level, recursive
11693:
11694: A @dfn{recursive edit} is a situation in which you are using Emacs
11695: commands to perform arbitrary editing while in the middle of another Emacs
11696: command. For example, when you type @kbd{C-r} inside of a @code{query-replace},
11697: you enter a recursive edit in which you can change the current buffer. On
11698: exiting from the recursive edit, you go back to the @code{query-replace}.
11699:
11700: @kindex C-M-c
11701: @findex exit-recursive-edit
11702: @cindex exiting
11703: @dfn{Exiting} the recursive edit means returning to the unfinished
11704: command, which continues execution. For example, exiting the recursive
11705: edit requested by @kbd{C-r} in @code{query-replace} causes query replacing
11706: to resume. Exiting is done with @kbd{C-M-c} (@code{exit-recursive-edit}).
11707:
11708: @kindex C-]
11709: @findex abort-recursive-edit
11710: You can also @dfn{abort} the recursive edit. This is like exiting, but
11711: also quits the unfinished command immediately. Use the command @kbd{C-]}
11712: (@code{abort-recursive-edit}) for this. @xref{Quitting}.
11713:
11714: The mode line shows you when you are in a recursive edit by displaying
11715: square brackets around the parentheses that always surround the major and
11716: minor mode names. Every window's mode line shows this, in the same way,
11717: since being in a recursive edit is true of Emacs as a whole rather than
11718: any particular buffer.
11719:
11720: @findex top-level
11721: It is possible to be in recursive edits within recursive edits. For
11722: example, after typing @kbd{C-r} in a @code{query-replace}, you might type a
11723: command that entered the debugger. In such circumstances, two or more sets
11724: of square brackets appear in the mode line. Exiting the inner recursive
11725: edit (such as, with the debugger @kbd{c} command) would resume the command
11726: where it called the debugger. After the end of this command, you would be
11727: able to exit the first recursive edit. Aborting also gets out of only one
11728: level of recursive edit; it returns immediately to the command level of the
11729: previous recursive edit. So you could immediately abort that one too.
11730:
11731: Alternatively, the command @kbd{M-x top-level} aborts all levels of
11732: recursive edits, returning immediately to the top level command reader.
11733:
11734: The text being edited inside the recursive edit need not be the same text
11735: that you were editing at top level. It depends on what the recursive edit
11736: is for. If the command that invokes the recursive edit selects a different
11737: buffer first, that is the buffer you will edit recursively. In any case,
11738: you can switch buffers within the recursive edit in the normal manner (as
11739: long as the buffer-switching keys have not been rebound). You could
11740: probably do all the rest of your editing inside the recursive edit,
11741: visiting files and all. But this could have surprising effects (such as
11742: stack overflow) from time to time. So remember to exit or abort the
11743: recursive edit when you no longer need it.
11744:
11745: In general, GNU Emacs tries to avoid using recursive edits. It is
11746: usually preferable to allow the user to switch among the possible editing
11747: modes in any order he likes. With recursive edits, the only way to get to
11748: another state is to go ``back'' to the state that the recursive edit was
11749: invoked from.
11750:
11751: @node Narrowing, Sorting, Recursive Edit, Top
11752: @section Narrowing
11753: @cindex widening
11754: @cindex restriction
11755: @cindex narrowing
11756:
11757: @dfn{Narrowing} means focusing in on some portion of the buffer, making
11758: the rest temporarily invisible and inaccessible. Cancelling the narrowing,
11759: and making the entire buffer once again visible, is called @dfn{widening}.
11760: The amount of narrowing in effect in a buffer at any time is called the
11761: buffer's @dfn{restriction}.
11762:
11763: @c WideCommands
11764: @table @kbd
11765: @item C-x n
11766: Narrow down to between point and mark (@code{narrow-to-region}).
11767: @item C-x w
11768: Widen to make the entire buffer visible again (@code{widen}).
11769: @end table
11770:
11771: When you have narrowed down to a part of the buffer, that part appears to
11772: be all there is. You can't see the rest, you can't move into it (motion
11773: commands won't go outside the visible part), you can't change it in any
11774: way. However, it is not gone, and if you save the file all the invisible
11775: text will be saved. In addition to sometimes making it easier to
11776: concentrate on a single subroutine or paragraph by eliminating clutter,
11777: narrowing can be used to restrict the range of operation of a replace
11778: command or repeating keyboard macro. The word @samp{Narrow} appears in the
11779: mode line whenever narrowing is in effect.
11780:
11781: @kindex C-x n
11782: @findex narrow-to-region
11783: The primary narrowing command is @kbd{C-x n} (@code{narrow-to-region}).
11784: It sets the current buffer's restrictions so that the text in the current
11785: region remains visible but all text before the region or after the region
11786: is invisible. Point and mark do not change.
11787:
11788: Because narrowing can easily confuse users who do not understand it,
11789: @code{narrow-to-region} is normally a disabled command. Attempting to use
11790: this command asks for confirmation and gives you the option of enabling it;
11791: once you enable the command, confirmation will no longer be required for
11792: it. @xref{Disabling}.
11793:
11794: @kindex C-x w
11795: @findex widen
11796: The way to undo narrowing is to widen with @kbd{C-x w} (@code{widen}).
11797: This makes all text in the buffer accessible again.
11798:
11799: You can get information on what part of the buffer you are narrowed down
11800: to using the @kbd{C-x =} command. @xref{Position Info}.
11801:
11802: @node Sorting, Shell, Narrowing, Top
11803: @section Sorting Text
11804: @cindex sorting
11805:
11806: Emacs provides several commands for sorting text in the buffer. All
11807: operate on the contents of the region (the text between point and the
11808: mark). They divide the text of the region into many @dfn{sort records},
11809: identify a @dfn{sort key} for each record, and then reorder the records
11810: into the order determined by the sort keys. The records are ordered so
11811: that their keys are in alphabetical order, or, for numeric sorting, in
11812: numeric order. In alphabetic sorting, all upper case letters `A' through
11813: `Z' come before lower case `a', in accord with the @sc{ascii} character
11814: sequence.
11815:
11816: The various sort commands differ in how they divide the text into sort
11817: records and in which part of each record is used as the sort key. Most of
11818: the commands make each line a separate sort record, but some commands use
11819: paragraphs or pages as sort records. Most of the sort commands use each
11820: entire sort record as its own sort key, but some use only a portion of the
11821: record as the sort key.
11822:
11823: @findex sort-lines
11824: @findex sort-paragraphs
11825: @findex sort-pages
11826: @findex sort-fields
11827: @findex sort-numeric-fields
11828: @table @kbd
11829: @item M-x sort-lines
11830: Divide the region into lines, and sort by comparing the entire
11831: text of a line. A prefix argument means sort into descending order.
11832:
11833: @item M-x sort-paragraphs
11834: Divide the region into paragraphs, and sort by comparing the entire
11835: text of a paragraph (except for leading blank lines). A prefix
11836: argument means sort into descending order.
11837:
11838: @item M-x sort-pages
11839: Divide the region into pages, and sort by comparing the entire
11840: text of a page (except for leading blank lines). A prefix
11841: argument means sort into descending order.
11842:
11843: @item M-x sort-fields
11844: Divide the region into lines, and sort by comparing the contents of
11845: one field in each line. Fields are defined as separated by
11846: whitespace, so the first run of consecutive non-whitespace characters
11847: in a line constitutes field 1, the second such run constitutes field
11848: 2, etc.
11849:
11850: You specify which field to sort by with a numeric argument: 1 to sort
11851: by field 1, etc. A negative argument means sort into descending
11852: order. Thus, minus 2 means sort by field 2 in reverse-alphabetical
11853: order.
11854:
11855: If two lines are equal in the field being compared, their relative order
11856: in the text is not changed. This enables you to sort by multiple keys:
11857: sort first by the least significant key, then by the next-to-least
11858: key, and so on, ending with the most important key.
11859:
11860: @item M-x sort-numeric-fields
11861: Like @kbd{M-x sort-fields} except the specified field is converted
11862: to a number for each line, and the numbers are compared. @samp{10}
11863: comes before @samp{2} when considered as text, but after it when
11864: considered as a number.
11865:
11866: @item M-x sort-columns
11867: Like @kbd{M-x sort-fields} except that the text within each line
11868: used for comparison comes from a fixed range of columns. See below
11869: for an explanation.
11870: @end table
11871:
11872: For example, if the buffer contains
11873:
11874: @smallexample
11875: On systems where clash detection (locking of files being edited) is
11876: implemented, Emacs also checks the first time you modify a buffer
11877: whether the file has changed on disk since it was last visited or
11878: saved. If it has, you are asked to confirm that you want to change
11879: the buffer.
11880: @end smallexample
11881:
11882: @noindent
11883: then if you apply @kbd{M-x sort-lines} to the entire buffer you get
11884:
11885: @smallexample
11886: On systems where clash detection (locking of files being edited) is
11887: implemented, Emacs also checks the first time you modify a buffer
11888: saved. If it has, you are asked to confirm that you want to change
11889: the buffer.
11890: whether the file has changed on disk since it was last visited or
11891: @end smallexample
11892:
11893: @noindent
11894: where the upper case `O' comes before all lower case letters. If you apply
11895: instead @kbd{C-u 2 M-x sort-fields} you get
11896:
11897: @smallexample
11898: implemented, Emacs also checks the first time you modify a buffer
11899: saved. If it has, you are asked to confirm that you want to change
11900: the buffer.
11901: On systems where clash detection (locking of files being edited) is
11902: whether the file has changed on disk since it was last visited or
11903: @end smallexample
11904:
11905: @noindent
11906: where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer},
11907: @samp{systems} and @samp{the}.@refill
11908:
11909: @findex sort-columns
11910: @kbd{M-x sort-columns} requires more explanation. You specify the
11911: columns by putting point at one of the columns and the mark at the other
11912: column. Because this means you cannot put point or the mark at the
11913: beginning of the first line to sort, this command uses an unusual
11914: definition of `region': all of the line point is in is considered part of
11915: the region, and so is all of the line the mark is in.
11916:
11917: For example, to sort a table by information found in columns 10 to 15,
11918: you could put the mark on column 10 in the first line of the table, and
11919: point on column 15 in the last line of the table, and then use this command.
11920: Or you could put the mark on column 15 in the first line and point on
11921: column 10 in the last line.
11922:
11923: This can be thought of as sorting the rectangle specified by point and
11924: the mark, except that the text on each line to the left or right of the
11925: rectangle moves along with the text inside the rectangle.
11926: @xref{Rectangles}.
11927:
11928: @node Shell, Hardcopy, Sorting, Top
11929: @section Running Shell Commands from Emacs
11930: @cindex subshell
11931: @cindex shell commands
11932:
11933: Emacs has commands for passing single command lines to inferior shell
11934: processes; it can also run a shell interactively with input and output to
11935: an Emacs buffer @samp{*shell*}.
11936:
11937: @table @kbd
11938: @item M-!
11939: Run a specified shell command line and display the output
11940: (@code{shell-command}).
11941: @item M-|
11942: Run a specified shell command line with region contents as input;
11943: optionally replace the region with the output
11944: (@code{shell-command-on-region}).
11945: @item M-x shell
11946: Run a subshell with input and output through an Emacs buffer.
11947: You can then give commands interactively.
11948: @end table
11949:
11950: @menu
11951: * Single Shell:: How to run one shell command and return.
11952: * Interactive Shell:: Permanent shell taking input via Emacs.
11953: * Shell Mode:: Special Emacs commands used with permanent shell.
11954: @end menu
11955:
11956: @node Single Shell, Interactive Shell, Shell, Shell
11957: @subsection Single Shell Commands
11958:
11959: @kindex M-!
11960: @findex shell-command
11961: @kbd{M-!} (@code{shell-command}) reads a line of text using the
11962: minibuffer and creates an inferior shell to execute the line as a command.
11963: Standard input from the command comes from the null device. If the shell
11964: command produces any output, the output goes into an Emacs buffer named
11965: @samp{*Shell Command Output*}, which is displayed in another window but not
11966: selected. A numeric argument, as in @kbd{M-1 M-!}, directs this command to
11967: insert any output into the current buffer. In that case, point is left
11968: before the output and the mark is set after the output.
11969:
11970: @kindex M-|
11971: @findex shell-command-on-region
11972: @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but passes
11973: the contents of the region as input to the shell command, instead of no
11974: input. If a numeric argument is used, meaning insert output in the current
11975: buffer, then the old region is deleted first and the output replaces it as
11976: the contents of the region.@refill
11977:
11978: @vindex shell-file-name
11979: @cindex environment
11980: Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
11981: shell to use. This variable is initialized based on your @code{SHELL}
11982: environment variable when Emacs is started. If the file name does not
11983: specify a directory, the directories in the list @code{exec-path} are
11984: searched; this list is initialized based on the environment variable
11985: @code{PATH} when Emacs is started. Your @file{.emacs} file can override
11986: either or both of these default initializations.@refill
11987:
11988: With @kbd{M-!} and @kbd{M-|}, Emacs has to wait until the shell command
11989: completes. You can quit with @kbd{C-g}; that terminates the shell command.
11990:
11991: @node Interactive Shell, Shell Mode, Single Shell, Shell
11992: @subsection Interactive Inferior Shell
11993:
11994: @findex shell
11995: To run a subshell interactively, putting its typescript in an Emacs
11996: buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named
11997: @samp{*shell*} and runs a subshell with input coming from and output going
11998: to that buffer. That is to say, any ``terminal output'' from the subshell
11999: will go into the buffer, advancing point, and any ``terminal input'' for
12000: the subshell comes from text in the buffer. To give input to the subshell,
12001: go to the end of the buffer and type the input, terminated by @key{RET}.
12002:
12003: Emacs does not wait for the subshell to do anything. You can switch
12004: windows or buffers and edit them while the shell is waiting, or while it is
12005: running a command. Output from the subshell waits until Emacs has time to
12006: process it; this happens whenever Emacs is waiting for keyboard input or
12007: for time to elapse.
12008:
12009: If you would like multiple subshells, change the name of buffer
12010: @samp{*shell*} to something different by using @kbd{M-x rename-buffer}. The
12011: next use of @kbd{M-x shell} will create a new buffer @samp{*shell*} with
12012: its own subshell. By renaming this buffer as well you can create a third
12013: one, and so on. All the subshells run independently and in parallel.
12014:
12015: @vindex explicit-shell-file-name
12016: The file name used to load the subshell is the value of the variable
12017: @code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise, the
12018: environment variable @code{ESHELL} is used, or the environment variable
12019: @code{SHELL} if there is no @code{ESHELL}. If the file name specified
12020: is relative, the directories in the list @code{exec-path} are searched
12021: (@pxref{Single Shell,Single Shell Commands}).@refill
12022:
12023: As soon as the subshell is started, it is sent as input the contents of
12024: the file @file{~/.emacs_@var{shellname}}, if that file exists, where
12025: @var{shellname} is the name of the file that the shell was loaded
12026: from. For example, if you use @code{csh}, the file sent to it is
12027: @file{~/.emacs_csh}; if you use the Bourne-Again shell, the file sent
12028: to it is @file{~/.emacs_bash}.@refill
12029:
12030: @vindex shell-pushd-regexp
12031: @vindex shell-popd-regexp
12032: @vindex shell-cd-regexp
12033: @code{cd}, @code{pushd} and @code{popd} commands given to the inferior
12034: shell are watched by Emacs so it can keep the @samp{*shell*} buffer's
12035: default directory the same as the shell's working directory. These
12036: commands are recognized syntactically by examining lines of input that are
12037: sent. If you use aliases for these commands, you can tell Emacs to
12038: recognize them also. For example, if the value of the variable
12039: @code{shell-pushd-regexp} matches the beginning of a shell command line,
12040: that line is regarded as a @code{pushd} command. Change this variable when
12041: you add aliases for @samp{pushd}. Likewise, @code{shell-popd-regexp} and
12042: @code{shell-cd-regexp} are used to recognize commands with the meaning of
12043: @samp{popd} and @samp{cd}. These commands are recognized only at the
12044: beginning of a shell command line.@refill
12045:
12046: @vindex shell-set-directory-error-hook
12047: If Emacs gets an error while trying to handle what it believes is
12048: a @samp{cd}, @samp{pushd} or @samp{popd} command, and the value of
12049: @code{shell-set-directory-error-hook} is non-@code{nil}, that value is
12050: called as a function with no arguments.@refill
12051:
12052: @node Shell Mode,, Interactive Shell, Shell
12053: @subsection Shell Mode
12054:
12055: @cindex Shell mode
12056: The shell buffer uses Shell mode, which defines several special keys
12057: attached to the @kbd{C-c} prefix. They are chosen to resemble the usual
12058: editing and job control characters present in shells that are not under
12059: Emacs, except that you must type @kbd{C-c} first. Here is a complete list
12060: of the special key bindings of Shell mode:
12061:
12062: @kindex RET (Shell mode)
12063: @kindex C-c C-d (Shell mode)
12064: @kindex C-c C-u (Shell mode)
12065: @kindex C-c C-w (Shell mode)
12066: @kindex C-c C-c (Shell mode)
12067: @kindex C-c C-z (Shell mode)
12068: @kindex C-c C-\ (Shell mode)
12069: @kindex C-c C-o (Shell mode)
12070: @kindex C-c C-r (Shell mode)
12071: @kindex C-c C-y (Shell mode)
12072: @findex send-shell-input
12073: @findex shell-send-eof
12074: @findex interrupt-shell-subjob
12075: @findex stop-shell-subjob
12076: @findex quit-shell-subjob
12077: @findex kill-output-from-shell
12078: @findex show-output-from-shell
12079: @findex copy-last-shell-input
12080: @vindex shell-prompt-pattern
12081: @table @kbd
12082: @item @key{RET}
12083: At end of buffer, send line as input; otherwise, copy current line to end of
12084: buffer and send it (@code{send-shell-input}). When a line is copied, any
12085: text at the beginning of the line that matches the variable
12086: @code{shell-prompt-pattern} is left out; this variable's value should be a
12087: regexp string that matches the prompts that you use in your subshell.
12088: @item C-c C-d
12089: Send end-of-file as input, probably causing the shell or its current
12090: subjob to finish (@code{shell-send-eof}).
12091: @item C-c C-u
12092: Kill all text that has yet to be sent as input (@code{kill-shell-input}).
12093: @item C-c C-w
12094: Kill a word before point (@code{backward-kill-word}).
12095: @item C-c C-c
12096: Interrupt the shell or its current subjob if any
12097: (@code{interrupt-shell-subjob}).
12098: @item C-c C-z
12099: Stop the shell or its current subjob if any (@code{stop-shell-subjob}).
12100: @item C-c C-\
12101: Send quit signal to the shell or its current subjob if any
12102: (@code{quit-shell-subjob}).
12103: @item C-c C-o
12104: Delete last batch of output from shell (@code{kill-output-from-shell}).
12105: @item C-c C-r
12106: Scroll top of last batch of output to top of window
12107: (@code{show-output-from-shell}).
12108: @item C-c C-y
12109: Copy the previous bunch of shell input, and insert it into the
12110: buffer before point (@code{copy-last-shell-input}). No final newline
12111: is inserted, and the input copied is not resubmitted until you type
12112: @key{RET}.
12113: @end table
12114:
12115: @node Hardcopy, Dissociated Press, Shell, Top
12116: @section Hardcopy Output
12117: @cindex hardcopy
12118:
12119: The Emacs commands for making hardcopy derive their names from the
12120: Unix commands @samp{print} and @samp{lpr}.
12121:
12122: @table @kbd
12123: @item M-x print-buffer
12124: Print hardcopy of current buffer using Unix command @samp{print}
12125: (@samp{lpr -p}). This makes page headings containing the file name
12126: and page number.
12127: @item M-x lpr-buffer
12128: Print hardcopy of current buffer using Unix command @samp{lpr}.
12129: This makes no page headings.
12130: @item M-x print-region
12131: Like @code{print-buffer} but prints only the current region.
12132: @item M-x lpr-region
12133: Like @code{lpr-buffer} but prints only the current region.
12134: @end table
12135:
12136: @findex print-buffer
12137: @findex print-region
12138: @findex lpr-buffer
12139: @findex lpr-region
12140: @vindex lpr-switches
12141: @vindex lpr-command
12142: All the hardcopy commands pass extra switches to the @code{lpr}
12143: program based on the value of the variable @code{lpr-switches}. Its
12144: value should be a list of strings, each string a switch starting with
12145: @samp{-}. For example, the value could be @w{@code{("-Pfoo")}} to print on
12146: printer @samp{foo}. You can specify an alternative command to run
12147: instead of @code{lpr} by setting the variable @code{lpr-command}.
12148:
12149: @node Dissociated Press, Amusements, Hardcopy, Top
12150: @section Dissociated Press
12151:
12152: @findex dissociated-press
12153: @kbd{M-x dissociated-press} is a command for scrambling a file of text
12154: either word by word or character by character. Starting from a buffer of
12155: straight English, it produces extremely amusing output. The input comes
12156: from the current Emacs buffer. Dissociated Press writes its output in a
12157: buffer named @samp{*Dissociation*}, and redisplays that buffer after every
12158: couple of lines (approximately) to facilitate reading it.
12159:
12160: @code{dissociated-press} asks every so often whether to continue
12161: operating. Answer @kbd{n} to stop it. You can also stop at any time by
12162: typing @kbd{C-g}. The dissociation output remains in the @samp{*Dissociation*}
12163: buffer for you to copy elsewhere if you wish.
12164:
12165: @cindex presidentagon
12166: Dissociated Press operates by jumping at random from one point in the
12167: buffer to another. In order to produce plausible output rather than
12168: gibberish, it insists on a certain amount of overlap between the end of one
12169: run of consecutive words or characters and the start of the next. That is,
12170: if it has just printed out `president' and then decides to jump to a
12171: different point in the file, it might spot the `ent' in `pentagon' and
12172: continue from there, producing `presidentagon'. Long sample texts produce
12173: the best results.
12174:
12175: @cindex againformation
12176: A positive argument to @kbd{M-x dissociated-press} tells it to operate
12177: character by character, and specifies the number of overlap characters. A
12178: negative argument tells it to operate word by word and specifies the number
12179: of overlap words. In this mode, whole words are treated as the elements to
12180: be permuted, rather than characters. No argument is equivalent to an
12181: argument of two. For your againformation, the output goes only into the
12182: buffer @samp{*Dissociation*}. The buffer you start with is not changed.
12183:
12184: @cindex Markov chain
12185: @cindex ignoriginal
12186: @cindex techniquitous
12187: Dissociated Press produces nearly the same results as a Markov chain
12188: based on a frequency table constructed from the sample text. It is,
12189: however, an independent, ignoriginal invention. Dissociated Press
12190: techniquitously copies several consecutive characters from the sample
12191: between random choices, whereas a Markov chain would choose randomly for
12192: each word or character. This makes for more plausible sounding results,
12193: and runs faster.
12194:
12195: @cindex outragedy
12196: @cindex buggestion
12197: @cindex properbose
12198: It is a mustatement that too much use of Dissociated Press can be a
12199: developediment to your real work. Sometimes to the point of outragedy.
12200: And keep dissociwords out of your documentation, if you want it to be well
12201: userenced and properbose. Have fun. Your buggestions are welcome.
12202:
12203: @node Amusements, Emulation, Dissociated Press, Top
12204: @section Other Amusements
12205: @cindex boredom
12206: @findex hanoi
12207: @findex yow
12208:
12209: If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are
12210: considerably bored, give it a numeric argument. If you are very very
12211: bored, try an argument of 9. Sit back and watch.
12212:
12213: When you are frustrated, try the famous Eliza program. Just do
12214: @kbd{M-x doctor}. End each input by typing @kbd{RET} twice.
12215:
12216: When you are feeling strange, type @kbd{M-x yow}.
12217:
12218: @node Emulation, Customization, Amusements, Top
12219: @section Emulation
12220: @cindex other editors
12221: @cindex EDT
12222: @cindex vi
12223:
12224: GNU Emacs can be programmed to emulate (more or less) most other
12225: editors. Standard facilities can emulate these:
12226:
12227: @table @asis
12228: @item EDT (DEC VMS editor)
12229: @findex edt-emulation-on
12230: @findex edt-emulation-off
12231: Turn on EDT emulation with @kbd{M-x edt-emulation-on}. @kbd{M-x
12232: edt-emulation-off} restores normal Emacs command bindings.
12233:
12234: Most of the EDT emulation commands are keypad keys, and most standard
12235: Emacs key bindings are still available. The EDT emulation rebindings
12236: are done in the global keymap, so there is no problem switching
12237: buffers or major modes while in EDT emulation.
12238:
12239: @item Gosling Emacs
12240: @findex set-gosmacs-bindings
12241: @findex set-gnu-bindings
12242: Turn on emulation of Gosling Emacs (aka Unipress Emacs) with @kbd{M-x
12243: set-gosmacs-bindings}. This redefines many keys, mostly on the
12244: @kbd{C-x} and @kbd{ESC} prefixes, to work as they do in Gosmacs.
12245: @kbd{M-x set-gnu-bindings} returns to normal GNU Emacs by rebinding
12246: the same keys to the definitions they had at the time @kbd{M-x
12247: set-gosmacs-bindings} was done.
12248:
12249: It is also possible to run Mocklisp code written for Gosling Emacs.
12250: @xref{Mocklisp}.
12251:
12252: @item vi (Berkeley Unix editor)
12253: @findex vi-mode
12254: @cindex VI mode
12255: Turn on vi emulation with @kbd{M-x vi-mode}. This is a major mode
12256: that replaces the previously established major mode. All of the
12257: vi commands that, in real vi, enter ``input'' mode are programmed
12258: in the Emacs emulator to return to the previous major mode. Thus,
12259: ordinary Emacs serves as vi's ``input'' mode.
12260:
12261: Because vi emulation works through major modes, it does not work
12262: to switch buffers during emulation. Return to normal Emacs first.
12263:
12264: If you plan to use vi emulation much, you probably want to bind a key
12265: to the @code{vi-mode} command.
12266:
12267: @item vi (alternate emulator)
12268: @findex vip-mode
12269: Another vi emulator said to resemble real vi more thoroughly is
12270: invoked by @kbd{M-x vip-mode}. ``Input'' mode in this emulator is
12271: changed from ordinary Emacs so you can use @key{ESC} to go back to
12272: emulated vi command mode. To get from emulated vi command mode back
12273: to ordinary Emacs, type @kbd{C-z}.
12274:
12275: This emulation does not work through major modes, and it is possible
12276: to switch buffers in various ways within the emulator. It is not
12277: so necessary to assign a key to the command @code{vip-mode} as
12278: it is with @code{vi-mode} because terminating insert mode does
12279: not use it.
12280:
12281: For full information, see the long comment at the beginning of the
12282: source file, which is @file{lisp/vip.el} in the Emacs distribution.
12283: @end table
12284:
12285: I am interested in hearing which vi emulator users prefer, as well as in
12286: receiving more complete user documentation for either or both emulators.
12287: Warning: loading both at once may cause name conficts; no one has checked.
12288:
12289: @node Customization, Quitting, Emulation, Top
12290: @chapter Customization
12291: @cindex customization
12292:
12293: This chapter talks about various topics relevant to adapting the
12294: behavior of Emacs in minor ways.
12295:
12296: All kinds of customization affect only the particular Emacs job that you
12297: do them in. They are completely lost when you kill the Emacs job, and have
12298: no effect on other Emacs jobs you may run at the same time or later. The
12299: only way an Emacs job can affect anything outside of it is by writing a
12300: file; in particular, the only way to make a customization `permanent' is to
12301: put something in your @file{.emacs} file or other appropriate file to do the
12302: customization in each session. @xref{Init File}.
12303:
12304: @menu
12305: * Minor Modes:: Each minor mode is one feature you can turn on
12306: independently of any others.
12307: * Variables:: Many Emacs commands examine Emacs variables
12308: to decide what to do; by setting variables,
12309: you can control their functioning.
12310: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
12311: to be replayed with a single command.
12312: * Key Bindings:: The keymaps say what command each key runs.
12313: By changing them, you can "redefine keys".
12314: * Syntax:: The syntax table controls how words and expressions
12315: are parsed.
12316: * Init File:: How to write common customizations in the @file{.emacs} file.
12317: @end menu
12318:
12319: @node Minor Modes, Variables, Customization, Customization
12320: @section Minor Modes
12321: @cindex minor modes
12322:
12323: @cindex mode line
12324: Minor modes are options which you can use or not. For example, Auto Fill
12325: mode is a minor mode in which @key{SPC} breaks lines between words as you
12326: type. All the minor modes are independent of each other and of the
12327: selected major mode. Most minor modes say in the mode line when they are
12328: on; for example, @samp{Fill} in the mode line means that Auto Fill mode is
12329: on.
12330:
12331: Append @code{-mode} to the name of a minor mode to get the name of a
12332: command function that turns the mode on or off. Thus, the command to
12333: enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
12334: commands are usually invoked with @kbd{M-x}, but you can bind keys to them
12335: if you wish. With no argument, the function turns the mode on if it was
12336: off and off if it was on. This is known as @dfn{toggling}. A positive
12337: argument always turns the mode on, and an explicit zero argument or a
12338: negative argument always turns it off.
12339:
12340: Auto Fill mode allows you to enter filled text without breaking lines
12341: explicitly. Emacs inserts newlines as necessary to prevent lines from
12342: becoming too long. @xref{Filling}.
12343:
12344: @cindex Overwrite mode
12345: @findex overwrite-mode
12346: Overwrite mode causes ordinary printing characters to replace existing
12347: text instead of shoving it over. For example, if the point is in front of
12348: the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a @kbd{G}
12349: changes it to @samp{FOOGAR}, instead of making it @samp{FOOGBAR} as
12350: usual.@refill
12351:
12352: Abbrev mode allows you to define abbreviations that automatically expand
12353: as you type them. For example, @samp{amd} might expand to @samp{abbrev
12354: mode}. @xref{Abbrevs}, for full information.
12355:
12356: @node Variables, Keyboard Macros, Minor Modes, Customization
12357: @section Variables
12358: @cindex variables
12359: @cindex option
12360:
12361: A @dfn{variable} is a Lisp symbol which has a value. The symbol's name
12362: is also called the name of the variable. Variable names can contain any
12363: characters, but conventionally they are chosen to be words separated by
12364: hyphens. A variable can have a documentation string which describes what
12365: kind of value it should have and how the value will be used.
12366:
12367: Lisp allows any variable to have any kind of value, but most variables
12368: that Emacs uses require a value of a certain type. Often the value should
12369: always be a string, or should always be a number. Sometimes we say that a
12370: certain feature is turned on if a variable is ``non-@code{nil},'' meaning
12371: that if the variable's value is @code{nil}, the feature is off, but the
12372: feature is on for @i{any} other value. The conventional value to use to
12373: turn on the feature---since you have to pick one particular value when you
12374: set the variable---is @code{t}.
12375:
12376: Emacs uses many Lisp variables for internal recordkeeping, as any Lisp
12377: program must, but the most interesting variables for you are the ones that
12378: exist for the sake of customization. Emacs does not (usually) change the
12379: values of these variables; instead, you set the values, and thereby alter
12380: and control the behavior of certain Emacs commands. These variables are
12381: called @dfn{options}. Most options are documented in this manual, and
12382: appear in the Variable Index (@pxref{Variable Index}).
12383:
12384: @cindex right margin position
12385: @cindex margin position
12386: One example of a variable which is an option is @code{fill-column}, which
12387: specifies the position of the right margin (as a number of characters from
12388: the left margin) to be used by the fill commands (@pxref{Filling}).
12389:
12390: @menu
12391: * Examining:: Examining or setting one variable's value.
12392: * Edit Options:: Examining or editing list of all variables' values.
12393: * Locals:: Per-buffer values of variables.
12394: * File Variables:: How files can specify variable values.
12395: @end menu
12396:
12397: @node Examining, Edit Options, Variables, Variables
12398: @subsection Examining and Setting Variables
12399: @cindex setting variables
12400:
12401: @table @kbd
12402: @item C-h v
12403: @itemx M-x describe-variable
12404: Print the value and documentation of a variable.
12405: @item M-x set-variable
12406: Change the value of a variable.
12407: @end table
12408:
12409: @kindex C-h v
12410: @findex describe-variable
12411: @c !!! following written verbosely to avoid overfull hbox
12412: To examine the value of a single variable, type @kbd{C-h v}
12413: (@code{describe-variable}), which reads a variable name using the
12414: minibuffer, with completion. It prints both the value and the
12415: documentation of the variable.
12416:
12417: @example
12418: C-h v fill-column @key{RET}
12419: @end example
12420: @noindent
12421: prints something like
12422: @smallexample
12423: @group
12424: fill-column's value is 72
12425:
12426: Documentation:
12427: *Column beyond which automatic line-wrapping should happen.
12428: Automatically becomes local when set in any fashion.
12429: @end group
12430: @end smallexample
12431:
12432: @cindex option
12433: @noindent
12434: The star at the beginning of the documentation indicates that this variable
12435: is an option. @kbd{C-h v} is not restricted to options; it allows any
12436: variable name.
12437:
12438: @findex set-variable
12439: If you know which option you want to set, you can set it using @kbd{M-x
12440: set-variable}. This reads the variable name with the minibuffer (with
12441: completion), and then reads a Lisp expression for the new value using the
12442: minibuffer a second time. For example,
12443:
12444: @example
12445: M-x set-variable @key{RET} fill-column @key{RET} 72 @key{RET}
12446: @end example
12447:
12448: @noindent
12449: sets @code{fill-column} to 72, like executing the Lisp expression
12450:
12451: @example
12452: (setq fill-column 72)
12453: @end example
12454:
12455: Setting variables in this way, like all means of customizing Emacs
12456: except where explicitly stated, affects only the current Emacs session.
12457:
12458: @node Edit Options, Locals, Examining, Variables
12459: @subsection Editing Variable Values
12460:
12461: @table @kbd
12462: @item M-x list-options
12463: Display a buffer listing names, values and documentation of all options.
12464: @item M-x edit-options
12465: Change option values by editing a list of options.
12466: @end table
12467:
12468: @findex list-options
12469: @kbd{M-x list-options} displays a list of all Emacs option variables, in
12470: an Emacs buffer named @samp{*List Options*}. Each option is shown with its
12471: documentation and its current value. Here is what a portion of it might
12472: look like:
12473:
12474: @smallexample
12475: @group
12476: ;; exec-path:
12477: ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
12478: *List of directories to search programs to run in subprocesses.
12479: Each element is a string (directory name)
12480: or nil (try the default directory).
12481: ;;
12482: ;; fill-column:
12483: 72
12484: *Column beyond which automatic line-wrapping should happen.
12485: Automatically becomes local when set in any fashion.
12486: ;;
12487: @end group
12488: @end smallexample
12489:
12490: @findex edit-options
12491: @cindex Options mode
12492: @kbd{M-x edit-options} goes one step further and immediately selects the
12493: @samp{*List Options*} buffer; this buffer uses the major mode Options mode,
12494: which provides commands that allow you to point at an option and change its
12495: value:
12496:
12497: @table @kbd
12498: @item s
12499: Set the variable point is in or near to a new value read using the
12500: minibuffer.
12501: @item x
12502: Toggle the variable point is in or near: if the value was @code{nil},
12503: it becomes @code{t}; otherwise it becomes @code{nil}.
12504: @item 1
12505: Set the variable point is in or near to @code{t}.
12506: @item 0
12507: Set the variable point is in or near to @code{nil}.
12508: @item n
12509: @itemx p
12510: Move to the next or previous variable.
12511: @end table
12512:
12513: Changes take effect immediately.
12514:
12515: @node Locals, File Variables, Edit Options, Variables
12516: @subsection Local Variables
12517:
12518: @table @kbd
12519: @item M-x make-local-variable
12520: Make a variable have a local value in the current buffer.
12521: @item M-x kill-local-variable
12522: Make a variable use its global value in the current buffer.
12523: @item M-x make-variable-buffer-local
12524: Mark a variable so that setting it will make it local to the
12525: buffer that is current at that time.
12526: @end table
12527:
12528: @cindex local variables
12529: Any variable can be made @dfn{local} to a specific Emacs buffer. This
12530: means that its value in that buffer is independent of its value in other
12531: buffers. A few variables are always local in every buffer. Every other
12532: Emacs variable has a @dfn{global} value which is in effect in all buffers
12533: that have not made the variable local.
12534:
12535: Major modes always make the variables they set local to the buffer.
12536: This is why changing major modes in one buffer has no effect on other
12537: buffers.
12538:
12539: @findex make-local-variable
12540: @kbd{M-x make-local-variable} reads the name of a variable and makes it
12541: local to the current buffer. Further changes in this buffer will not
12542: affect others, and further changes in the global value will not affect this
12543: buffer.
12544:
12545: @findex make-variable-buffer-local
12546: @cindex per-buffer variables
12547: @kbd{M-x make-variable-buffer-local} reads the name of a variable and
12548: changes the future behavior of the variable so that it will become local
12549: automatically when it is set. More precisely, once a variable has been
12550: marked in this way, the usual ways of setting the variable will
12551: automatically do @code{make-local-variable} first. We call such variables
12552: @dfn{per-buffer} variables.
12553:
12554: @c !!! following paragraph rewritten to avoid overfull hbox
12555: Some important variables have been marked per-buffer already. These include
12556: @code{abbrev-mode}, @code{auto-fill-hook}, @code{case-fold-search},
12557: @code{ctl-arrow}, @code{comment-column}, @code{fill-column},
12558: @code{fill-prefix}, @code{indent-tabs-mode}, @code{left-margin},
12559: @code{mode-line-format}, @code{overwrite-mode},
12560: @code{selective-display},
12561: @code{tab-width},
12562: @code{selective-display-ellipses},
12563: and @code{truncate-lines}. Some other variables are
12564: always local in every buffer, but they are used for internal
12565: purposes.@refill
12566:
12567: @findex kill-local-variable
12568: @kbd{M-x kill-local-variable} reads the name of a variable and makes it
12569: cease to be local to the current buffer. The global value of the variable
12570: henceforth is in effect in this buffer. Setting the major mode kills all
12571: the local variables of the buffer.
12572:
12573: @findex setq-default
12574: To set the global value of a variable, regardless of whether the
12575: variable has a local value in the current buffer, you can use the
12576: Lisp function @w{@code{setq-default}}. It works like @code{setq}.
12577: If there is a local value in the current buffer, the local value is
12578: not affected by @code{setq-default}; thus, the new global value may
12579: not be visible until you switch to another buffer. For example,
12580:
12581: @example
12582: (setq-default fill-column 72)
12583: @end example
12584:
12585: @noindent
12586: @code{setq-default} is the only way to set the global value of a variable
12587: that has been marked with @code{make-variable-buffer-local}.
12588:
12589: @findex default-value
12590: Programs can look at a variable's default value with @code{default-value}.
12591: This function takes a symbol as argument and returns its default value.
12592: The argument is evaluated; usually you must quote it explicitly. For
12593: example,
12594:
12595: @example
12596: (default-value 'fill-column)
12597: @end example
12598:
12599: @node File Variables,, Locals, Variables
12600: @subsection Local Variables in Files
12601: @cindex local variables in files
12602:
12603: A file can contain a @dfn{local variables list}, which specifies the
12604: values to use for certain Emacs variables when that file is edited.
12605: Visiting the file checks for a local variables list and makes each variable
12606: in the list local to the buffer in which the file is visited, with the
12607: value specified in the file.
12608:
12609: A local variables list goes near the end of the file, in the last page.
12610: (It is often best to put it on a page by itself.) The local variables list
12611: starts with a line containing the string @samp{Local Variables:}, and ends
12612: with a line containing the string @samp{End:}. In between come the
12613: variable names and values, one set per line, as @samp{@var{variable}:@:
12614: @var{value}}. The @var{value}s are not evaluated; they are used literally.
12615:
12616: The line which starts the local variables list does not have to say just
12617: @samp{Local Variables:}. If there is other text before @samp{Local
12618: Variables:}, that text is called the @dfn{prefix}, and if there is other
12619: text after, that is called the @dfn{suffix}. If these are present, each
12620: entry in the local variables list should have the prefix before it and the
12621: suffix after it. This includes the @samp{End:} line. The prefix and
12622: suffix are included to disguise the local variables list as a comment so
12623: that the compiler or text formatter will not be perplexed by it. If you do
12624: not need to disguise the local variables list as a comment in this way, do
12625: not bother with a prefix or a suffix.@refill
12626:
12627: Two ``variable'' names are special in a local variables list: a value for
12628: the variable @code{mode} really sets the major mode, and a value for the
12629: variable @code{eval} is simply evaluated as an expression and the value is
12630: ignored. These are not real variables; setting such variables in any other
12631: context has no such effect. If @code{mode} is used in a local variables
12632: list, it should be the first entry in the list.
12633:
12634: Here is an example of a local variables list:
12635:
12636: @example
12637: ;;; Local Variables: ***
12638: ;;; mode:lisp ***
12639: ;;; comment-column:0 ***
12640: ;;; comment-start: ";;; " ***
12641: ;;; comment-end:"***" ***
12642: ;;; End: ***
12643: @end example
12644:
12645: Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}. Note also
12646: that comments in the file begin with and end with the same strings.
12647: Presumably the file contains code in a language which is like Lisp
12648: (like it enough for Lisp mode to be useful) but in which comments start
12649: and end in that way. The prefix and suffix are used in the local
12650: variables list to make the list appear as comments when the file is read
12651: by the compiler or interpreter for that language.
12652:
12653: The start of the local variables list must be no more than 3000
12654: characters from the end of the file, and must be in the last page if the
12655: file is divided into pages. Otherwise, Emacs will not notice it is there.
12656: The purpose of this is so that a stray @samp{Local Variables:}@: not in the
12657: last page does not confuse Emacs, and so that visiting a long file that is
12658: all one page and has no local variables list need not take the time to
12659: search the whole file.
12660:
12661: @cindex local variables and Auto Fill
12662: You may be tempted to try to turn on Auto Fill mode with a local variable
12663: list. That is a mistake. The choice of Auto Fill mode or not is a matter
12664: of individual taste, not a matter of the contents of particular files.
12665: If you want to use Auto Fill, set up major mode hooks with your @file{.emacs}
12666: file to turn it on (when appropriate) for you alone (@pxref{Init File}).
12667: Don't try to use a local variable list that would impose your taste on
12668: everyone.
12669:
12670: @vindex inhibit-local-variables
12671: If you are concerned that you might visit a file containing a Trojan-horse
12672: local variable specification, you can prevent local variables processing
12673: by setting the variable @code{inhibit-local-variables} to a non-@code{nil}
12674: value. Emacs will display the local variables specification and then ask
12675: you whether to process it.
12676:
12677: @node Keyboard Macros, Key Bindings, Variables, Customization
12678: @section Keyboard Macros
12679:
12680: @cindex keyboard macros
12681: A @dfn{keyboard macro} is a command defined by the user to abbreviate a
12682: sequence of keys. For example, if you discover that you are about to type
12683: @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
12684: macro to do @kbd{C-n C-d} and calling it with a repeat count of forty.
12685:
12686: @c widecommands
12687: @table @kbd
12688: @item C-x (
12689: Start defining a keyboard macro (@code{start-kbd-macro}).
12690: @item C-x )
12691: End the definition of a keyboard macro (@code{end-kbd-macro}).
12692: @item C-x e
12693: Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
12694: @item C-u C-x (
12695: Re-execute last keyboard macro, then add more keys to its @w{definition}.
12696: @item C-x q
12697: When this point is reached during macro execution, ask for confirmation
12698: (@code{kbd-macro-query}).
12699: @item M-x name-last-kbd-macro
12700: Give a command name (for the duration of the session) to the most
12701: recently defined keyboard macro.
12702: @item M-x insert-kbd-macro
12703: Insert in the buffer a keyboard macro's definition, as Lisp code.
12704: @end table
12705:
12706: Keyboard macros differ from ordinary Emacs commands in that they are
12707: written in the Emacs command language rather than in Lisp. This makes it
12708: easier for the novice to write them, and makes them more convenient as
12709: temporary hacks. However, the Emacs command language is not powerful
12710: enough as a programming language to be useful for writing anything
12711: intelligent or general. For such things, Lisp must be used.
12712:
12713: You define a keyboard macro while executing the commands which are the
12714: definition. Put differently, as you are defining a keyboard macro, the
12715: definition is being executed for the first time. This way, you can see
12716: what the effects of your commands are, so that you don't have to figure
12717: them out in your head. When you are finished, the keyboard macro is
12718: defined and also has been, in effect, executed once. You can then do the
12719: whole thing over again by invoking the macro.
12720:
12721: @menu
12722: * Basic Kbd Macro:: Defining and running keyboard macros.
12723: * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
12724: * Kbd Macro Query:: Keyboard macros that do different things each use.
12725: @end menu
12726:
12727: @node Basic Kbd Macro, Save Kbd Macro, Keyboard Macros, Keyboard Macros
12728: @subsection Basic Use
12729:
12730: @kindex C-x (
12731: @kindex C-x )
12732: @kindex C-x e
12733: @findex start-kbd-macro
12734: @findex end-kbd-macro
12735: @findex call-last-kbd-macro
12736: To start defining a keyboard macro, type the @kbd{C-x (} command
12737: (@code{start-kbd-macro}). From then on, your keys continue to be
12738: executed, but also become part of the definition of the macro. @samp{Def}
12739: appears in the mode line to remind you of what is going on. When you are
12740: finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
12741: definition (without becoming part of it!).
12742:
12743: @example
12744: @group
12745: @exdent For example,
12746:
12747: C-x ( M-F foo C-x )
12748: @end group
12749: @end example
12750:
12751: @noindent
12752: defines a macro to move forward a word and then insert @samp{foo}.
12753:
12754: The macro thus defined can be invoked again with the @kbd{C-x e} command
12755: (@code{call-last-kbd-macro}), which may be given a repeat count as a
12756: numeric argument to execute the macro many times. @kbd{C-x )} can also be
12757: given a repeat count as an argument, in which case it repeats the macro
12758: that many times right after defining it, but defining the macro counts as
12759: the first repetition (since it is executed as you define it). So, giving
12760: @kbd{C-x )} an argument of 4 executes the macro immediately 3 additional
12761: times. An argument of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the
12762: macro indefinitely (until it gets an error or you type @kbd{C-g}).
12763:
12764: If you wish to repeat an operation at regularly spaced places in the
12765: text, define a macro and include as part of the macro the commands to move
12766: to the next place you want to use it. For example, if you want to change
12767: each line, you should position point at the start of a line, and define a
12768: macro to change that line and leave point at the start of the next line.
12769: Then repeating the macro will operate on successive lines.
12770:
12771: After you have terminated the definition of a keyboard macro, you can add
12772: to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
12773: to plain @kbd{C-x (} followed by retyping the whole definition so far. As
12774: a consequence it re-executes the macro as previously defined.
12775:
12776: One limitation on the use of keyboard macros is that if you exit a
12777: recursive edit within a macro that was not entered within the macro,
12778: then the execution of the macro stops at that point. In Emacs 18, View
12779: mode uses a recursive edit, so exiting View mode is an occasion for such
12780: a problem.
12781:
12782: @node Save Kbd Macro, Kbd Macro Query, Basic Kbd Macro, Keyboard Macros
12783: @subsection Naming and Saving Keyboard Macros
12784:
12785: @findex name-last-kbd-macro
12786: If you wish to save a keyboard macro for longer than until you define the
12787: next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
12788: This reads a name as an argument using the minibuffer and defines that name
12789: to execute the macro. The macro name is a Lisp symbol, and defining it in
12790: this way makes it a valid command name for calling with @kbd{M-x} or for
12791: binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
12792: specify a name that has a prior definition other than another keyboard
12793: macro, an error message is printed and nothing is changed.
12794:
12795: @findex insert-kbd-macro
12796: Once a macro has a command name, you can save its definition in a file.
12797: Then it can be used in another editing session. First visit the file
12798: you want to save the definition in. Then use the command
12799:
12800: @example
12801: M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
12802: @end example
12803:
12804: @noindent
12805: This inserts some Lisp code that, when executed later, will define the same
12806: macro with the same definition it has now. You need not understand Lisp
12807: code to do this, because @code{insert-kbd-macro} writes the Lisp code for you.
12808: Then save the file. The file can be loaded with @code{load-file}
12809: (@pxref{Lisp Libraries}). If the file you save in is your init file
12810: @file{~/.emacs} (@pxref{Init File}) then the macro will be defined each
12811: time you run Emacs.
12812:
12813: If you give @code{insert-kbd-macro} a prefix argument, it makes
12814: additional Lisp code to record the keys (if any) that you have bound to the
12815: keyboard macro, so that the macro will be reassigned the same keys when you
12816: load the file.
12817:
12818: @node Kbd Macro Query,, Save Kbd Macro, Keyboard Macros
12819: @subsection Executing Macros with Variations
12820:
12821: @kindex C-x q
12822: @findex kbd-macro-query
12823: Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect similar
12824: to that of @code{query-replace}, where the macro asks you each time around
12825: whether to make a change. When you are defining the macro, type @kbd{C-x
12826: q} at the point where you want the query to occur. During macro
12827: definition, the @kbd{C-x q} does nothing, but when the macro is invoked the
12828: @kbd{C-x q} reads a character from the terminal to decide whether to
12829: continue.
12830:
12831: The special answers are @key{SPC}, @key{DEL}, @kbd{C-d}, @kbd{C-l} and
12832: @kbd{C-r}. Any other character terminates execution of the keyboard macro
12833: and is then read as a command. @key{SPC} means to continue. @key{DEL}
12834: means to skip the remainder of this repetition of the macro, starting again
12835: from the beginning in the next repetition. @kbd{C-d} means to skip the
12836: remainder of this repetition and cancel further repetition. @kbd{C-l}
12837: redraws the screen and asks you again for a character to say what to do.
12838: @kbd{C-r} enters a recursive editing level, in which you can perform
12839: editing which is not part of the macro. When you exit the recursive edit
12840: using @kbd{C-M-c}, you are asked again how to continue with the keyboard
12841: macro. If you type a @key{SPC} at this time, the rest of the macro
12842: definition is executed. It is up to you to leave point and the text in a
12843: state such that the rest of the macro will do what you want.@refill
12844:
12845: @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a
12846: different function. It enters a recursive edit reading input from the
12847: keyboard, both when you type it during the definition of the macro, and
12848: when it is executed from the macro. During definition, the editing you do
12849: inside the recursive edit does not become part of the macro. During macro
12850: execution, the recursive edit gives you a chance to do some particularized
12851: editing. @xref{Recursive Edit}.
12852:
12853: @node Key Bindings, Syntax, Keyboard Macros, Customization
12854: @section Customizing Key Bindings
12855:
12856: This section deals with the @dfn{keymaps} which define the bindings
12857: between keys and functions, and shows how you can customize these bindings.
12858: @cindex command
12859: @cindex function
12860: @cindex command name
12861:
12862: A command is a Lisp function whose definition provides for interactive
12863: use. Like every Lisp function, a command has a function name, a Lisp
12864: symbol whose name usually consists of lower case letters and hyphens.
12865:
12866: @menu
12867: * Keymaps:: Definition of the keymap data structure.
12868: Names of Emacs's standard keymaps.
12869: * Rebinding:: How to redefine one key's meaning conveniently.
12870: * Disabling:: Disabling a command means confirmation is required
12871: before it can be executed. This is done to protect
12872: beginners from surprises.
12873: @end menu
12874:
12875: @node Keymaps, Rebinding, Key Bindings, Key Bindings
12876: @subsection Keymaps
12877: @cindex keymap
12878:
12879: @cindex global keymap
12880: @vindex global-map
12881: The bindings between characters and command functions are recorded in
12882: data structures called @dfn{keymaps}. Emacs has many of these. One, the
12883: @dfn{global} keymap, defines the meanings of the single-character keys that
12884: are defined regardless of major mode. It is the value of the variable
12885: @code{global-map}.
12886:
12887: @cindex local keymap
12888: @vindex c-mode-map
12889: @vindex lisp-mode-map
12890: Each major mode has another keymap, its @dfn{local keymap}, which
12891: contains overriding definitions for the single-character keys that are to
12892: be redefined in that mode. Each buffer records which local keymap is
12893: installed for it at any time, and the current buffer's local keymap is the
12894: only one that directly affects command execution. The local keymaps for
12895: Lisp mode, C mode, and many other major modes always exist even when not in
12896: use. They are the values of the variables @code{lisp-mode-map},
12897: @code{c-mode-map}, and so on. For major modes less often used, the local
12898: keymap is sometimes constructed only when the mode is used for the first
12899: time in a session. This is to save space.
12900:
12901: @cindex minibuffer
12902: @vindex minibuffer-local-map
12903: @vindex minibuffer-local-ns-map
12904: @vindex minibuffer-local-completion-map
12905: @vindex minibuffer-local-must-match-map
12906: @vindex repeat-complex-command-map
12907: There are local keymaps for the minibuffer too; they contain various
12908: completion and exit commands.
12909:
12910: @itemize @bullet
12911: @item
12912: @code{minibuffer-local-map} is used for ordinary input (no completion).
12913: @item
12914: @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
12915: just like @key{RET}. This is used mainly for Mocklisp compatibility.
12916: @item
12917: @code{minibuffer-local-completion-map} is for permissive completion.
12918: @item
12919: @code{minibuffer-local-must-match-map} is for strict completion and
12920: for cautious completion.
12921: @item
12922: @code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}.
12923: @end itemize
12924:
12925: @vindex ctl-x-map
12926: @vindex help-map
12927: @vindex esc-map
12928: Finally, each prefix key has a keymap which defines the key sequences
12929: that start with it. For example, @code{ctl-x-map} is the keymap used for
12930: characters following a @kbd{C-x}.
12931:
12932: @itemize @bullet
12933: @item
12934: @code{ctl-x-map} is the variable name for the map used for characters that
12935: follow @kbd{C-x}.
12936: @item
12937: @code{help-map} is used for characters that follow @kbd{C-h}.
12938: @item
12939: @code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta
12940: characters are actually defined by this map.
12941: @item
12942: @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
12943: @item
12944: @code{mode-specific-map} is for characters that follow @kbd{C-c}.
12945: @end itemize
12946:
12947: The definition of a prefix key is just the keymap to use for looking up
12948: the following character. Actually, the definition is sometimes a Lisp
12949: symbol whose function definition is the following character keymap. The
12950: effect is the same, but it provides a command name for the prefix key that
12951: can be used as a description of what the prefix key is for. Thus, the
12952: binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
12953: definition is the keymap for @kbd{C-x} commands, the value of
12954: @code{ctl-x-map}.@refill
12955:
12956: Prefix key definitions of this sort can appear in either the global map
12957: or a local map. The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC}
12958: as prefix keys appear in the global map, so these prefix keys are always
12959: available. Major modes can locally redefine a key as a prefix by putting
12960: a prefix key definition for it in the local map.@refill
12961:
12962: A mode can also put a prefix definition of a global prefix character such
12963: as @kbd{C-x} into its local map. This is how major modes override the
12964: definitions of certain keys that start with @kbd{C-x}. This case is
12965: special, because the local definition does not entirely replace the global
12966: one. When both the global and local definitions of a key are other
12967: keymaps, the next character is looked up in both keymaps, with the local
12968: definition overriding the global one as usual. So, the character after the
12969: @kbd{C-x} is looked up in both the major mode's own keymap for redefined
12970: @kbd{C-x} commands and in @code{ctl-x-map}. If the major mode's own keymap
12971: for @kbd{C-x} commands contains @code{nil}, the definition from the global
12972: keymap for @kbd{C-x} commands is used.@refill
12973:
12974: @cindex sparse keymap
12975: A keymap is actually a Lisp object. The simplest form of keymap is a
12976: Lisp vector of length 128. The binding for a character in such a keymap is
12977: found by indexing into the vector with the character as an index. A keymap
12978: can also be a Lisp list whose @sc{car} is the symbol @code{keymap} and whose
12979: remaining elements are pairs of the form @code{(@var{char} .@: @var{binding})}.
12980: Such lists are called @dfn{sparse keymaps} because they are used when most
12981: of the characters' entries will be @code{nil}. Sparse keymaps are used
12982: mainly for prefix characters.
12983:
12984: Keymaps are only of length 128, so what about Meta characters, whose
12985: codes are from 128 to 255? A key that contains a Meta character actually
12986: represents it as a sequence of two characters, the first of which is
12987: @key{ESC}. So the key @kbd{M-a} is really represented as @kbd{@key{ESC}
12988: a}, and its binding is found at the slot for @samp{a} in
12989: @code{esc-map}.@refill
12990:
12991: @node Rebinding, Disabling, Keymaps, Key Bindings
12992: @subsection Changing Key Bindings Interactively
12993: @cindex key rebinding, this session
12994: @cindex rebinding keys, this session
12995: @cindex rebinding keys, this session
12996:
12997: The way to redefine an Emacs key is to change its entry in a keymap.
12998: You can change the global keymap, in which case the change is effective in
12999: all major modes (except those that have their own overriding local
13000: definitions for the same key). Or you can change the current buffer's
13001: local map, which affects all buffers using the same major mode.
13002: @findex global-set-key
13003: @findex local-set-key
13004:
13005: @table @kbd
13006: @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
13007: Defines @var{key} globally to run @var{cmd}.
13008: @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
13009: Defines @var{key} locally (in the major mode now in effect) to run
13010: @var{cmd}.
13011: @end table
13012:
13013: For example,
13014:
13015: @example
13016: M-x global-set-key @key{RET} C-f next-line @key{RET}
13017: @end example
13018:
13019: @noindent
13020: would redefine @kbd{C-f} to move down a line. The fact that @var{cmd} is
13021: read second makes it serve as a kind of confirmation for @var{key}.
13022:
13023: These functions offer no way to specify a particular prefix keymap as the
13024: one to redefine in, but that is not necessary, as you can include prefixes
13025: in @var{key}. @var{key} is read by reading characters one by one until
13026: they amount to a complete key (that is, not a prefix key). Thus, if you
13027: type @kbd{C-f} for @var{key}, that's the end; the minibuffer is entered
13028: immediately to read @var{cmd}. But if you type @kbd{C-x}, another
13029: character is read; if that is @kbd{4}, another character is read, and so
13030: on. For example,@refill
13031:
13032: @example
13033: M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
13034: @end example
13035:
13036: @noindent
13037: would redefine @kbd{C-x 4 $} to run the (fictitious) command
13038: @code{spell-other-window}.
13039:
13040: All the key sequences which consist of @kbd{C-c} followed by a letter
13041: are supposed to be reserved for user customization. That is, Emacs Lisp
13042: libraries should not define any of these commands.
13043:
13044: @findex define-key
13045: @findex substitute-key-definition
13046: The most general way to modify a keymap is the function @code{define-key},
13047: used in Lisp code (such as your @file{.emacs} file). @code{define-key}
13048: takes three arguments: the keymap, the key to modify in it, and the new
13049: definition. @xref{Init File}, for an example. @code{substitute-key-definition}
13050: is used similarly; it takes three arguments, an old definition, a new
13051: definition and a keymap, and redefines in that keymap all keys that were
13052: previously defined with the old definition to have the new definition
13053: instead.
13054:
13055: @node Disabling,, Rebinding, Key Bindings
13056: @subsection Disabling Commands
13057: @cindex disabled command
13058:
13059: Disabling a command marks the command as requiring confirmation before it
13060: can be executed. The purpose of disabling a command is to prevent
13061: beginning users from executing it by accident and being confused.
13062:
13063: The direct mechanism for disabling a command is to have a non-@code{nil}
13064: @code{disabled} property on the Lisp symbol for the command. These
13065: properties are normally set up by the user's @file{.emacs} file with
13066: Lisp expressions such as
13067:
13068: @example
13069: (put 'delete-region 'disabled t)
13070: @end example
13071:
13072: If the value of the @code{disabled} property is a string, that string
13073: is included in the message printed when the command is used:
13074:
13075: @example
13076: (put 'delete-region 'disabled
13077: "Text deleted this way cannot be yanked back!\n")
13078: @end example
13079:
13080: @findex disable-command
13081: @findex enable-command
13082: You can make a command disabled either by editing the @file{.emacs} file
13083: directly or with the command @kbd{M-x disable-command}, which edits the
13084: @file{.emacs} file for you. @xref{Init File}.
13085:
13086: Attempting to invoke a disabled command interactively in Emacs causes the
13087: display of a window containing the command's name, its documentation, and
13088: some instructions on what to do immediately; then Emacs asks for input
13089: saying whether to execute the command as requested, enable it and execute,
13090: or cancel it. If you decide to enable the command, you are asked whether to
13091: do this permanently or just for the current session. Enabling permanently
13092: works by automatically editing your @file{.emacs} file. You can use
13093: @kbd{M-x enable-command} at any time to enable any command permanently.
13094:
13095: Whether a command is disabled is independent of what key is used to
13096: invoke it; it also applies if the command is invoked using @kbd{M-x}.
13097: Disabling a command has no effect on calling it as a function from Lisp
13098: programs.
13099:
13100: @node Syntax, Init File, Key Bindings, Customization
13101: @section The Syntax Table
13102: @cindex syntax table
13103:
13104: All the Emacs commands which parse words or balance parentheses are
13105: controlled by the @dfn{syntax table}. The syntax table says which
13106: characters are opening delimiters, which are parts of words, which are
13107: string quotes, and so on. Actually, each major mode has its own syntax
13108: table (though sometimes related major modes use the same one) which it
13109: installs in each buffer that uses that major mode. The syntax table
13110: installed in the current buffer is the one that all commands use, so we
13111: call it ``the'' syntax table. A syntax table is a Lisp object, a vector of
13112: length 256 whose elements are numbers.
13113:
13114: @menu
13115: * Entry: Syntax Entry. What the syntax table records for each character.
13116: * Change: Syntax Change. How to change the information.
13117: @end menu
13118:
13119: @node Syntax Entry, Syntax Change, Syntax, Syntax
13120: @subsection Information about Each Character
13121:
13122: The syntax table entry for a character is a number that encodes six
13123: pieces of information:
13124:
13125: @itemize @bullet
13126: @item
13127: The syntactic class of the character, represented as a small integer.
13128: @item
13129: The matching delimiter, for delimiter characters only.
13130: The matching delimiter of @samp{(} is @samp{)}, and vice versa.
13131: @item
13132: A flag saying whether the character is the first character of a
13133: two-character comment starting sequence.
13134: @item
13135: A flag saying whether the character is the second character of a
13136: two-character comment starting sequence.
13137: @item
13138: A flag saying whether the character is the first character of a
13139: two-character comment ending sequence.
13140: @item
13141: A flag saying whether the character is the second character of a
13142: two-character comment ending sequence.
13143: @end itemize
13144:
13145: The syntactic classes are stored internally as small integers, but are
13146: usually described to or by the user with characters. For example, @samp{(}
13147: is used to specify the syntactic class of opening delimiters. Here is a
13148: table of syntactic classes, with the characters that specify them.
13149:
13150: @table @samp
13151: @item @w{ }
13152: The class of whitespace characters.
13153: @item -
13154: Another name for the class of whitespace characters.
13155: @item w
13156: The class of word-constituent characters.
13157: @item _
13158: The class of characters that are part of symbol names but not words.
13159: This class is represented by @samp{_} because the character @samp{_}
13160: has this class in both C and Lisp.
13161: @item .
13162: The class of punctuation characters that do not fit into any other
13163: special class.
13164: @item (
13165: The class of opening delimiters.
13166: @item )
13167: The class of closing delimiters.
13168: @item '
13169: The class of expression-adhering characters. These characters are
13170: part of a symbol if found within or adjacent to one, and are part
13171: of a following expression if immediately preceding one, but are like
13172: whitespace if surrounded by whitespace.
13173: @item "
13174: The class of string-quote characters. They match each other in pairs,
13175: and the characters within the pair all lose their syntactic
13176: significance except for the @samp{\} and @samp{/} classes of escape
13177: characters, which can be used to include a string-quote inside the
13178: string.
13179: @item $
13180: The class of self-matching delimiters. This is intended for @TeX{}'s
13181: @samp{$}, which is used both to enter and leave math mode. Thus,
13182: a pair of matching @samp{$} characters surround each piece of math mode
13183: @TeX{} input. A pair of adjacent @samp{$} characters act like a single
13184: one for purposes of matching.
13185:
13186: @item /
13187: The class of escape characters that always just deny the following
13188: character its special syntactic significance. The character after one
13189: of these escapes is always treated as alphabetic.
13190: @item \
13191: The class of C-style escape characters. In practice, these are
13192: treated just like @samp{/}-class characters, because the extra
13193: possibilities for C escapes (such as being followed by digits) have no
13194: effect on where the containing expression ends.
13195: @item <
13196: The class of comment-starting characters. Only single-character
13197: comment starters (such as @samp{;} in Lisp mode) are represented this
13198: way.
13199: @item >
13200: The class of comment-ending characters. Newline has this syntax in
13201: Lisp mode.
13202: @end table
13203:
13204: @vindex parse-sexp-ignore-comments
13205: The characters flagged as part of two-character comment delimiters can
13206: have other syntactic functions most of the time. For example, @samp{/} and
13207: @samp{*} in C code, when found separately, have nothing to do with
13208: comments. The comment-delimiter significance overrides when the pair of
13209: characters occur together in the proper order. Only the list and sexp
13210: commands use the syntax table to find comments; the commands specifically
13211: for comments have other variables that tell them where to find comments.
13212: And the list and sexp commands notice comments only if
13213: @code{parse-sexp-ignore-comments} is non-@code{nil}. This variable is set
13214: to @code{nil} in modes where comment-terminator sequences are liable to
13215: appear where there is no comment; for example, in Lisp mode where the
13216: comment terminator is a newline but not every newline ends a comment.
13217:
13218: @node Syntax Change,, Syntax Entry, Syntax
13219: @subsection Altering Syntax Information
13220:
13221: It is possible to alter a character's syntax table entry by storing a new
13222: number in the appropriate element of the syntax table, but it would be hard
13223: to determine what number to use. Therefore, Emacs provides a command that
13224: allows you to specify the syntactic properties of a character in a
13225: convenient way.
13226:
13227: @findex modify-syntax-entry
13228: @kbd{M-x modify-syntax-entry} is the command to change a character's
13229: syntax. It can be used interactively, and is also the means used by major
13230: modes to initialize their own syntax tables. Its first argument is the
13231: character to change. The second argument is a string that specifies the
13232: new syntax. When called from Lisp code, there is a third, optional
13233: argument, which specifies the syntax table in which to make the change. If
13234: not supplied, or if this command is called interactively, the third
13235: argument defaults to the current buffer's syntax table.
13236:
13237: @enumerate
13238: @item
13239: The first character in the string specifies the syntactic class. It
13240: is one of the characters in the previous table (@pxref{Syntax Entry}).
13241:
13242: @item
13243: The second character is the matching delimiter. For a character that
13244: is not an opening or closing delimiter, this should be a space, and may
13245: be omitted if no following characters are needed.
13246:
13247: @item
13248: The remaining characters are flags. The flag characters allowed are
13249:
13250: @table @samp
13251: @item 1
13252: Flag this character as the first of a two-character comment starting sequence.
13253: @item 2
13254: Flag this character as the second of a two-character comment starting sequence.
13255: @item 3
13256: Flag this character as the first of a two-character comment ending sequence.
13257: @item 4
13258: Flag this character as the second of a two-character comment ending sequence.
13259: @end table
13260: @end enumerate
13261:
13262: @kindex C-h s
13263: @findex describe-syntax
13264: A description of the contents of the current syntax table can be
13265: displayed with @kbd{C-h s} (@code{describe-syntax}). The description of
13266: each character includes both the string you would have to give to
13267: @code{modify-syntax-entry} to set up that character's current syntax, and
13268: some English to explain that string if necessary.
13269:
13270: @node Init File,, Syntax, Customization
13271: @section The Init File, .emacs
13272: @cindex init file
13273: @cindex Emacs initialization file
13274: @cindex key rebinding, permanent
13275: @cindex rebinding keys, permanently
13276:
13277: When Emacs is started, it normally loads the file @file{.emacs} in your
13278: home directory. This file, if it exists, should contain Lisp code. It is
13279: called your @dfn{init file}. The command line switches @samp{-q} and
13280: @samp{-u} can be used to tell Emacs whether to load an init file
13281: (@pxref{Entering Emacs}).
13282:
13283: There can also be a @dfn{default init file}, which is the library named
13284: @file{default.el}, found via the standard search path for libraries. The
13285: Emacs distribution contains no such library; your site may create one for
13286: local customizations. If this library exists, it is loaded whenever you
13287: start Emacs. But your init file, if any, is loaded first; if it sets
13288: @code{inhibit-default-init} non-@code{nil}, then @file{default} is not
13289: loaded.
13290:
13291: If you have a large amount of code in your @file{.emacs} file, you
13292: should move it into another file named @file{@var{something}.el},
13293: byte-compile it (@pxref{Lisp Libraries}), and make your @file{.emacs}
13294: file load the other file using @code{load}.
13295:
13296: @menu
13297: * Init Syntax:: Syntax of constants in Emacs Lisp.
13298: * Init Examples:: How to do some things with an init file.
13299: * Terminal Init:: Each terminal type can have an init file.
13300: * Debugging Init:: How to debug your @file{.emacs} file.
13301: @end menu
13302:
13303: @node Init Syntax, Init Examples, Init File, Init File
13304: @subsection Init File Syntax
13305:
13306: The @file{.emacs} file contains one or more Lisp function call
13307: expressions. Each of these consists of a function name followed by
13308: arguments, all surrounded by parentheses. For example, @code{(setq
13309: fill-column 60)} represents a call to the function @code{setq} which is
13310: used to set the variable @code{fill-column} (@pxref{Filling}) to 60.
13311:
13312: The second argument to @code{setq} is an expression for the new value of
13313: the variable. This can be a constant, a variable, or a function call
13314: expression. In @file{.emacs}, constants are used most of the time. They can be:
13315:
13316: @table @asis
13317: @item Numbers:
13318: Numbers are written in decimal, with an optional initial minus sign.
13319:
13320: @item Strings:
13321: Lisp string syntax is the same as C string syntax with a few extra
13322: features. Use a double-quote character to begin and end a string constant.
13323:
13324: Newlines and special characters may be present literally in strings. They
13325: can also be represented as backslash sequences: @samp{\n} for newline,
13326: @samp{\b} for backspace, @samp{\r} for carriage return, @samp{\t} for tab,
13327: @samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a
13328: backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the
13329: character whose octal code is @var{ooo}. Backslash and double-quote are
13330: the only characters for which backslash sequences are mandatory.
13331:
13332: @samp{\C-} can be used as a prefix for a control character, as in
13333: @w{@samp{\C-s}} for @sc{ascii} Control-S, and @samp{\M-} can be used as a prefix for
13334: a meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for
13335: Control-Meta-A.
13336:
13337: @item Characters:
13338: Lisp character constant syntax consists of a @samp{?} followed by
13339: either a character or an escape sequence starting with @samp{\}.
13340: Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
13341: strings and characters are not interchangeable in Lisp; some contexts
13342: require one and some contexts require the other.
13343:
13344: @item True:
13345: @code{t} stands for `true'.
13346:
13347: @item False:
13348: @code{nil} stands for `false'.
13349:
13350: @item Other Lisp objects:
13351: Write a single-quote (') followed by the Lisp object you want.
13352: @end table
13353:
13354: @node Init Examples, Terminal Init, Init Syntax, Init File
13355: @subsection Init File Examples
13356:
13357: Here are some examples of doing certain commonly desired things with
13358: Lisp expressions:
13359:
13360: @itemize @bullet
13361: @item
13362: Make @key{TAB} in C mode just insert a tab if point is in the middle of a
13363: line.
13364:
13365: @example
13366: (setq c-tab-always-indent nil)
13367: @end example
13368:
13369: Here we have a variable whose value is normally @code{t} for `true'
13370: and the alternative is @code{nil} for `false'.
13371:
13372: @item
13373: Make searches case sensitive by default (in all buffers that do not
13374: override this).
13375:
13376: @example
13377: (setq-default case-fold-search nil)
13378: @end example
13379:
13380: This sets the default value, which is effective in all buffers that do
13381: not have local values for the variable. Setting @code{case-fold-search}
13382: with @code{setq} affects only the current buffer's local value, which
13383: is not what you probably want to do in an init file.
13384:
13385: @item
13386: Make Text mode the default mode for new buffers.
13387:
13388: @example
13389: (setq default-major-mode 'text-mode)
13390: @end example
13391:
13392: Note that @code{text-mode} is used because it is the command for entering
13393: the mode we want. A single-quote is written before it to make a symbol
13394: constant; otherwise, @code{text-mode} would be treated as a variable name.
13395:
13396: @item
13397: Turn on Auto Fill mode automatically in Text mode and related modes.
13398:
13399: @example
13400: (setq text-mode-hook
13401: '(lambda () (auto-fill-mode 1)))
13402: @end example
13403:
13404: Here we have a variable whose value should be a Lisp function. The
13405: function we supply is a list starting with @code{lambda}, and a single
13406: quote is written in front of it to make it (for the purpose of this
13407: @code{setq}) a list constant rather than an expression. Lisp functions
13408: are not explained here, but for mode hooks it is enough to know that
13409: @code{(auto-fill-mode 1)} is an expression that will be executed when
13410: Text mode is entered, and you could replace it with any other expression
13411: that you like, or with several expressions in a row.
13412:
13413: @example
13414: (setq text-mode-hook 'turn-on-auto-fill)
13415: @end example
13416:
13417: This is another way to accomplish the same result.
13418: @code{turn-on-auto-fill} is a symbol whose function definition is
13419: @code{(lambda () (auto-fill-@w{mode 1}))}.
13420:
13421: @item
13422: Load the installed Lisp library named @file{foo} (actually a file
13423: @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
13424:
13425: @example
13426: (load "foo")
13427: @end example
13428:
13429: When the argument to @code{load} is a relative pathname, not starting
13430: with @samp{/} or @samp{~}, @code{load} searches the directories in
13431: @code{load-path} (@pxref{Loading}).
13432:
13433: @item
13434: Load the compiled Lisp file @file{foo.elc} from your home directory.
13435:
13436: @example
13437: (load "~/foo.elc")
13438: @end example
13439:
13440: Here an absolute file name is used, so no searching is done.
13441:
13442: @item
13443: Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
13444:
13445: @example
13446: (global-set-key "\C-xl" 'make-symbolic-link)
13447: @end example
13448:
13449: or
13450:
13451: @example
13452: (define-key global-map "\C-xl" 'make-symbolic-link)
13453: @end example
13454:
13455: Note once again the single-quote used to refer to the symbol
13456: @code{make-symbolic-link} instead of its value as a variable.
13457:
13458: @item
13459: Do the same thing for C mode only.
13460:
13461: @example
13462: (define-key c-mode-map "\C-xl" 'make-symbolic-link)
13463: @end example
13464:
13465: @item
13466: Redefine all keys which now run @code{next-line} in Fundamental mode
13467: so that they run @code{forward-line} instead.
13468:
13469: @example
13470: (substitute-key-definition 'next-line 'forward-line
13471: global-map)
13472: @end example
13473:
13474: @item
13475: Make @kbd{C-x C-v} undefined.
13476:
13477: @example
13478: (global-unset-key "\C-x\C-v")
13479: @end example
13480:
13481: One reason to undefine a key is so that you can make it a prefix.
13482: Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v}
13483: a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition
13484: first.
13485:
13486: @item
13487: Make @samp{$} have the syntax of punctuation in Text mode.
13488: Note the use of a character constant for @samp{$}.
13489:
13490: @example
13491: (modify-syntax-entry ?\$ "." text-mode-syntax-table)
13492: @end example
13493:
13494: @item
13495: Enable the use of the command @code{eval-expression} without confirmation.
13496:
13497: @example
13498: (put 'eval-expression 'disabled nil)
13499: @end example
13500: @end itemize
13501:
13502: @node Terminal Init, Debugging Init, Init Examples, Init File
13503: @subsection Terminal-specific Initialization
13504:
13505: Each terminal type can have a Lisp library to be loaded into Emacs when
13506: it is run on that type of terminal. For a terminal type named
13507: @var{termtype}, the library is called @file{term/@var{termtype}} and it is
13508: found by searching the directories @code{load-path} as usual and trying the
13509: suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
13510: subdirectory @file{term} of the directory where most Emacs libraries are
13511: kept.@refill
13512:
13513: The usual purpose of the terminal-specific library is to define the
13514: escape sequences used by the terminal's function keys using the library
13515: @file{keypad.el}. See the file
13516: @file{term/vt100.el} for an example of how this is done.@refill
13517:
13518: When the terminal type contains a hyphen, only the part of the name
13519: before the first hyphen is significant in choosing the library name.
13520: Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
13521: the library @file{term/aaa}. The code in the library can use
13522: @code{(getenv "TERM")} to find the full terminal type name.@refill
13523:
13524: @vindex term-file-prefix
13525: The library's name is constructed by concatenating the value of the
13526: variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
13527: file can prevent the loading of the terminal-specific library by setting
13528: @code{term-file-prefix} to @code{nil}.
13529:
13530: @vindex term-setup-hook
13531: The value of the variable @code{term-setup-hook}, if not @code{nil}, is
13532: called as a function of no arguments at the end of Emacs initialization,
13533: after both your @file{.emacs} file and any terminal-specific library have
13534: been read in. You can set the value in the @file{.emacs} file to override
13535: part of any of the terminal-specific libraries and to define
13536: initializations for terminals that do not have a library.@refill
13537:
13538: @node Debugging Init,, Terminal Init, Init File
13539: @subsection Debugging Your @file{.emacs} File
13540:
13541: Ordinarily, Emacs traps errors that occur while reading @file{.emacs}.
13542: This is convenient, most of the time, because it means you can still get
13543: an Emacs in which you can edit. But it causes inconvenience because
13544: there is no way to enter the debugger if there is an error.
13545:
13546: But you can run the @file{.emacs} file explicitly in an Emacs that is
13547: already set up, and debug errors at that time.
13548:
13549: @example
13550: M-x set-variable
13551: debug-on-error
13552: t
13553: M-x load-file
13554: ~/.emacs
13555: @end example
13556:
13557: In Emacs 19, use the @samp{-debug-init} option if you want errors in
13558: @file{.emacs} to enter the debugger.
13559:
13560: @iftex
13561: @chapter Correcting Mistakes (Yours or Emacs's)
13562:
13563: If you type an Emacs command you did not intend, the results are often
13564: mysterious. This chapter tells what you can do to cancel your mistake or
13565: recover from a mysterious situation. Emacs bugs and system crashes are
13566: also considered.
13567: @end iftex
13568:
13569: @node Quitting, Lossage, Customization, Top
13570: @section Quitting and Aborting
13571: @cindex quitting
13572:
13573: @table @kbd
13574: @item C-g
13575: Quit. Cancel running or partially typed command.
13576: @item C-]
13577: Abort innermost recursive editing level and cancel the command which
13578: invoked it (@code{abort-recursive-edit}).
13579: @item M-x top-level
13580: Abort all recursive editing levels that are currently executing.
13581: @item C-x u
13582: Cancel an already-executed command, usually (@code{undo}).
13583: @end table
13584:
13585: There are two ways of cancelling commands which are not finished
13586: executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]}
13587: or @kbd{M-x top-level}. Quitting is cancelling a partially typed command
13588: or one which is already running. Aborting is getting out of a recursive
13589: editing level and cancelling the command that invoked the recursive edit.
13590:
13591: @cindex quitting
13592: @cindex C-g
13593: Quitting with @kbd{C-g} is used for getting rid of a partially typed
13594: command, or a numeric argument that you don't want. It also stops a
13595: running command in the middle in a relatively safe way, so you can use it
13596: if you accidentally give a command which takes a long time. In particular,
13597: it is safe to quit out of killing; either your text will @var{all} still be
13598: there, or it will @var{all} be in the kill ring (or maybe both). Quitting
13599: an incremental search does special things documented under searching; in
13600: general, it may take two successive @kbd{C-g} characters to get out of a
13601: search. @kbd{C-g} works by setting the variable @code{quit-flag} to
13602: @code{t} the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
13603: frequently and quits if it is non-@code{nil}. @kbd{C-g} is only actually
13604: executed as a command if it is typed while Emacs is waiting for input.
13605:
13606: If you quit twice in a row before the first @kbd{C-g} is recognized, you
13607: activate the ``emergency escape'' feature and return to the shell.
13608: @xref{Emergency Escape}.
13609:
13610: @cindex recursive editing level
13611: @cindex editing level, recursive
13612: @cindex aborting
13613: @findex abort-recursive-edit
13614: @kindex C-]
13615: Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get out
13616: of a recursive editing level and cancel the command which invoked it.
13617: Quitting with @kbd{C-g} does not do this, and could not do this, because it
13618: is used to cancel a partially typed command @i{within} the recursive
13619: editing level. Both operations are useful. For example, if you are in the
13620: Emacs debugger (@pxref{Lisp Debug}) and have typed @kbd{C-u 8} to enter a
13621: numeric argument, you can cancel that argument with @kbd{C-g} and remain in
13622: the debugger.
13623:
13624: @findex top-level
13625: The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
13626: commands to get you out of all the levels of recursive edits that you are
13627: in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level}
13628: goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} are
13629: like all other commands, and unlike @kbd{C-g}, in that they are effective
13630: only when Emacs is ready for a command. @kbd{C-]} is an ordinary key and
13631: has its meaning only because of its binding in the keymap.
13632: @xref{Recursive Edit}.
13633:
13634: @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelling a
13635: command, but you can think of it as cancelling a command already finished
13636: executing. @xref{Undo}.
13637:
13638: @node Lossage, Bugs, Quitting, Top
13639: @section Dealing with Emacs Trouble
13640:
13641: This section describes various conditions in which Emacs fails to work,
13642: and how to recognize them and correct them.
13643:
13644: @menu
13645: * Stuck Recursive:: `[...]' in mode line around the parentheses
13646: * Screen Garbled:: Garbage on the screen
13647: * Text Garbled:: Garbage in the text
13648: * Unasked-for Search:: Spontaneous entry to incremental search
13649: * Emergency Escape:: Emergency escape---
13650: What to do if Emacs stops responding
13651: * Total Frustration:: When you are at your wits' end.
13652: @end menu
13653:
13654: @node Stuck Recursive, Screen Garbled, Lossage, Lossage
13655: @subsection Recursive Editing Levels
13656:
13657: Recursive editing levels are important and useful features of Emacs, but
13658: they can seem like malfunctions to the user who does not understand them.
13659:
13660: If the mode line has square brackets @samp{[@dots{}]} around the parentheses
13661: that contain the names of the major and minor modes, you have entered a
13662: recursive editing level. If you did not do this on purpose, or if you
13663: don't understand what that means, you should just get out of the recursive
13664: editing level. To do so, type @kbd{M-x top-level}. This is called getting
13665: back to top level. @xref{Recursive Edit}.
13666:
13667: @node Screen Garbled, Text Garbled, Stuck Recursive, Lossage
13668: @subsection Garbage on the Screen
13669:
13670: If the data on the screen looks wrong, the first thing to do is see
13671: whether the text is really wrong. Type @kbd{C-l}, to redisplay the entire
13672: screen. If it appears correct after this, the problem was entirely in the
13673: previous screen update.
13674:
13675: Display updating problems often result from an incorrect termcap entry
13676: for the terminal you are using. The file @file{etc/TERMS} in the Emacs
13677: distribution gives the fixes for known problems of this sort.
13678: @file{INSTALL} contains general advice for these problems in one of its
13679: sections. Very likely there is simply insufficient padding for certain
13680: display operations. To investigate the possibility that you have this sort
13681: of problem, try Emacs on another terminal made by a different manufacturer.
13682: If problems happen frequently on one kind of terminal but not another kind,
13683: it is likely to be a bad termcap entry, though it could also be due to a
13684: bug in Emacs that appears for terminals that have or that lack specific
13685: features.
13686:
13687: @node Text Garbled, Unasked-for Search, Screen Garbled, Lossage
13688: @subsection Garbage in the Text
13689:
13690: If @kbd{C-l} shows that the text is wrong, try undoing the changes to it
13691: using @kbd{C-x u} until it gets back to a state you consider correct. Also
13692: try @kbd{C-h l} to find out what command you typed to produce the observed
13693: results.
13694:
13695: If a large portion of text appears to be missing at the beginning or
13696: end of the buffer, check for the word @samp{Narrow} in the mode line.
13697: If it appears, the text is still present, but marked off-limits.
13698: To make it visible again, type @kbd{C-x w}. @xref{Narrowing}.
13699:
13700: @node Unasked-for Search, Emergency Escape, Text Garbled, Lossage
13701: @subsection Spontaneous Entry to Incremental Search
13702:
13703: If Emacs spontaneously displays @samp{I-search:} at the bottom of the
13704: screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q}
13705: according to the poorly designed @samp{xon/xoff} ``flow control''
13706: protocol. You should try to prevent this by putting the terminal in a
13707: mode where it will not use flow control or giving it enough padding
13708: that it will never send a @kbd{C-s}. If that cannot be done, you must
13709: tell Emacs to expect flow control to be used, until you can get a
13710: properly designed terminal.
13711:
13712: Information on how to do these things can be found in the file
13713: @file{INSTALL} in the Emacs distribution.
13714:
13715: @node Emergency Escape, Total Frustration, Unasked-for Search, Lossage
13716: @subsection Emergency Escape
13717:
13718: Because at times there have been bugs causing Emacs to loop without
13719: checking @code{quit-flag}, a special feature causes Emacs to be suspended
13720: immediately if you type a second @kbd{C-g} while the flag is already set,
13721: so you can always get out of GNU Emacs. Normally Emacs recognizes and
13722: clears @code{quit-flag} (and quits!) quickly enough to prevent this from
13723: happening.
13724:
13725: When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it
13726: asks two questions before going back to what it had been doing:
13727:
13728: @example
13729: Auto-save? (y or n)
13730: Abort (and dump core)? (y or n)
13731: @end example
13732:
13733: @noindent
13734: Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.
13735:
13736: Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all
13737: modified buffers in which auto-saving is enabled.
13738:
13739: Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be
13740: executed, dumping core. This is to enable a wizard to figure out why Emacs
13741: was failing to quit in the first place. Execution does not continue
13742: after a core dump. If you answer @kbd{n}, execution does continue. With
13743: luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally.
13744: If not, and you type another @kbd{C-g}, it is suspended again.
13745:
13746: If Emacs is not really hung, just slow, you may invoke the double
13747: @kbd{C-g} feature without really meaning to. Then just resume and answer
13748: @kbd{n} to both questions, and you will arrive at your former state.
13749: Presumably the quit you requested will happen soon.
13750:
13751: The double-@kbd{C-g} feature may be turned off when Emacs is running under
13752: a window system, since the window system always enables you to kill Emacs
13753: or to create another window and run another program.
13754:
13755: @node Total Frustration,, Emergency Escape, Lossage
13756: @subsection Help for Total Frustration
13757: @cindex Eliza
13758: @cindex doctor
13759:
13760: If using Emacs (or something else) becomes terribly frustrating and none
13761: of the techniques described above solve the problem, Emacs can still help
13762: you.
13763:
13764: First, if the Emacs you are using is not responding to commands, type
13765: @kbd{C-g C-g} to get out of it and then start a new one.
13766:
13767: @findex doctor
13768: Second, type @kbd{M-x doctor @key{RET}}.
13769:
13770: The doctor will make you feel better. Each time you say something to
13771: the doctor, you must end it by typing @key{RET} @key{RET}. This lets the
13772: doctor know you are finished.
13773:
13774: @node Bugs, Version 19, Lossage, Top
13775: @section Reporting Bugs
13776:
13777: @cindex bugs
13778: Sometimes you will encounter a bug in Emacs. Although we cannot promise
13779: we can or will fix the bug, and we might not even agree that it is a bug,
13780: we want to hear about bugs you encounter in case we do want to fix them.
13781:
13782: To make it possible for us to fix a bug, you must report it. In order
13783: to do so effectively, you must know when and how to do it.
13784:
13785: @subsection When Is There a Bug
13786:
13787: If Emacs executes an illegal instruction, or dies with an operating
13788: system error message that indicates a problem in the program (as opposed to
13789: something like ``disk full''), then it is certainly a bug.
13790:
13791: If Emacs updates the display in a way that does not correspond to what is
13792: in the buffer, then it is certainly a bug. If a command seems to do the
13793: wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
13794: case of incorrect display updating.
13795:
13796: Taking forever to complete a command can be a bug, but you must make
13797: certain that it was really Emacs's fault. Some commands simply take a long
13798: time. Type @kbd{C-g} and then @kbd{C-h l} to see whether the input Emacs
13799: received was what you intended to type; if the input was such that you
13800: @var{know} it should have been processed quickly, report a bug. If you
13801: don't know whether the command should take a long time, find out by looking
13802: in the manual or by asking for assistance.
13803:
13804: If a command you are familiar with causes an Emacs error message in a
13805: case where its usual definition ought to be reasonable, it is probably a
13806: bug.
13807:
13808: If a command does the wrong thing, that is a bug. But be sure you know
13809: for certain what it ought to have done. If you aren't familiar with the
13810: command, or don't know for certain how the command is supposed to work,
13811: then it might actually be working right. Rather than jumping to
13812: conclusions, show the problem to someone who knows for certain.
13813:
13814: Finally, a command's intended definition may not be best for editing
13815: with. This is a very important sort of problem, but it is also a matter of
13816: judgment. Also, it is easy to come to such a conclusion out of ignorance
13817: of some of the existing features. It is probably best not to complain
13818: about such a problem until you have checked the documentation in the usual
13819: ways, feel confident that you understand it, and know for certain that what
13820: you want is not available. If you are not sure what the command is
13821: supposed to do after a careful reading of the manual, check the index and
13822: glossary for any terms that may be unclear. If you still do not
13823: understand, this indicates a bug in the manual. The manual's job is to
13824: make everything clear. It is just as important to report documentation
13825: bugs as program bugs.
13826:
13827: If the on-line documentation string of a function or variable disagrees
13828: with the manual, one of them must be wrong, so report the bug.
13829:
13830: @subsection How to Report a Bug
13831:
13832: @cindex version of Emacs
13833: @cindex Emacs version
13834: @findex emacs-version
13835: When you decide that there is a bug, it is important to report it and to
13836: report it in a way which is useful. What is most useful is an exact
13837: description of what commands you type, starting with the shell command to
13838: run Emacs, until the problem happens. Always include the version number
13839: of Emacs that you are using; type @kbd{M-x emacs-version} to print this.
13840:
13841: The most important principle in reporting a bug is to report @var{facts},
13842: not hypotheses or categorizations. It is always easier to report the facts,
13843: but people seem to prefer to strain to posit explanations and report
13844: them instead. If the explanations are based on guesses about how Emacs is
13845: implemented, they will be useless; we will have to try to figure out what
13846: the facts must have been to lead to such speculations. Sometimes this is
13847: impossible. But in any case, it is unnecessary work for us.
13848:
13849: For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
13850: @key{RET}}, visiting a file which (you know) happens to be rather large,
13851: and Emacs prints out @samp{I feel pretty today}. The best way to report
13852: the bug is with a sentence like the preceding one, because it gives all the
13853: facts and nothing but the facts.
13854:
13855: Do not assume that the problem is due to the size of the file and say,
13856: ``When I visit a large file, Emacs prints out @samp{I feel pretty today}.''
13857: This is what we mean by ``guessing explanations''. The problem is just as
13858: likely to be due to the fact that there is a @samp{z} in the file name. If
13859: this is so, then when we got your report, we would try out the problem with
13860: some ``large file'', probably with no @samp{z} in its name, and not find
13861: anything wrong. There is no way in the world that we could guess that we
13862: should try visiting a file with a @samp{z} in its name.
13863:
13864: Alternatively, the problem might be due to the fact that the file starts
13865: with exactly 25 spaces. For this reason, you should make sure that you
13866: inform us of the exact contents of any file that is needed to reproduce the
13867: bug. What if the problem only occurs when you have typed the @kbd{C-x C-a}
13868: command previously? This is why we ask you to give the exact sequence of
13869: characters you typed since starting to use Emacs.
13870:
13871: You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
13872: you @i{know} that it makes no difference which visiting command is used.
13873: Similarly, rather than saying ``if I have three characters on the line,''
13874: say ``after I type @w{@kbd{@key{RET} A B C} @key{RET} C-p},'' if that is
13875: the way you entered the text.
13876:
13877: If you are not in Fundamental mode when the problem occurs, you should
13878: say what mode you are in.
13879:
13880: If the manifestation of the bug is an Emacs error message, it is
13881: important to report not just the text of the error message but a backtrace
13882: showing how the Lisp program in Emacs arrived at the error. To make the
13883: backtrace, you must execute the Lisp expression
13884: @code{(setq @w{debug-on-error t})} before the error happens (that is to
13885: say, you must execute that expression and then make the bug happen). This
13886: causes the Lisp debugger to run (@pxref{Lisp Debug}). The debugger's
13887: backtrace can be copied as text into the bug report. This use of the
13888: debugger is possible only if you know how to make the bug happen again. Do
13889: note the error message the first time the bug happens, so if you can't make
13890: it happen again, you can report at least that.
13891:
13892: Check whether any programs you have loaded into the Lisp world, including
13893: your @file{.emacs} file, set any variables that may affect the functioning
13894: of Emacs. Also, see whether the problem happens in a freshly started Emacs
13895: without loading your @file{.emacs} file (start Emacs with the @code{-q} switch
13896: to prevent loading the init file.) If the problem does @var{not} occur
13897: then, it is essential that we know the contents of any programs that you
13898: must load into the Lisp world in order to cause the problem to occur.
13899:
13900: If the problem does depend on an init file or other Lisp programs that
13901: are not part of the standard Emacs system, then you should make sure it is
13902: not a bug in those programs by complaining to their maintainers first.
13903: After they verify that they are using Emacs in a way that is supposed to
13904: work, they should report the bug.
13905:
13906: If you can tell us a way to cause the problem without visiting any files,
13907: please do so. This makes it much easier to debug. If you do need files,
13908: make sure you arrange for us to see their exact contents. For example, it
13909: can often matter whether there are spaces at the ends of lines, or a
13910: newline after the last line in the buffer (nothing ought to care whether
13911: the last line is terminated, but tell that to the bugs).
13912:
13913: @findex open-dribble-file
13914: @cindex dribble file
13915: The easy way to record the input to Emacs precisely is to write a
13916: dribble file; execute the Lisp expression
13917:
13918: @example
13919: (open-dribble-file "~/dribble")
13920: @end example
13921:
13922: @noindent
13923: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting
13924: Emacs. From then on, all Emacs input will be written in the specified
13925: dribble file until the Emacs process is killed.
13926:
13927: @findex open-termscript
13928: @cindex termscript file
13929: For possible display bugs, it is important to report the terminal type
13930: (the value of environment variable @code{TERM}), the complete termcap entry
13931: for the terminal from @file{/etc/termcap} (since that file is not identical
13932: on all machines), and the output that Emacs actually sent to the terminal.
13933: The way to collect this output is to execute the Lisp expression
13934:
13935: @example
13936: (open-termscript "~/termscript")
13937: @end example
13938:
13939: @noindent
13940: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just
13941: after starting Emacs. From then on, all output from Emacs to the terminal
13942: will be written in the specified termscript file as well, until the Emacs
13943: process is killed. If the problem happens when Emacs starts up, put this
13944: expression into your @file{.emacs} file so that the termscript file will
13945: be open when Emacs displays the screen for the first time. Be warned:
13946: it is often difficult, and sometimes impossible, to fix a terminal-dependent
13947: bug without access to a terminal of the type that stimulates the bug.@refill
13948:
13949: The address for reporting bugs is
13950:
13951: @format
13952: GNU Emacs Bugs
13953: Free Software Foundation
13954: 675 Mass Ave
13955: Cambridge, MA 02139
13956: @end format
13957:
13958: @noindent
13959: or send email either to @samp{bug-gnu-emacs@@prep.ai.mit.edu} (Internet)
13960: or to @samp{uunet!prep.ai.mit.edu!bug-gnu-emacs} (Usenet).
13961:
13962: Once again, we do not promise to fix the bug; but if the bug is serious,
13963: or ugly, or easy to fix, chances are we will want to.
13964:
13965: @node Version 19, Manifesto, Bugs, Top
13966: @unnumbered Version 19 Antenews
13967:
13968: This chapter prematurely describes new features of Emacs 19, in
13969: anticipation of its release. We have included this so that the version
13970: 18 manuals don't become obsolete as soon as Emacs 19 comes out. This
13971: list mentions only features that would belong in @cite{The GNU Emacs
13972: Manual}; changes relevant to Emacs Lisp programming will be documented
13973: in the next revision of @cite{The GNU Emacs Lisp Manual}.
13974:
13975: @menu
13976: * Basic Changes:: Changes every user must know.
13977: * New Facilities:: Changes every user will want to know.
13978: * Binding Changes:: Ordinary commands that have been moved. Important!.
13979: * Changed Commands:: Ordinary commands that have new features. Important!
13980: * M-x Changes:: Changes in commands you run with @kbd{M-x}. Important!
13981: * New Commands:: Commands that have been added
13982: that we expect many users to want to use.
13983: * Search Changes:: Changes in incremental search. Some are important.
13984:
13985: The rest of the changes you can pretty much ignore unless you are interested.
13986:
13987: * Filling Changes:: Changes in fill commands.
13988: * TeX Mode Changes:: Changes in the commands for editing TeX files
13989: and running TeX.
13990: * Shell Changes:: Major changes in all the modes that run subprograms.
13991: * Spell Changes:: These commands now use ispell instead of spell.
13992: * Tags Changes:: Changes in Tags facility.
13993: * Mail Changes:: Changes in both Sendmail mode and Rmail mode.
13994: * Info Changes:: New commands in Info.
13995: * Dired Changes:: Powerful new features in Dired.
13996: * GNUS:: An alternative news reader.
13997: * Calendar/Diary:: The calendar feature now lets you move to different
13998: dates and convert to and from other calendars.
13999: You can also display related entries from your diary
14000: file.
14001: * Version Control:: A convenient interface to RCS or SCCS.
14002: * Emerge:: A new feature for merging files interactively.
14003: * Debuggers:: Running debuggers (GDB, DBX, SDB) under Emacs.
14004: * Other New Modes:: Miscellaneous new and changed major modes.
14005: * Key Sequence Changes:: You can now bind key sequences that include function
14006: keys and mouse clicks.
14007: * Hook Changes:: Hook variables have been renamed more systematically.
14008: @end menu
14009:
14010: @node Basic Changes
14011: @section Basic Changes
14012:
14013: We have made changes to help Emacs use fewer resources and make it less
14014: likely to become irreparably hung. While these changes don't alter the
14015: commands of Emacs, they are important enough to be worth mentioning.
14016:
14017: You can quit with @kbd{C-g} while Emacs is waiting to read or write a
14018: file---provided the operating system will allow you to interrupt the
14019: system call that is hung. (Unfortunately, most NFS implementations
14020: won't allow interruption.)
14021:
14022: When you kill buffers, Emacs now returns memory to the operating system,
14023: thus reducing the size of the Emacs process. The space that you free up
14024: by killing buffers can now be reused for other buffers no matter what
14025: their sizes, or reused by other processes if Emacs doesn't need it.
14026:
14027: @subheading Multiple X Windows
14028:
14029: When using X windows, you can now create more than one window at the X
14030: level. Each X window displays a @dfn{frame} which can contain one or
14031: several Emacs windows. Each frame has its own echo area and normally
14032: its own minibuffer. (To avoid confusion, we reserve the word
14033: ``window'' for the subdivisions that Emacs implements, and never use
14034: it to refer to a frame.) The easiest way to create additional frames
14035: is with the @kbd{C-x 5} prefix character (@pxref{New Commands, , New
14036: Everyday Commands}).
14037:
14038: @c ??? Change not yet made
14039: @findex scroll-bar-mode @r{(V19)}
14040: Emacs windows can now have scroll bars; use the @code{scroll-bar-mode}
14041: command to turn scroll bars on or off. With no argument, it toggles the
14042: use of scroll bars. With an argument, it turns use of scroll bars on if
14043: and only if the argument is positive. This command applies to all
14044: frames, including frames yet to be created. (You can control scroll
14045: bars on a frame by frame basis by writing a Lisp program.)
14046:
14047: @subheading Undo Improvements
14048:
14049: @c ??? Change not yet made
14050: Undoing a deletion now puts the cursor position where it was just before
14051: the deletion.
14052:
14053: @subheading Auto Save Improvements
14054:
14055: @vindex auto-save-timeout @r{(V19)}
14056: Emacs now does garbage collection and auto saving while it is waiting
14057: for input, which often avoids the need to do these things while you are
14058: typing. The variable @code{auto-save-timeout} says how many seconds
14059: Emacs should wait, after you stop typing, before it does an auto save
14060: and perhaps also a garbage collection. (The actual time period varies
14061: also according to the size of the buffer---longer for longer buffers,
14062: since auto saving itself is slower for long buffers.) This way, Emacs
14063: does not interrupt or delay your typing.
14064:
14065: In Emacs 18, when auto saving detects that a buffer has shrunk greatly,
14066: it refrains from auto saving that buffer and displays a warning. In
14067: version 19, it also turns off Auto Save mode in that buffer, so that you
14068: won't get the same warning repeatedly. If you reenable Auto Save mode
14069: in that buffer, Emacs will start saving it again despite the shrinkage.
14070:
14071: @findex revert-buffer @r{(V19)}
14072: In Emacs 19, @code{revert-buffer} no longer offers to revert from the
14073: latest auto-save file. That option hasn't been very useful since the
14074: change to keep more undo information.
14075:
14076: The command @code{recover-file} no longer turns off Auto Save mode.
14077:
14078: @subheading File Local Variables
14079:
14080: @vindex enable-local-variables @r{(V19)}
14081: @vindex inhibit-local-variables @r{(V19)}
14082: The user option for controlling whether files can set local variables is
14083: called @code{enable-local-variables} in Emacs 19, rather than
14084: @code{inhibit-local-variables}. A value of @code{t} means
14085: local-variables lists are obeyed; @code{nil} means they are ignored;
14086: anything else means query the user.
14087:
14088: @node New Facilities
14089: @section New Basic Facilities
14090:
14091: @cindex minibuffer history
14092: @cindex history, in minibuffer
14093: @kindex M-p @r{(V19)}
14094: @kindex M-n @r{(V19)}
14095: @findex next-history-element @r{(V19)}
14096: @findex previous-history-element @r{(V19)}
14097: You can now get back recent minibuffer inputs conveniently. While in
14098: the minibuffer, type @kbd{M-p} (@code{previous-history-element}) to fetch
14099: the next earlier minibuffer input, and use @kbd{M-n}
14100: (@code{next-history-element}) to fetch the next later input.
14101:
14102: @findex previous-matching-history-element @r{(V19)}
14103: @findex next-matching-history-element @r{(V19)}
14104: @kindex M-r @r{(V19)}
14105: @kindex M-s @r{(V19)}
14106: There are also commands to search forward or backward through the
14107: history. As of this writing, they search for history elements that
14108: match a regular expression that you specify with the minibuffer.
14109: @kbd{M-r} (@code{previous-matching-history-element}) searches older
14110: elements in the history, while @kbd{M-s}
14111: (@code{next-matching-history-element}) searches newer elements. By
14112: special dispensation, these commands can always use the minibuffer to
14113: read their arguments even though you are already in the minibuffer when
14114: you issue them.
14115:
14116: We may have changed the precise way these commands work by the time you
14117: use Emacs 19. Perhaps they will search for a match for the string given
14118: so far in the minibuffer; perhaps they will search for a literal match
14119: rather than a regular expression match; perhaps they will only accept
14120: matches at the beginning of a history element; perhaps they will read
14121: the string to search for incrementally like @kbd{C-s}. We want to
14122: choose an interface that is convenient, flexible and natural, and these
14123: goals are somewhat contradictory. To find out what interface is
14124: actually available, type @kbd{C-h f previous-matching-history-element}.
14125:
14126: The history feature is available for all uses of the minibuffer, but
14127: there are separate history lists for different kinds of input. For
14128: example, there is a list for file names, used by all the commands that
14129: read file names. There is a list for arguments of commands like
14130: @code{query-replace}. There are also very specific history lists, such
14131: as the one that @code{compile} uses for compilation commands.
14132:
14133: @subheading Remote File Access
14134:
14135: @cindex ftp
14136: @cindex remote file access
14137: You can refer to files on other machines using a special file name syntax:
14138:
14139: @example
14140: @group
14141: /@var{host}:@var{filename}
14142: /@var{user}@@@var{host}:@var{filename}
14143: @end group
14144: @end example
14145:
14146: When you do this, Emacs uses the FTP program to read and write files on
14147: the specified host. It logs in through FTP using your user name or the
14148: name @var{user}. It may ask you for a password from time to time; this
14149: is used for logging in on @var{host}.
14150:
14151: @subheading Using Flow Control
14152:
14153: @cindex flow control in V19
14154: @cindex xon-xoff in V19
14155: There is now a convenient way to enable flow control when your terminal
14156: or your connection won't work without it. Suppose you want to do this
14157: on VT-100 and H19 terminals; put the following in your @file{.emacs}
14158: file:
14159:
14160: @findex evade-flow-control-on @r{(V19)}
14161: @example
14162: (evade-flow-control-on "vt100" "h19")
14163: @end example
14164:
14165: When flow control is enabled, you must type @kbd{C-\} to get the effect
14166: of a @kbd{C-s}, and type @kbd{C-^} to get the effect of a @kbd{C-q}.
14167:
14168: @subheading Controlling Backup File Names
14169:
14170: @vindex version-control @r{(V19)}
14171: @vindex VERSION_CONTROL
14172: The default setting of the Lisp variable @code{version-control} now
14173: comes from the environment variable @code{VERSION_CONTROL}. Thus, you
14174: can select a style of backup file naming for Emacs and other GNU
14175: utilities all together.
14176:
14177: @node Binding Changes
14178: @section Changed Key Bindings
14179:
14180: @table @kbd
14181: @item M-@{
14182: @kindex M-@{ @r{(V19)}
14183: This is the new key sequence for @code{backward-paragraph}. The old key
14184: sequence for this, @kbd{M-[}, is now undefined by default.
14185:
14186: The reason for this change is to avoid conflict with the sequences that
14187: function keys send on most terminals.
14188:
14189: @item M-@}
14190: @kindex M-@} @r{(V19)}
14191: This is the new key sequence for @code{forward-paragraph}. The old key
14192: sequence for this, @kbd{M-]}, is now undefined by default.
14193:
14194: We changed this to go along with @kbd{M-@{}.
14195:
14196: @item C-x C-u
14197: @itemx C-x C-l
14198: @kindex C-x C-u @r{(V19)}
14199: @kindex C-x C-l @r{(V19)}
14200: The two commands, @kbd{C-x C-u} (@code{upcase-region}) and @kbd{C-x
14201: C-l} (@code{downcase-region}), are now disabled by default; these
14202: keys seem to be often hit by accident, and can be quite
14203: destructive if their effects are not noticed immediately.
14204:
14205: @item C-x 3
14206: @kindex C-x 3 @r{(V19)}
14207: @kbd{C-x 3} is now the key binding for @code{split-window-horizontally},
14208: which splits a window into two side-by-side windows. This used to be
14209: @kbd{C-x 5}.
14210:
14211: @item @kbd{C-x 4 C-o}
14212: @kindex C-x 4 C-o @r{(V19)}
14213: @findex display-buffer @r{(V19)}
14214: This key now runs @code{display-buffer}, which displays a specified
14215: buffer in another window without selecting it.
14216:
14217: @item M-g
14218: @kindex M-g @r{(V19)}
14219: @kbd{M-g} is now undefined. It used to run the command @code{fill-region}.
14220: This command used to be run more often by mistake than on purpose.
14221:
14222: @item C-x a
14223: @itemx C-x n
14224: @itemx C-x r
14225: @kindex C-x a @r{(V19)}
14226: @kindex C-x n @r{(V19)}
14227: @kindex C-x r @r{(V19)}
14228: Three new prefix keys have been created to make many of the @w{@kbd{C-x}}
14229: commands more systematic: @w{@kbd{C-x a}}, @w{@kbd{C-x n}} and @w{@kbd{C-x r}}.
14230: @w{@kbd{C-x a}} is used for abbreviation commands, @w{@kbd{C-x n}} for commands
14231: pertaining to narrowing, and @w{@kbd{C-x r}} for register and rectangle
14232: commands. These are the new bindings, in detail:
14233:
14234: @table @kbd
14235: @item C-x a l
14236: @code{add-mode-abbrev} (previously @kbd{C-x C-a}).
14237: @item C-x a g
14238: @code{add-global-abbrev} (previously @kbd{C-x +}).
14239: @item C-x a i g
14240: @code{inverse-add-mode-abbrev} (previously @kbd{C-x C-h}).
14241: @item C-x a i l
14242: @code{inverse-add-global-abbrev} (previously @kbd{C-x -}).
14243: @item C-x a e
14244: @code{expand-abbrev} (previously @kbd{C-x '}).
14245:
14246: @sp 1
14247:
14248: @item C-x n n
14249: @code{narrow-to-region} (previously @kbd{C-x n}).
14250: @item C-x n p
14251: @code{narrow-to-page} (previously @kbd{C-x p}).
14252: @item C-x n w
14253: @code{widen} (previously @kbd{C-x w}).
14254:
14255: @sp 1
14256:
14257: @item C-x r C-@key{SPC}
14258: @code{point-to-register} (previously @kbd{C-x /}).
14259: @item C-x r @key{SPC}
14260: Also @code{point-to-register} (previously @kbd{C-x /}).
14261: @item C-x r j
14262: @code{jump-to-register} (previously @kbd{C-x j}).
14263: @item C-x r s
14264: @code{copy-to-register} (previously @kbd{C-x x}).
14265: @item C-x r i
14266: @code{insert-register} (previously @kbd{C-x g}).
14267: @item C-x r r
14268: @code{copy-rectangle-to-register} (previously @kbd{C-x r}).
14269: @item C-x r k
14270: @code{kill-rectangle} (no previous key binding).
14271: @item C-x r y
14272: @code{yank-rectangle} (no previous key binding).
14273: @item C-x r o
14274: @code{open-rectangle} (no previous key binding).
14275: @item C-x r f
14276: @code{frame-configuration-to-register} (a new command)
14277: saves the state of all windows in all frames.
14278: Use @kbd{C-x r j} to restore the configuration.
14279: @c !!! following generates acceptable underfull hbox
14280: @item C-x r w
14281: @code{window-configuration-to-register} (a new command)
14282: saves the state of all windows in the selected frame.
14283: Use @kbd{C-x r j} to restore the configuration.
14284: @end table
14285:
14286: The old key bindings @kbd{C-x /}, @kbd{C-x j}, @kbd{C-x x} and @kbd{C-x
14287: g} have not yet been removed. The other old key bindings listed have
14288: been removed. The old key binding @kbd{C-x a}, which was
14289: @code{append-to-buffer}, was removed to make way for a prefix key; now
14290: @code{append-to-buffer} has no keybinding.
14291:
14292: @item C-x v
14293: @kbd{C-x v} is a new prefix character, used for version control commands.
14294: @xref{Version Control}.
14295: @end table
14296:
14297: @node Changed Commands
14298: @section Changed Everyday Commands
14299:
14300: @table @kbd
14301: @item C-o
14302: @kindex C-o @r{(V19)}
14303: When you have a fill prefix, the command @kbd{C-o} inserts the prefix on
14304: the newly created line.
14305:
14306: @item M-^
14307: @kindex M-^ @r{(V19)}
14308: When you have a fill prefix, the command @kbd{M-^} deletes the prefix
14309: (if it occurs) after the newline that it deletes.
14310:
14311: @item M-z
14312: @kindex M-z @r{(V19)}
14313: The @kbd{M-z} command (@code{zap-to-char}) now kills through the target
14314: character. In version 18, it killed up to but not including the target
14315: character.
14316:
14317: @item M-!
14318: @kindex M-! @r{(V19)}
14319: The command @kbd{M-!} (@code{shell-command}) now runs the specified
14320: shell command asynchronously if it ends in @samp{&}, just as the shell
14321: does.
14322:
14323: @item C-x 2
14324: @kindex C-x 2 @r{(V19)}
14325: @vindex split-window-keep-point @r{(V19)}
14326: The @kbd{C-x 2} command (@code{split-window-vertically}) now tries to
14327: avoid scrolling by putting point in whichever window happens to contain
14328: the screen line the cursor is already on. If you don't like this, you
14329: can turn it off by setting @code{split-window-keep-point} to
14330: @code{nil}.
14331:
14332: @item C-x s
14333: @kindex C-x s @r{(V19)}
14334: The @kbd{C-x s} command (@code{save-some-buffers}) now gives you more
14335: options when it asks whether to save a particular buffer. The options
14336: are analogous to those of @code{query-replace}. Here they are:
14337:
14338: @table @kbd
14339: @item y
14340: Save this buffer and ask about the rest of the buffers.
14341: @item n
14342: Don't save this buffer, but ask about the rest of the buffers.
14343: @item !
14344: Save this buffer and all the rest with no more questions.
14345: @c !!! following generates acceptable underfull hbox
14346: @item @key{ESC}
14347: Terminate @code{save-some-buffers} without any more saving.
14348: @item .
14349: @c !!! following written verbosely to avoid overfull hbox
14350: Save only this buffer, then exit @code{save-some-buffers} without even asking
14351: about other buffers.
14352: @item C-r
14353: View the buffer that you are currently being asked about. When you exit
14354: View mode, you get back to @code{save-some-buffers}, which asks the
14355: question again.
14356: @item C-h
14357: Display a help message about these options.
14358: @end table
14359:
14360: @item C-x C-v
14361: @kindex C-x C-v @r{(V19)}
14362: This command (@kbd{find-alternate-file}) now inserts the entire current
14363: file name in the minibuffer. This is convenient if you made a small
14364: mistake in typing it. Point goes after the last slash, before the last
14365: file name component, so if you want to replace it entirely, you can use
14366: @kbd{C-k} right away to delete it.
14367:
14368: @item C-M-f
14369: @kindex C-M-f @r{(V19)}
14370: Expression and list commands such as @kbd{C-M-f} now ignore parentheses
14371: within comments in Lisp mode.
14372: @end table
14373:
14374: @node M-x Changes
14375: @section Changes in Common @kbd{M-x} Commands
14376:
14377: @table @asis
14378: @item @kbd{M-x make-symbolic-link}
14379: @findex make-symbolic-link @r{(V19)}
14380: This command now does not expand its second argument. This lets you
14381: make a link with a target that is a relative file name.
14382:
14383: @item @kbd{M-x add-change-log-entry}
14384: @itemx @kbd{C-x 4 a}
14385: @findex add-change-log-entry @r{(V19)}
14386: @kindex C-x 4 a @r{(V19)}
14387: These commands now automatically insert the name of the file and often
14388: the name of the function that you changed. They also handle grouping of
14389: entries.
14390:
14391: There is now a special major mode for editing @file{ChangeLog} files.
14392: It makes filling work conveniently. Each bunch of grouped entries is
14393: one paragraph, and each collection of entries from one person on one day
14394: is considered a page.
14395:
14396: @item @kbd{M-x compare-windows}
14397: @findex compare-windows @r{(V19)}
14398: With a prefix argument, @code{compare-windows} ignores changes in
14399: whitespace. If the variable @code{compare-ignore-case} is
14400: non-@code{nil}, it ignores differences in case as well.
14401:
14402: @item @kbd{M-x view-buffer}
14403: @itemx @kbd{M-x view-file}
14404: @findex view-buffer @r{(V19)}
14405: @findex view-file @r{(V19)}
14406: The View commands (such as @kbd{M-x view-buffer} and @kbd{M-x
14407: view-file}) no longer use recursive edits; instead, they switch
14408: temporarily to a different major mode (View mode) specifically designed
14409: for moving around through a buffer without editing it.
14410:
14411: @item @kbd{M-x manual-entry}
14412: @findex manual-entry @r{(V19)}
14413: @kbd{M-x manual-entry} now uses View mode for the buffer showing the
14414: man page.
14415:
14416: @item @kbd{M-x compile}
14417: @findex compile @r{(V19)}
14418: You can repeat any previous @code{compile} conveniently using the
14419: minibuffer history commands, while in the minibuffer entering the
14420: compilation command.
14421:
14422: While a compilation is going on, the string @samp{Compiling} appears
14423: in the mode line. When this string disappears, the compilation is
14424: finished.
14425:
14426: The buffer of compiler messages is in Compilation mode. This mode
14427: provides the keys @key{SPC} and @key{DEL} to scroll by screenfuls, and
14428: @kbd{M-n} and @kbd{M-p} to move to the next or previous error message.
14429: You can also use @kbd{M-@{} and @kbd{M-@}} to move up or down to an
14430: error message for a different source file. Use @kbd{C-c C-c} on any
14431: error message to find the corresponding source code.
14432:
14433: Emacs 19 has a more general parser for compiler messages. For example, it
14434: can understand messages from lint, and from certain C compilers whose
14435: error message format is unusual.
14436: @end table
14437:
14438: @node New Commands
14439: @section New Everyday Commands
14440:
14441: @table @asis
14442: @item @kbd{C-z}
14443: @kindex C-z @r{(V19)}
14444: @findex iconify-frame @r{(V19)}
14445: When you are using X windows, @kbd{C-z} (@code{iconify-frame}) now
14446: iconifies the current frame.
14447:
14448: @item @kbd{C-M-l}
14449: @kindex C-M-l @r{(V19)}
14450: @findex reposition-window @r{(V19)}
14451: The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
14452: window heuristically in a way designed to get useful information onto
14453: the screen. For example, in a Lisp file, this command tries to get the
14454: entire current defun onto the screen if possible.
14455:
14456: @item @kbd{C-M-r}
14457: @kindex C-M-r @r{(V19)}
14458: @findex isearch-backward-regexp @r{(V19)}
14459: @c !!! following written verbosely to avoid overfull hbox
14460: The @kbd{C-M-r} key now runs the command @code{isearch-backward-regexp},
14461: which does reverse incremental regexp search.
14462:
14463: @item @kbd{C-x 5}
14464: @kindex C-x 5 @r{(V19)}
14465: The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with parallel
14466: subcommands. The difference is that @kbd{C-x 5} commands create a new
14467: frame rather than just a new window.
14468:
14469: @item @kbd{C-x 5 C-f}
14470: @itemx @kbd{C-x 5 b}
14471: @kindex C-x 5 C-f @r{(V19)}
14472: @kindex C-x 5 b @r{(V19)}
14473: @findex find-file-other-frame @r{(V19)}
14474: @findex switch-to-buffer-other-frame @r{(V19)}
14475: These new commands switch to a specified file or buffer in a new frame
14476: (when using X windows). The commands' names are
14477: @code{find-file-other-frame} and @code{switch-to-buffer-other-frame}.
14478:
14479: @item @kbd{C-x 5 m}
14480: @kindex C-x 5 m @r{(V19)}
14481: @findex mail-other-frame @r{(V19)}
14482: Start outgoing mail in another frame (@code{mail-other-frame}).
14483:
14484: @item @kbd{C-x 5 .}
14485: @kindex C-x 5 . @r{(V19)}
14486: @findex find-tag-other-frame @r{(V19)}
14487: Find a tag in another frame (@code{find-tag-other-frame}).
14488:
14489: @item @kbd{C-x 4 r}
14490: @kindex C-x 4 r @r{(V19)}
14491: @findex find-file-read-only-other-window @r{(V19)}
14492: This is now @code{find-file-read-only-other-window}.
14493:
14494: @item arrow keys
14495: @cindex arrow keys
14496: The arrow keys now have default bindings to move in the appropriate
14497: directions.
14498:
14499: @item @kbd{C-h C-f}
14500: @itemx @kbd{C-h C-k}
14501: @kindex C-h C-f @r{(V19)}
14502: @kindex C-h C-k @r{(V19)}
14503: These new help commands enter Info and display the node for a given
14504: Emacs function name or key sequence, respectively.
14505:
14506: @item @kbd{M-a}
14507: @itemx @kbd{M-e}
14508: @kindex M-a @r{(C mode in V19)}
14509: @kindex M-e @r{(C mode in V19)}
14510: @findex c-beginning-of-statement @r{(V19)}
14511: @findex c-end-of-statement @r{(V19)}
14512: In C mode, @kbd{M-a} and @kbd{M-e} now move by complete C statements
14513: (@code{c-beginning-of-statement} and @code{c-end-of-statement}).
14514:
14515: @item @kbd{M-q}
14516: @kindex M-q @r{(C mode in V19)}
14517: @findex c-fill-paragraph @r{(V19)}
14518: @kbd{M-q} in C mode now runs @code{c-fill-paragraph}, which is designed
14519: for filling C comments. (We assume you don't want to fill the actual C
14520: code in a C program.)
14521:
14522: @item @kbd{M-x c-up-conditional}
14523: @findex c-up-conditional @r{(V19)}
14524: In C mode, @code{c-up-conditional} moves back to the containing
14525: preprocessor conditional, setting the mark where point was previously.
14526:
14527: A prefix argument acts as a repeat count. With a negative argument,
14528: this command moves forward to the end of the containing preprocessor
14529: conditional. When going backwards, @samp{#elif} acts like @samp{#else}
14530: followed by @samp{#if}. When going forwards, @samp{#elif} is ignored.
14531:
14532: @item @kbd{M-x comment-region}
14533: @findex comment-region @r{(V19)}
14534: The @code{comment-region} command adds comment delimiters to the lines
14535: that start in the region, thus commenting them out. With a negative
14536: argument, it deletes comment delimiters from the lines in the
14537: region---this is the inverse of the effect of @code{comment-region}
14538: without an argument.
14539:
14540: With a positive argument, @code{comment-region} adds comment delimiters
14541: but duplicates the last character of the comment start sequence as many
14542: times as the argument specifies. This is a way of calling attention to
14543: the comment. In Lisp, you should use an argument of at least two, because
14544: the indentation convention for single semicolon comments does not leave
14545: them at the beginning of a line.
14546:
14547: @item @kbd{M-x super-apropos}
14548: @findex super-apropos @r{(V19)}
14549: This command is like @code{apropos} except that it searches for a
14550: regular expression instead of merely a substring.
14551:
14552: @findex apropros @r{(V19)}
14553: @kindex C-h a @r{(V19)}
14554: If you use a prefix argument (regardless of its value) with
14555: @code{apropos} or @code{super-apropos}, they also search documentation
14556: strings for matches as well as symbol names. The prefix argument also
14557: controls looking up and printing the key bindings of all commands.
14558:
14559: @item @kbd{M-x diff}
14560: @findex diff @r{(V19)}
14561: @vindex diff-switches @r{(V19)}
14562: This new command compares two files, displaying the differences in an
14563: Emacs buffer. The options for the @code{diff} program come from the
14564: variable @code{diff-switches}, whose value should be a string.
14565:
14566: The buffer of differences has Compilation mode as its major mode, so you
14567: can use @kbd{C-x `} to visit successive changed locations in the two
14568: source files, or you can move to a particular hunk of changes and type
14569: @kbd{C-c C-c} to move to the corresponding source. You can also use the
14570: other special commands of Compilation mode: @key{SPC} and @key{DEL} for
14571: scrolling, and @kbd{M-p} and @kbd{M-n} for cursor motion.
14572:
14573: @item @kbd{M-x diff-backup}
14574: @findex diff-backup @r{(V19)}
14575: The command @code{diff-backup} compares a specified file with its most
14576: recent backup. If you specify the name of a backup file,
14577: @code{diff-backup} compares it with the source file that it is a backup
14578: of.
14579: @end table
14580:
14581: @node Search Changes
14582: @section Changes in Incremental Search
14583:
14584: The most important change in incremental search is that @key{RET} now
14585: terminates a search, and @key{ESC} does not. The other changes are
14586: useful, but not vital to know about.
14587:
14588: @cindex Incremental search in V19
14589: @findex isearch @r{(V19)}
14590: @itemize @bullet
14591: @item
14592: The character to terminate an incremental search is now @key{RET}. This
14593: is for compatibility with the way most other arguments are read.
14594:
14595: To search for a newline in an incremental search, type @key{LFD} (also
14596: known as @kbd{C-j}).
14597:
14598: (This change is somewhat of an experiment; it might be taken back by
14599: the time Emacs 19 is really released.)
14600:
14601: @item
14602: Incremental search now maintains a ring of previous search strings. Use
14603: @kbd{M-p} and @kbd{M-n} to move through the ring to pick a search string
14604: to reuse. These commands leave the selected search ring element in the
14605: minibuffer, where you can edit it. Type @key{RET} to finish editing and
14606: search for the chosen string.
14607:
14608: @item
14609: When there is an upper-case letter in the search
14610: string, then the search is case sensitive.
14611:
14612: @item
14613: Incremental search is now implemented as a major mode. When you type
14614: @kbd{C-s}, it switches temporarily to a different keymap which defines
14615: each key to do what it ought to do for incremental search. This has
14616: next to no effect on the user-visible behavior of searching, but makes
14617: it easier to customize that behavior.
14618: @end itemize
14619:
14620: @node Filling Changes
14621: @section Changes in Fill Commands
14622:
14623: @itemize @bullet
14624: @item
14625: @findex fill-individual-paragraphs @r{(V19)}
14626: @code{fill-individual-paragraphs} now has two modes. Its default mode
14627: is that any change in indentation starts a new paragraph. The alternate
14628: mode is that only separator lines separate paragraphs; this can handle
14629: paragraphs with extra indentation on the first line. To select the
14630: alternate mode, set @code{fill-individual-varying-indent} to a
14631: non-@code{nil} value.
14632:
14633: @item
14634: @cindex Adaptive Fill mode
14635: @findex fill-region-as-paragraph @r{(V19)}
14636: Filling is now partially controlled by a new minor mode, Adaptive Fill
14637: mode. When this mode is enabled (and it is enabled by default), if you
14638: use @code{fill-region-as-paragraph} on an indented paragraph and you
14639: don't have a fill prefix, it uses the indentation of the second line of
14640: the paragraph as the fill prefix.
14641:
14642: Adaptive Fill mode doesn't have much effect on @kbd{M-q} in most major
14643: modes, because an indented line will probably count as a paragraph
14644: starter and thus each line of an indented paragraph will be considered
14645: a paragraph of its own.
14646:
14647: @item
14648: @kindex M-q @r{(C mode in V19)}
14649: @findex c-fill-paragraph @r{(V19)}
14650: @kbd{M-q} in C mode now runs @code{c-fill-paragraph}, which is designed
14651: for filling C comments. (We assume you don't want to fill the actual C
14652: code in a C program.)
14653: @end itemize
14654:
14655: @node TeX Mode Changes
14656: @section Changes in @TeX{} Mode
14657:
14658: @cindex Tex mode in V19
14659: @kindex C-c @{ @r{(TeX mode in V19)}
14660: @kindex C-c @} @r{(TeX mode in V19)}
14661: The old @TeX{} mode bindings of @kbd{M-@{} and @kbd{M-@}} have been
14662: moved to @kbd{C-c @{} and @kbd{C-c @}}. (These commands are
14663: @code{up-list} and @code{tex-insert-braces}; they are the @TeX{}
14664: equivalents of @kbd{M-(} and @kbd{M-)}.)
14665:
14666: @c !!! following generates acceptable underfull hbox
14667: @kindex C-c C-e @r{(TeX mode in V19)}
14668: @kindex C-c C-o @r{(TeX mode in V19)}
14669: @findex tex-latex-block @r{(V19)}
14670: @findex tex-close-latex-block @r{(V19)}
14671: The new command @kbd{C-c C-o} (@code{tex-latex-block}) inserts a
14672: matching @samp{\begin}--@samp{\end} pair. The new command @kbd{C-c C-e}
14673: (@code{tex-close-latex-block}) inserts a matching @samp{\end} for the
14674: last unterminated @samp{\begin}.
14675:
14676: @kindex C-c @key{TAB} @r{(TeX mode in V19)}
14677: @findex tex-bibtex-file @r{(V19)}
14678: You can run Bib@TeX{} on the current file using @kbd{C-c @key{TAB}}
14679: (@code{tex-bibtex-file}).
14680:
14681: @kindex C-c C-v @r{(TeX mode in V19)}
14682: @findex tex-view @r{(V19)}
14683: There is a new command @kbd{C-c C-v} (@code{tex-view}) for running a
14684: DVI previewer.
14685:
14686: @vindex tex-directory @r{(V19)}
14687: You can specify the directory to use for running @TeX{} by setting the
14688: variable @code{tex-directory}. @code{"."} is the default value. If
14689: your environment variable @code{TEXINPUTS} contains relative directory
14690: names, or if your files contains @samp{\input} commands with relative
14691: file names, then @code{tex-directory} @emph{must} be @code{"."} or you
14692: will get the wrong results. Otherwise, it is safe to specify some other
14693: directory, such as @file{/tmp}.
14694:
14695: There is now a third variant of @TeX{} mode, for Sli@TeX{}. This is in
14696: addition to the variants for plain @TeX{} and La@TeX{}. As before, the
14697: correct variant is chosen automatically when you visit a file.
14698:
14699: @node Shell Changes
14700: @section Changes in Shell Mode
14701:
14702: @cindex Shell mode in V19
14703: Shell mode has been completely replaced with a new implementation.
14704: The basic idea is the same: Emacs runs a subshell, and all input
14705: and output to the subshell go through the shell buffer. But the
14706: special commands of Shell mode have been redesigned.
14707:
14708: @table @kbd
14709: @item @key{TAB}
14710: @kindex @key{TAB} @r{(Shell mode in V19)}
14711: @findex comint-dynamic-complete @r{(V19)}
14712: Complete the file name before point in the shell buffer
14713: (@code{comint-dynamic-complete}).
14714:
14715: @item M-?
14716: @kindex M-? @r{(Shell mode in V19)}
14717: @findex comint-dynamic-list-completions @r{(V19)}
14718: To get a list of all possible completions of the file name before, type
14719: @kbd{M-?} (@code{comint-dynamic-list-completions}).
14720:
14721: @item M-p
14722: @itemx M-n
14723: @kindex M-p @r{(Shell mode in V19)}
14724: @kindex M-n @r{(Shell mode in V19)}
14725: @findex comint-next-input @r{(V19)}
14726: @findex comint-previous-input @r{(V19)}
14727: There is a new convenient history mechanism for repeating previous
14728: shell inputs. Use the command @kbd{M-p} (@code{comint-previous-input}) to
14729: recall the last input; it copies the text of that input to the place
14730: where you are editing. If you repeat @w{@kbd{M-p}}, it replaces the copied
14731: input with successively earlier inputs. @kbd{M-n} is similar but goes in the
14732: opposite direction, towards the present (@code{comint-next-input}).
14733:
14734: When you find the previous input you want, you can resubmit it by typing
14735: @key{RET}, or you can edit it first and then resubmit it if you wish.
14736:
14737: These shell history commands operate outside the minibuffer, but they
14738: are completely analogous to the minibuffer history commands.
14739:
14740: @item M-r
14741: @itemx M-s
14742: @kindex M-r @r{(Shell mode in V19)}
14743: @kindex M-s @r{(Shell mode in V19)}
14744: @findex comint-previous-matching-input @r{(V19)}
14745: @findex comint-next-matching-input @r{(V19)}
14746: You can also use @kbd{M-r} and @kbd{M-s} to search for (respectively)
14747: earlier or later inputs starting with a given string. First type the
14748: string, then type @kbd{M-r} (@code{comint-previous-matching-input}) to
14749: yank a previous input from the history which starts with that string.
14750: You can repeat @kbd{M-r} to find successively earlier inputs starting
14751: with the same string.
14752:
14753: You can start moving in the opposite direction (toward more recent
14754: inputs) by typing @kbd{M-s} (@code{comint-next-matching-input}) instead
14755: of @kbd{M-r}. As long as you don't use any commands except @kbd{M-r}
14756: and @kbd{M-s}, they keep using the same string that you had entered
14757: initially.
14758:
14759: These commands serve a purpose similar to that of @kbd{M-r} and
14760: @kbd{M-s} in the minibuffer, but do not work in quite the same way. We
14761: may change the interface of these commands, as well as that of the
14762: analogous minibuffer commands; one goal will be to make the two sets of
14763: commands compatible. But we haven't yet figured out which of the
14764: possible interfaces is best. To find out what interface is actually
14765: supported in Emacs 19, type @kbd{C-h f comint-previous-matching-input
14766: @key{RET}}.
14767:
14768: @item C-c C-o
14769: @kindex C-c C-o @r{(Shell mode in V19)}
14770: @findex comint-kill-output @r{(V19)}
14771: Kill the last batch of output from a shell command
14772: (@code{comint-kill-output}). This is useful if a shell command spews
14773: out lots of output that just gets in the way.
14774:
14775: @item C-c C-r
14776: @kindex C-c C-r @r{(Shell mode in V19)}
14777: @findex comint-show-output @r{(V19)}
14778: Scroll to display the
14779: beginning of the last batch of output at the top of the window; it also
14780: moves the cursor there (@code{comint-show-output}).
14781:
14782: @item C-a
14783: @kindex C-a @r{(Shell mode in V19)}
14784: If you type @kbd{C-a} on a line that starts with a shell prompt, it
14785: moves to the end of the prompt, not to the very beginning of the line.
14786:
14787: @item C-d
14788: @kindex C-d @r{(Shell mode in V19)}
14789: Typed at the end of the shell buffer, @kbd{C-d} sends EOF to the
14790: subshell. Typed at any other position in the buffer, @kbd{C-d}
14791: deletes a character as usual.
14792:
14793: @item M-x dirs
14794: @findex dirs @r{(V19)}
14795: If Emacs gets confused while trying to track changes in the shell's
14796: current directory, type @kbd{M-x dirs} to re-synchronize.
14797:
14798: @item M-x send-invisible
14799: @findex send-invisible @r{(V19)}
14800: This command reads a line of text without echoing it, and sends it to
14801: the shell.
14802:
14803: @item M-x comint-continue-subjob
14804: @findex comint-continue-subjob @r{(V19)}
14805: If you accidentally suspend your process, use this command to continue it.
14806: @end table
14807:
14808: @node Spell Changes
14809: @section Changes in Spell Checking
14810:
14811: @cindex Spell checking in V19
14812: @cindex @code{ispell} program @r{(V19)}
14813: @findex kill-ispell @r{(V19)}
14814: Emacs 19 uses the Ispell program for spelling correction instead of the
14815: Unix spell program. Ispell has many advantages; one is that it can be
14816: started the first time you check a word, and left running thereafter,
14817: which makes further checking much faster. If you want to get rid of the
14818: Ispell process, use @kbd{M-x kill-ispell}.
14819:
14820: @findex ispell-buffer @r{(V19)}
14821: @findex ispell-region @r{(V19)}
14822: To check the entire current buffer, use @kbd{M-x ispell-buffer}. Use
14823: @kbd{M-x ispell-region} to check just the current region.
14824:
14825: @kindex M-$ @r{(V19)}
14826: Ispell commands often involve interactive replacement of words.
14827: You can interrupt the interactive replacement with @kbd{C-g}.
14828: You can restart it again afterward with @kbd{C-u M-$}.
14829:
14830: Interactive replacement shows you one misspelling at a time and asks you
14831: what to do. To answer, type one of the following characters:
14832:
14833: @table @kbd
14834: @item @var{digit}
14835: Replace the word (this time) with one of the displayed near-misses.
14836: The digit you use says which near-miss to use.
14837:
14838: @item a
14839: Accept this word this time.
14840:
14841: @item i
14842: Insert this word in your private dictionary
14843: so that Ispell will consider it correct it from now on.
14844:
14845: @item r
14846: Replace the word this time with a string typed by you.
14847: @end table
14848:
14849: When the Ispell process starts, it reads your private dictionary which
14850: is the file @file{~/ispell.words}. Words that you ``insert'' with the
14851: @kbd{i} command are added to that file, but not right away---only at the
14852: end of the interactive replacement procedure.
14853:
14854: @c !!! Written verbosely to avoid overfull hbox.
14855: @findex reload-ispell @r{(V19)}
14856: Use the @kbd{M-x reload-ispell} command
14857: to reload your private dictionary from
14858: @file{~/ispell.words} if you edit the file outside of Ispell.
14859:
14860: @node Mail Changes
14861: @section Changes in Mail Reading and Sending
14862:
14863: @cindex Mail mode in V19
14864: @samp{%} is now a word-separator character in Mail mode. This is because
14865: that character frequently appears in addresses.
14866:
14867: @vindex mail-signature @r{(V19)}
14868: If you set the variable @code{mail-signature} non-@code{nil}, then
14869: @code{mail} inserts the contents of your @file{.signature} file
14870: automatically when it initializes a mail buffer. If you don't want your
14871: signature in a particular message, just delete it from the buffer before
14872: you send the message.
14873:
14874: @vindex mail-yank-prefix @r{(V19)}
14875: You can specify the text to insert at the beginning of each line when
14876: you use @kbd{C-c C-y} to yank the message you are replying to. Set
14877: @code{mail-yank-prefix} to the desired string. A value of @code{nil}
14878: (the default) means to use indentation, as in Emacs 18. If you use
14879: @kbd{C-u} by itself as the prefix argument to @kbd{C-c C-y}, then it
14880: does not insert anything at the beginning of the lines, regardless of
14881: the value of @code{mail-yank-prefix}.
14882:
14883: @findex unrmail
14884: You can easily convert an Rmail file to system mailbox format with the
14885: command @code{unrmail}. This command reads two arguments, the name of
14886: the Rmail file to convert, and the name of the new mailbox file.
14887: The Rmail file is unchanged by this command.
14888:
14889: @cindex Rmail in V19
14890: Rmail now initially positions you at the first message in the Rmail file
14891: that you have not seen. This may not be a message that just arrived; it
14892: may have arrived in a previous session during which you did not select
14893: it. You can then read all the unseen messages going forwards.
14894:
14895: @kindex C-M-m @r{(Rmail in V19)}
14896: @findex rmail-retry-failure @r{(V19)}
14897: When a message that you sent ``bounces'' back to you, you can retry
14898: sending it by typing @kbd{C-M-m} (@code{rmail-retry-failure}) on the
14899: failure message.
14900:
14901: @findex rmail-resend @r{(V19)}
14902: By contrast, the new command @kbd{M-x rmail-resend} is used for
14903: forwarding a message and marking it as ``resentby'' you,
14904: with the special header fields @samp{Resent-by:} and @samp{Resent-to:}.
14905:
14906: @kindex < @r{(Rmail in V19)}
14907: Another new Rmail command is @kbd{<}, which moves to the first message.
14908: (This is for symmetry with @kbd{>}.) @kbd{<} is actually an alias for
14909: @kbd{j}.
14910:
14911: @kindex e @r{(Rmail in V19)}
14912: @kindex x @r{(Rmail in V19)}
14913: @c !!!! overfull hbox cured by ugly change
14914: @kbd{e} (@code{rmail-edit-current-message}) is now the command
14915: to edit a message. To expunge, type @kbd{x}. We know
14916: this will surprise people some of the time, but the surprise will not be
14917: disastrous---if you type @kbd{e} meaning to expunge, just type @kbd{C-c
14918: C-c} to leave Rmail Edit mode, and then type @kbd{x}.
14919:
14920: @vindex rmail-output-file-alist
14921: The variable @code{rmail-output-file-alist} now controls the default
14922: for the file to output a message to.
14923:
14924: @kindex C-n @r{(Rmail summary in V19)}
14925: @kindex C-p @r{(Rmail summary in V19)}
14926: @kindex M-n @r{(Rmail summary in V19)}
14927: @kindex M-p @r{(Rmail summary in V19)}
14928: @kindex p @r{(Rmail summary in V19)}
14929: @kindex n @r{(Rmail summary in V19)}
14930: In the Rmail summary, @kbd{C-n} and @kbd{C-p} are now ordinary cursor
14931: motion commands. To move in the summary @emph{and} select a new
14932: message, use @kbd{n} and @kbd{p} (which skip deleted messages) or
14933: @kbd{M-n} and @kbd{M-p} (which stop at all messages). These are, of
14934: course, the same commands you would use in the Rmail buffer.
14935:
14936: @node Tags Changes
14937: @section Changes in Tags Commands
14938:
14939: @cindex tags in V19
14940: @kindex M-. @r{(V19)}
14941: @kbd{M-.} (@code{find-tag}) and the other commands to find a tag now
14942: look first for an exact match in the tags table, and try substring
14943: matches only afterward.
14944:
14945: Another change in @kbd{M-.} is that it has no effect on what @kbd{M-,}
14946: will do subsequently. You can no longer use @kbd{M-,} to find the next
14947: similar tag; instead, use @kbd{M-.} with a prefix argument.
14948:
14949: @findex find-tag-regexp @r{(V19)}
14950: The new command @code{find-tag-regexp} successively visits the tags that
14951: match a specified regular expression.
14952:
14953: You can now use more than one tags table. Using @code{visit-tags-table}
14954: to load a new tags table does not discard the other tables previously
14955: loaded. The other tags commands use all the tags tables that are
14956: loaded; the first one they use is the one that mentions the current
14957: visited file.
14958:
14959: You can specify a precise list of tags tables by setting the variable
14960: @code{tags-table-list} to a list of strings, like this:
14961:
14962: @c keep this on two lines for formatting in smallbook
14963: @example
14964: @group
14965: (setq tags-table-list
14966: '("~/emacs" "/usr/local/lib/emacs/src"))
14967: @end group
14968: @end example
14969:
14970: @noindent
14971: This tells @code{find-tag} to look at the @file{TAGS} files in your
14972: @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
14973: directory. The order depends on which file you are in and which tags
14974: table mentions that file, as explained above.
14975:
14976: @kindex M-@key{TAB} @r{(V19)}
14977: You can now use the tags table for completion of names during ordinary
14978: editing. The command @kbd{M-@key{TAB}} (except in Emacs Lisp and Lisp
14979: Interaction modes) completes the identifier in the buffer before point,
14980: using the set of all tags as the list of possible completions.
14981:
14982: @code{tags-query-replace} and @code{tags-search} now create buffers only
14983: temporarily for the files that they have to search (those which are not
14984: already visited in Emacs buffers). If one of these files contains a
14985: match for the search pattern, then its buffer continues to exist;
14986: otherwise, it is killed.
14987:
14988: @node Info Changes
14989: @section Changes in Info
14990:
14991: @cindex Info mode in V19
14992: There are new commands in Info mode.
14993:
14994: @c I don't think individual index entries for these commands
14995: @c are useful. I don't think anyone would ever look them up.--RMS.
14996: @table @kbd
14997: @item ]
14998: Move forward a node, going up and down levels as needed in a depth-first
14999: tree walk. This command treats all the nodes in the file as forming a
15000: single sequence in which the ``children'' of a node follow that node.
15001: It is the equivalent of reading a printed manual sequentially.
15002:
15003: @item [
15004: Similar, but move backward.
15005:
15006: @item <
15007: Move to the top node of the current Info file.
15008:
15009: @item >
15010: Move to the last node of the file.
15011:
15012: @c ??? Not done yet
15013: @item @key{SPC}
15014: Scroll through this node, or advance to the next node in depth-first
15015: order (like @kbd{]}).
15016:
15017: @c ??? Not done yet
15018: @item i @var{string} @key{RET}
15019: Move to the node associated with @var{string} in the index or indices of
15020: this manual. If there is more than one match for @var{string}, the
15021: @kbd{i} command finds the first match.
15022:
15023: @c ??? Not done yet
15024: @item ,
15025: Find the next match for the string in the previous @kbd{i} command, and
15026: go to that node.
15027: @end table
15028:
15029: If you click the middle mouse button near a cross-reference,
15030: menu item or node pointer while in Info, you will go to the node
15031: which is referenced.
15032:
15033: @vindex Info-directory-list @r{(V19)}
15034: @vindex INFOPATH
15035: The variable @code{Info-directory-list} specifies a list of directory
15036: names that contain Info files. Each time Info looks for an Info file,
15037: it searches all these directories. This makes it easy to install the
15038: Info files that come with various packages. You can specify the path
15039: with the environment variable @code{INFOPATH}.
15040:
15041: @node Dired Changes
15042: @section Changes in Dired
15043:
15044: @cindex Dired in V19
15045: Dired has many new features which allow you to do these things:
15046:
15047: @itemize @bullet
15048: @item
15049: Make distinguishable types of marks for different operations.
15050:
15051: @item
15052: Rename, copy, or make links to many files at once.
15053:
15054: @item
15055: Display contents of subdirectories in the same Dired buffer as the
15056: parent directory.
15057: @end itemize
15058:
15059: @menu
15060: * Marks in Dired:: Flagging for deletion vs marking for other actions.
15061: * Multiple Files:: How to copy, rename, print, compress, etc.
15062: either one file or several files.
15063: * Shell Commands in Dired:: Running a shell command on the marked files.
15064: * Dired Regexps:: Using patterns to rename multiple files.
15065: * Dired Case Conversion:: Converting file names to upper or lower case.
15066: * Comparison in Dired:: Running `diff' by way of Dired.
15067: * Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
15068: * Hiding Subdirectories:: Making subdirectories visible or invisible.
15069: * Editing Dired Buffer:: Discarding lines for files of no interest.
15070: * Dired and Find:: Using `find' to select the files for Dired to show.
15071: @end menu
15072:
15073: @node Marks in Dired
15074: @subsection Setting and Clearing Marks
15075:
15076: @cindex Marks in Dired (V19)
15077: There are now two kinds of marker that you can put on a file in Dired:
15078: @samp{D} for deletion, and @samp{*} for any other kind of operation.
15079: The @kbd{x} command deletes only files marked with @samp{D}, and most
15080: other Dired commands operate only on the files marked with @samp{*}.
15081:
15082: To mark files with @samp{D} (also called @dfn{flagging} the files), you
15083: can use @kbd{d} as usual. Here are some commands for marking with
15084: @samp{*} (and also for unmarking):
15085:
15086: @table @kbd
15087: @kindex m @r{(Dired, V19)}
15088: @findex dired-mark @r{(V19)}
15089: @item m
15090: Mark the current file with @samp{*}, for an
15091: operation other than deletion (@code{dired-mark}).
15092:
15093: @kindex * @r{(Dired, V19)}
15094: @findex dired-mark-executables @r{(V19)}
15095: @item *
15096: Mark all executable files (@code{dired-mark-executables}).
15097: With a prefix argument, unmark all those files.
15098:
15099: @item @@
15100: @kindex @@ @r{(Dired, V19)}
15101: @findex dired-mark-symlinks @r{(V19)}
15102: Mark all symbolic links (@code{dired-mark-symlinks}). With a
15103: prefix argument, unmark all those files.
15104:
15105: @item /
15106: @kindex / @r{(Dired, V19)}
15107: @findex dired-mark-directories @r{(V19)}
15108: Mark all files which are actually directories, except for @file{.} and
15109: @file{..} (@code{dired-mark-directories}). With a prefix argument,
15110: unmark all those files.
15111:
15112: @item M-@key{DEL}
15113: @kindex M-@key{DEL} @r{(Dired, V19)}
15114: @findex dired-unmark-all-files @r{(V19)}
15115: Remove a specific or
15116: all marks from every file (@code{dired-unmark-all-files}).
15117: With an argument, query for each marked file.
15118: Type your help character, usually @kbd{C-h}, at that time for help.
15119:
15120: @item c @var{old} @var{new}
15121: @kindex c @r{(Dired, V19)}
15122: @findex dired-change-marks @r{(V19)}
15123: Replace all marks that use the character @var{old} with marks that use
15124: the character @var{new}. You can use almost any character as a mark
15125: character by means of this command, to distinguish various classes of
15126: files. If @var{old} is @samp{ }, then the command operates on all
15127: unmarked files; if @var{new} is @samp{ }, then the command unmarks the
15128: files it acts on.
15129:
15130: To illustrate the power of this command, here is how to put @samp{*}
15131: marks on all the files that were unmarked, while unmarking all those
15132: that had @samp{*} marks:
15133:
15134: @example
15135: c * t c SPC * c t SPC
15136: @end example
15137: @end table
15138:
15139: @node Multiple Files
15140: @subsection Operating on Multiple Files
15141:
15142: @cindex Multiple file ops, Dired (V19)
15143: @cindex Dired multiple file ops (V19)
15144: The Dired commands to operate on files (rename them, copy them, and so
15145: on) have been generalized to work on multiple files. There are also
15146: some additional commands in this series.
15147:
15148: All of these commands use the same convention to decide which files to
15149: manipulate:
15150:
15151: @itemize @bullet
15152: @item
15153: If you give the command a numeric prefix argument @var{n}, it operates
15154: on the next @var{n} files, starting with the current file.
15155:
15156: @item
15157: Otherwise, if there are marked files, the commands operate on all the
15158: marked files.
15159:
15160: @item
15161: Otherwise, the command operates on the current file only.
15162: @end itemize
15163:
15164: Here are the commands that operate on multiple files in this way:
15165:
15166: @table @kbd
15167: @findex dired-do-copy @r{(V19)}
15168: @kindex C @r{(Dired, V19)}
15169: @item C
15170: Copy the specified files (@code{dired-do-copy}). You must
15171: specify a directory to copy into, or (if copying a single file) a new
15172: name.
15173:
15174: @vindex dired-copy-preserve-time @r{(V19)}
15175: If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with
15176: this command sets the modification time of the new file to be the same
15177: as that of the old file.
15178:
15179: @findex dired-do-rename @r{(V19)}
15180: @kindex R @r{(Dired, V19)}
15181: @item R
15182: Rename the specified files (@code{dired-do-rename}). You must
15183: specify a directory to rename into, or (if renaming a single file) a new
15184: name.
15185:
15186: Dired automatically changes the visited file name of buffers associated
15187: with renamed files so that they refer to the new names.
15188:
15189: @findex dired-do-hardlink @r{(V19)}
15190: @kindex H @r{(Dired, V19)}
15191: @item H
15192: Make hard links to the specified
15193: files (@code{dired-do-hardlink}).
15194: You must specify a directory to make the links in, or (if making
15195: just one link) the name to give the link.
15196:
15197: @findex dired-do-symlink @r{(V19)}
15198: @kindex S @r{(Dired, V19)}
15199: @item S
15200: Make symbolic links to the specified
15201: files (@code{dired-do-symlink}).
15202: You must specify a directory to make the links in, or (if making
15203: just one link) the name to give the link.
15204:
15205: @findex dired-do-chmod @r{(V19)}
15206: @kindex M @r{(Dired, V19)}
15207: @item M
15208: Change the mode (also called ``permission bits'')
15209: of the specified files (@code{dired-do-chmod}). This calls the
15210: @code{chmod} program, so you can describe the desired mode change with
15211: any argument that @code{chmod} would handle.
15212:
15213: @findex dired-do-chgrp @r{(V19)}
15214: @kindex G @r{(Dired, V19)}
15215: @item G
15216: Change the group of the specified files (@code{dired-do-chgrp}).
15217:
15218: @vindex dired-chown-program @r{(V19)}
15219: @findex dired-do-chown @r{(V19)}
15220: @kindex O @r{(Dired, V19)}
15221: @item O
15222: Change the owner of the specified
15223: files (@code{dired-do-chown}).
15224: (On most systems, only the superuser can do this.)
15225:
15226: The variable @code{dired-chown-program} specifies the name of the
15227: program to use to do the work (different systems put @code{chown} in
15228: different places.
15229:
15230: @findex dired-do-compress @r{(V19)}
15231: @kindex Z @r{(Dired, V19)}
15232: @item Z
15233: @c !!! Rewrote to prevent overfull hbox.
15234: Compress or uncompress the specified files.
15235: If the file appears to be a compressed file, it is uncompressed;
15236: otherwise, it is compressed (@code{dired-do-compress}).
15237:
15238: @findex dired-do-load @r{(V19)}
15239: @kindex L @r{(Dired, V19)}
15240: @item L
15241: Load the specified Emacs Lisp files (@code{dired-do-load}).
15242:
15243: @findex dired-do-byte-compile @r{(V19)}
15244: @kindex B @r{(Dired, V19)}
15245: @item B
15246: Byte compile the specified Emacs Lisp files
15247: (@code{dired-do-byte-compile}).
15248:
15249: @findex dired-do-print @r{(V19)}
15250: @kindex P @r{(Dired, V19)}
15251: @item P
15252: Print the specified files (@code{dired-do-print}). This command uses
15253: the variables @code{lpr-command} and @code{lpr-switches} just as
15254: @code{lpr-file} does (@pxref{Hardcopy}).
15255: @end table
15256:
15257: @node Shell Commands in Dired
15258: @subsection Shell Commands in Dired
15259: @cindex shell commands, Dired V19
15260:
15261: @findex dired-do-shell-command @r{(V19)}
15262: @kindex ! @r{(Dired, V19)}
15263: The dired command @kbd{!} (@code{dired-do-shell-command}) reads a shell
15264: command string in the minibuffer and runs the shell command on all the
15265: specified files. There are two ways of applying a shell command to
15266: multiple files:
15267:
15268: @itemize @bullet
15269: @item
15270: If you use @samp{*} in the shell command, then it runs just once, with
15271: the list of file names substituted for the @samp{*}.
15272:
15273: Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire
15274: list of file names, putting them into one tar file @file{foo.tar}. The
15275: file names are inserted in the order that they appear in the Dired
15276: buffer.
15277:
15278: @item
15279: If the command string doesn't contain @samp{*}, then it runs once
15280: @emph{for each file}, with the file name attached at the end.
15281:
15282: For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each
15283: file.
15284: @end itemize
15285:
15286: What if you want to run the shell command once for each file but with
15287: the file name inserted in the middle? Or if you want to use the file
15288: names in a more complicated fashion? Use a shell loop. For example,
15289: this shell command would run @code{uuencode} on each of the specified
15290: files, writing the output into a corresponding @file{.uu} file:
15291:
15292: @example
15293: for file in *; uuencode $file $file >$file.uu; done
15294: @end example
15295:
15296: The working directory for the shell command is the top level directory
15297: of the Dired buffer.
15298:
15299: The @kbd{!} command does not attempt to update the Dired buffer to show
15300: new or modified files, because it doesn't know what those files might
15301: be. Type @kbd{g} to update the Dired buffer.
15302:
15303: @node Dired Regexps
15304: @subsection Regular Expression File Name Substitution
15305:
15306: Here are commands that select files according to a regular
15307: expression:
15308:
15309: @table @kbd
15310: @findex dired-mark-files-regexp @r{(V19)}
15311: @kindex % m @r{(Dired, V19)}
15312: @item % m @var{regexp} @key{RET}
15313: Mark all files whose names match the regular expression @var{regexp}
15314: (@code{dired-mark-files-regexp}).
15315:
15316: Only the non-directory part of the file name is used in matching. Use
15317: @samp{^} and @samp{$} to anchor matches. Exclude subdirs by hiding
15318: them (@pxref{Hiding Subdirectories}).
15319:
15320: @item % d @var{regexp} @key{RET}
15321: @findex dired-flag-files-regexp @r{(V19)}
15322: @kindex % d @r{(Dired, V19)}
15323: Flag for deletion all files whose names match the regular expression
15324: @var{regexp} (@code{dired-flag-files-regexp}).
15325:
15326: @item % R @var{from} @key{RET} @var{to} @key{RET}
15327: @kindex % R @r{(Dired, V19)}
15328: @findex dired-do-rename-regexp @r{(V19)}
15329: @itemx % C @var{from} @key{RET} @var{to} @key{RET}
15330: @kindex % C @r{(Dired, V19)}
15331: @findex dired-do-copy-regexp @r{(V19)}
15332: @itemx % H @var{from} @key{RET} @var{to} @key{RET}
15333: @kindex % H @r{(Dired, V19)}
15334: @findex dired-do-hardlink-regexp @r{(V19)}
15335: @itemx % S @var{from} @key{RET} @var{to} @key{RET}
15336: @kindex % S @r{(Dired, V19)}
15337: @findex dired-do-symlink-regexp @r{(V19)}
15338: These four commands rename, copy, make hard links and make soft links,
15339: in each case computing the new name by regular expression substitution
15340: from the name of the old file.
15341: @end table
15342:
15343: The four regular expression substitution commands effectively perform
15344: @code{query-replace-regexp} on the selected file names in the Dired
15345: buffer. They read two arguments: a regular expression @var{from}, and a
15346: substitution pattern @var{to}. Each selected file name is matched
15347: against the regular expression, and then the part which matched is
15348: replaced with the substitution pattern. You can use @samp{\&} and
15349: @samp{\@var{digit}} in the substitution pattern to refer to all or part
15350: of the old file name.
15351: @c ??? xref{???query replace???}.
15352:
15353: Thus, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each selected file
15354: by prepending @samp{x-} to its name. The inverse of this is to remove
15355: @samp{x-} from the front of each file name. One way to do that is
15356: @kbd{% R ^x-.*$ @key{RET} \& @key{RET}}; another is @w{@kbd{% R ^x-
15357: @key{RET} @key{RET}}}. (Use @samp{^} and @samp{$} to anchor matches that
15358: should span the whole filename.)
15359:
15360: If the regular expression matches more than once in a file name,
15361: only the first match is replaced.
15362:
15363: Normally, the replacement process does not consider the directory names;
15364: it operates on the file name within the directory. If you specify a
15365: prefix argument of zero, then replacement affects the entire file name.
15366:
15367: Often you will want to apply the command to all files matching the same
15368: @var{regexp} that you use in the command. To do this, mark those files
15369: with @w{@kbd{% m @var{regexp} @key{RET}}}, then use the same regular
15370: expression in @kbd{% R}. To make this easier, @kbd{% R} uses the
15371: last regular expression specified in a @kbd{%} command as a default.
15372:
15373: @node Dired Case Conversion
15374: @subsection Dired Case Conversion
15375: @cindex case conversion of file names @r{(V19)}
15376:
15377: Here are commands for changing the case of selected files:
15378:
15379: @table @code
15380: @findex dired-upcase @r{(V19)}
15381: @kindex % u @r{(Dired, V19)}
15382: @item % u
15383: Rename each of the selected files to an
15384: upper case name (@code{dired-upcase}).
15385:
15386: @item % l
15387: @findex dired-downcase @r{(V19)}
15388: @kindex % l @r{(Dired, V19)}
15389: Rename each of the selected files to
15390: a lower case name (@code{dired-downcase}).
15391: @end table
15392:
15393: @node Comparison in Dired
15394: @subsection File Comparison with Dired
15395:
15396: Here are two commands to run @code{diff} on selected files:
15397:
15398: @table @kbd
15399: @findex dired-diff @r{(V19)}
15400: @kindex = @r{(Dired, V19)}
15401: @item =
15402: Compare the current file with another file (the file at the mark), by
15403: running the @code{diff} program (@code{dired-diff}). The file at the
15404: mark is the first argument of @code{diff}, and the file at point is the
15405: second argument.
15406:
15407: @findex dired-backup-diff @r{(V19)}
15408: @kindex M-= @r{(Dired, V19)}
15409: @item M-=
15410: Compare the current file with its
15411: backup file (@code{dired-backup-diff}).
15412: If there are several numerical backups, use the most
15413: recent one. If this file is a backup, compare it to its
15414: original. The backup file is the first file given to @code{diff}.
15415: @end table
15416:
15417: @node Subdirectories in Dired
15418: @subsection Subdirectories in Dired
15419: @cindex subdirectories in Dired (V19)
15420: @cindex expanding subdirectories in Dired (V19)
15421:
15422: One Dired buffer can now display more than one directory.
15423:
15424: The simplest way to include multiple directories is to specify the
15425: options @samp{-lR} for running @code{ls}. That produces a recursive
15426: directory listing showing all subdirectories, all within the same Dired
15427: buffer.
15428:
15429: But the simplest way is not usually the most convenient way---usually
15430: the complete recursive listing is more than you want. So there is a
15431: Dired command to insert a single subdirectory into the Dired buffer:
15432:
15433: @table @kbd
15434: @findex dired-maybe-insert-subdir @r{(V19)}
15435: @kindex i @r{(Dired, V19)}
15436: @item i
15437: @cindex inserted subdirectory (Dired, V19)
15438: @cindex expanded subdirectory (Dired, V19)
15439: @cindex in-situ subdirectory (Dired, V19)
15440: @cindex headerline (Dired, V19)
15441: Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line
15442: that describes a file which is a directory. It inserts the contents of
15443: that directory into the same Dired buffer. Inserted subdirectory
15444: contents follow the top-level directory of the Dired buffer, just as
15445: they do in @samp{ls -lR} output.
15446:
15447: If the subdirectory's contents are already present in the buffer, the
15448: @kbd{i} command just moves to it (type @kbd{l}
15449: (@code{dired-do-redisplay}) to refresh it). It sets the Emacs mark
15450: before moving, so @kbd{C-x C-x} takes you back to the old position in
15451: the buffer.
15452: @end table
15453:
15454: When you have subdirectories in the Dired buffer, you can use the page
15455: motion commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories.
15456:
15457: The following commands move up and down in the tree of directories
15458: in one Dired buffer:
15459:
15460: @table @kbd
15461: @findex dired-tree-up @r{(V19)}
15462: @kindex C-M-u @r{(Dired, V19)}
15463: @item C-M-u
15464: Go up to the parent directory's headerline (@code{dired-tree-up}).
15465:
15466: @findex dired-tree-down @r{(V19)}
15467: @kindex C-M-d @r{(Dired, V19)}
15468: @item C-M-d
15469: Go down in the tree, to the first
15470: subdirectory's headerline (@code{dired-tree-down}).
15471: @end table
15472:
15473: The following commands move forwards and backwards to subdirectory headerlines:
15474:
15475: @table @kbd
15476: @findex dired-next-subdir @r{(V19)}
15477: @kindex C-M-n @r{(Dired, V19)}
15478: @item C-M-n
15479: Go to next subdirectory headerline,
15480: regardless of level (@code{dired-next-subdir}).
15481:
15482: @findex dired-prev-subdir @r{(V19)}
15483: @kindex C-M-p @r{(Dired, V19)}
15484: @item C-M-p
15485: @c !!! added @* to prevent overfull hbox
15486: Go to previous subdirectory headerline,
15487: regardless of level@*
15488: (@code{dired-prev-subdir}).
15489: @end table
15490:
15491: @node Hiding Subdirectories
15492: @subsection Hiding Subdirectories
15493:
15494: @cindex hiding in Dired (Dired, V19)
15495: @dfn{Hiding} a subdirectory means to make it invisible, except for its
15496: headerline. Files inside a hidden subdirectory are never considered by
15497: Dired. For example, the commands to operate on marked files ignore
15498: files in hidden directories even if they are marked. Thus you can use
15499: hiding to temporarily exclude subdirectories from operations without
15500: having to remove the markers.
15501:
15502: The hiding commands toggle; that is they unhide what was hidden and vice
15503: versa.
15504:
15505: @table @kbd
15506: @item $
15507: @findex dired-hide-subdir @r{(V19)}
15508: @kindex $ @r{(Dired, V19)}
15509: Hide or reveal the current subdirectory and move point to the next
15510: subdirectory (@code{dired-hide-subdir}). A prefix argument serves as
15511: a repeat count.
15512:
15513: @item M-$
15514: @findex dired-hide-all @r{(V19)}
15515: @kindex M-$ @r{(Dired, V19)}
15516: Hide all subdirectories, leaving only their header lines
15517: (@code{dired-hide-all}). Or, if any subdirectory is currently hidden,
15518: make all subdirectories visible again. You can use this command to get
15519: an overview in very deep directory trees or to move quickly to
15520: subdirectories far away.
15521: @end table
15522:
15523: @node Editing Dired Buffer
15524: @subsection Editing the Dired Buffer
15525:
15526: @table @kbd
15527: @kindex l @r{(Dired, V19)}
15528: @findex dired-do-redisplay @r{(V19)}
15529: @item l
15530: @c !!! rewrote to prevent overfull hbox
15531: Update the specified files in a Dired buffer. This means reading their
15532: current status from the file system and changing the buffer to reflect
15533: it properly (@code{dired-do-redisplay}).
15534:
15535: If you use this command on a subdirectory header line, it updates the
15536: contents of the subdirectory.
15537:
15538: @kindex g @r{(Dired, V19)}
15539: @findex revert-buffer @r{(Dired, V19)}
15540: @item g
15541: Update the entire contents of the Dired buffer
15542: (@code{revert-buffer}). Preserve all marks except for those on files
15543: that have vanished. Hidden subdirectories are updated but remain
15544: hidden.
15545:
15546: @kindex k @r{(Dired, V19)}
15547: @findex dired-do-kill-lines @r{(V19)}
15548: @item k
15549: Kill all marked lines (@code{dired-do-kill-lines}). With a prefix
15550: argument, kill that many lines starting with the current line.
15551:
15552: This command does not delete files; it just deletes text from the Dired
15553: buffer.
15554:
15555: If you kill the line for a file that is a directory, then its contents
15556: are also deleted from the buffer. Typing @kbd{C-u k} on the header line
15557: for a subdirectory is another way to delete a subdirectory from the
15558: Dired buffer.
15559:
15560: The @kbd{g} command will bring back any individual lines that you have
15561: killed in this way, but not subdirectories---you must use @kbd{i} to
15562: reinsert each subdirectory.
15563: @end table
15564:
15565: @node Dired and Find
15566: @subsection Dired and @code{find}
15567: @cindex @code{find} and Dired
15568:
15569: You can select a set of files for display in a Dired buffer more
15570: flexibly by using the @code{find} utility to choose the files.
15571:
15572: @findex find-name-dired
15573: To search for files with names matching a wildcard pattern use
15574: @code{find-name-dired}. Its arguments are @var{directory} and
15575: @var{pattern}. It selects all the files in @var{directory} or its
15576: subdirectories whose own names match @var{pattern}.
15577:
15578: The files thus selected are displayed in a Dired buffer in which the
15579: ordinary Dired commands are available.
15580:
15581: @findex find-grep-dired
15582: If you want to test the contents of files, rather than their names, use
15583: @code{find-grep-dired}. This command takes two minibuffer arguments,
15584: @var{directory} and @var{regexp}; it selects all the files in
15585: @var{directory} or its subdirectories that contain a match for
15586: @var{regexp}. It works by running @code{find} and @code{grep}.
15587:
15588: @findex find-dired
15589: The most general command in this series is @code{find-dired}, which lets
15590: you specify any condition that @code{find} can test. It takes two
15591: minibuffer arguments, @var{directory} and @var{find-args}; it runs
15592: @code{find} in @var{directory} with @var{find-args} as the
15593: arguments to @code{find} that specify which files to accept. To use this
15594: command, you need to know how to use @code{find}.
15595:
15596: @node GNUS
15597: @section GNUS
15598: @cindex @sc{gnus}
15599: @cindex reading netnews
15600:
15601: @sc{gnus} is an Emacs subsystem for reading and responding to netnews. You
15602: can use @sc{gnus} to browse through news groups, look at summaries of
15603: articles in specific group, and read articles of interest. You can
15604: respond to authors or write replies to all the readers of a news group.
15605:
15606: This document introduces @sc{gnus} and describes several basic features.
15607: Full documentation will appear in @cite{The GNU Emacs Extensions Manual}.
15608:
15609: @kindex M-x gnus @r{(V19)}
15610: @findex gnus @r{(V19)}
15611: To start @sc{gnus}, type @kbd{M-x gnus @key{RET}}.
15612:
15613: @menu
15614: * Buffers of GNUS:: The Newsgroups, Summary and Article buffers.
15615: * GNUS Startup:: What you should know about starting GNUS.
15616: * Summary of GNUS:: A short description of the basic GNUS commands.
15617: @end menu
15618:
15619: @node Buffers of GNUS
15620: @subsection @sc{GNUS}'s Three Buffers
15621:
15622: @sc{gnus} creates and uses three Emacs buffers, each with its own
15623: particular purpose and its own major mode.
15624:
15625: The @dfn{Newsgroup buffer} contains a list of newsgroups. This is the
15626: first buffer that @sc{gnus} displays when it starts up. Normally the list
15627: contains only the newsgroups to which you subscribe (which are listed in
15628: your @file{.newsrc} file) and which contain unread articles. Use this
15629: buffer to select a specific newsgroup.
15630:
15631: The @dfn{Summary buffer} lists the articles in a single newsgroup,
15632: including their subjects, their numbers, and who posted them. @sc{gnus}
15633: creates a Summary buffer for a newsgroup when you select the group in
15634: the Newsgroup buffer. Use this buffer to select an article, and to move
15635: around in an article.
15636:
15637: The @dfn{Article buffer} displays the text of an article. You rarely
15638: need to select this buffer because you can read the text while keeping
15639: the Summary buffer selected.
15640:
15641: @node GNUS Startup
15642: @subsection When @sc{GNUS} Starts Up
15643:
15644: At startup, @sc{gnus} reads your @file{.newsrc} news initialization file
15645: and attempts to communicate with the local news server, which is a
15646: repository of news articles. The news server need not be the same
15647: computer you are logged in on.
15648:
15649: If you start @sc{gnus} and connect to the server, but do not see any
15650: newsgroups listed in the Newsgroup buffer, type @kbd{L} to get a listing
15651: of all the newsgroups. Then type @kbd{u} to unsubscribe from particular
15652: newsgroups. (Move the cursor using @kbd{n} and @kbd{p} or the usual
15653: Emacs commands.) When you quit with @kbd{q}, @sc{gnus} automatically
15654: records the subscribed groups in your @file{.newsrc} initialization
15655: file. (You do not have to edit this file yourself, although you may.)
15656: Next time you start @sc{gnus}, you will see only the subscribed groups.
15657:
15658: @node Summary of GNUS
15659: @subsection Summary of GNUS Commands
15660:
15661: Reading news is a two step process:
15662:
15663: @enumerate
15664: @item
15665: Choose a newsgroup in the Newsgroup buffer.
15666:
15667: @item
15668: Choose an article in the Summary buffer. The article is displayed in
15669: the Article buffer in a large window, below the Summary buffer in its
15670: small window.
15671: @end enumerate
15672:
15673: Each buffer has commands particular to it, but commands that do the same
15674: things have similar keybindings. Here are commands for the Newsgroup
15675: and Summary buffers:
15676:
15677: @table @kbd
15678: @kindex z @r{(Group mode)} @r{(GNUS, V19)}
15679: @findex gnus-Group-suspend @r{(V19)}
15680: @item z
15681: In the Newsgroup buffer, suspend @sc{gnus}. You can return to @sc{gnus} later by
15682: selecting the Newsgroup buffer and typing @kbd{g} to get newly arrived
15683: articles.
15684:
15685: @kindex q @r{(Group mode)} @r{(GNUS, V19)}
15686: @findex gnus-Group-exit @r{(V19)}
15687: @item q
15688: In the Newsgroup buffer, update your @file{.newsrc} initialization file
15689: and quit @sc{gnus}.
15690:
15691: In the Summary buffer, exit the current newsgroup and return to the
15692: Newsgroup buffer. Thus, typing @kbd{q} twice quits @sc{gnus}.
15693:
15694: @kindex L @r{(Group mode)} @r{(GNUS, V19)}
15695: @findex gnus-Group-list-all-groups @r{(V19)}
15696: @item L
15697: In the Newsgroup buffer, list all the newsgroups available on your news
15698: server. This may be a long list!
15699:
15700: @kindex l @r{(Group mode)} @r{(GNUS, V19)}
15701: @findex gnus-Group-list-groups @r{(V19)}
15702: @item l
15703: In the Newsgroup buffer, list only the newsgroups to which you subscribe
15704: and which contain unread articles.
15705:
15706: @kindex u @r{(Group mode)} @r{(GNUS, V19)}
15707: @findex gnus-Group-unsubscribe-current-group @r{(V19)}
15708: @cindex subscribe newsgroups (V19)
15709: @cindex unsubscribe newsgroups (V19)
15710: @item u
15711: In the Newsgroup buffer, unsubscribe from (or subscribe to) the
15712: newsgroup listed in the line that point is on. When you quit @sc{gnus} by
15713: typing @kbd{q}, @sc{gnus} lists your subscribed-to newsgroups in your
15714: @file{.newsrc} file. The next time you start @sc{gnus}, you see only the
15715: newsgroups listed in your @file{.newsrc} file.
15716:
15717: You may also edit your @file{.newsrc} file directly in Emacs. First quit
15718: @sc{gnus}, then visit the @file{.newsrc} file. For example, you can remove
15719: all the @file{alt.} groups by going to the beginning of the file and
15720: typing @kbd{M-x flush-lines RET alt RET}. Next time you start @sc{gnus}, you
15721: will see only the newsgroups still listed in the @file{.newsrc} file.
15722:
15723: @kindex SPC @r{(Group mode)} @r{(GNUS, V19)}
15724: @findex gnus-Group-read-group @r{(V19)}
15725: @item @key{SPC}
15726: In the Newsgroup buffer, select the group on the line under the cursor
15727: and display the first unread article in that group.
15728:
15729: @kindex SPC @r{(Summary mode)} @r{(GNUS, V19)}
15730: @findex gnus-Summary-next-page @r{(V19)}
15731: @need 1000
15732: In the Summary buffer,
15733:
15734: @itemize @minus
15735: @item
15736: Select the article on the line under the cursor if none is selected.
15737:
15738: @item
15739: Scroll the text of the article if one is selected.
15740:
15741: @item
15742: Select the next unread article if at the end of the current article.
15743: @end itemize
15744:
15745: Thus, you can move through all the articles by repeatedly typing @key{SPC}.
15746:
15747: @kindex DEL @r{(Group mode)} @r{(GNUS, V19)}
15748: @item @key{DEL}
15749: In the Newsgroup Buffer, move point to the previous newsgroup containing
15750: unread articles.
15751:
15752: @kindex DEL @r{(Summary mode)} @r{(GNUS, V19)}
15753: @findex gnus-Summary-prev-page @r{(V19)}
15754: In the Summary buffer, scroll the text of the article backwards.
15755:
15756: @kindex n @r{(Group mode)} @r{(GNUS, V19)}
15757: @findex gnus-Group-next-unread-group @r{(V19)}
15758: @item n
15759: Move point to the next unread newsgroup, or select the next unread
15760: article.
15761:
15762: @kindex p @r{(Group mode)} @r{(GNUS, V19)}
15763: @findex gnus-Group-prev-unread-group @r{(V19)}
15764: @item p
15765: Move point to the previous unread newsgroup, or select the previous
15766: unread article.
15767:
15768: @kindex C-n @r{(Group mode)} @r{(GNUS, V19)}
15769: @findex gnus-Group-next-group @r{(V19)}
15770: @kindex C-p @r{(Group mode)} @r{(GNUS, V19)}
15771: @findex gnus-Group-prev-group @r{(V19)}
15772: @kindex C-n @r{(Summary mode)} @r{(GNUS, V19)}
15773: @findex gnus-Summary-next-subject @r{(V19)}
15774: @kindex C-p @r{(Summary mode)} @r{(GNUS, V19)}
15775: @findex gnus-Summary-prev-subject @r{(V19)}
15776: @itemx C-n
15777: @itemx C-p
15778: Move point to the next or previous item, even if it is marked as read.
15779: This does not select the article or newsgroup on that line.
15780:
15781: @kindex s @r{(Summary mode)} @r{(GNUS, V19)}
15782: @findex gnus-Summary-isearch-article @r{(V19)}
15783: @item s
15784: In the Summary buffer, do an incremental search of the current text in
15785: the Article buffer, just as if you switched to the Article buffer and
15786: typed @kbd{C-s}.
15787:
15788: @kindex M-s @r{(Summary mode)} @r{(GNUS, V19)}
15789: @findex gnus-Summary-search-article-forward @r{(V19)}
15790: @item M-s @var{regexp} RET
15791: In the Summary buffer, search forward for articles containing a match
15792: for @var{regexp}.
15793:
15794: @c kindex C-c C-s C-n @r{(Summary mode)} @r{(GNUS, V19)}
15795: @findex gnus-Summary-sort-by-number @r{(V19)}
15796: @c kindex C-c C-s C-s @r{(Summary mode)} @r{(GNUS, V19)}
15797: @findex gnus-Summary-sort-by-subject @r{(V19)}
15798: @c kindex C-c C-s C-d @r{(Summary mode)} @r{(GNUS, V19)}
15799: @findex gnus-Summary-sort-by-date @r{(V19)}
15800: @c kindex C-c C-s C-a @r{(Summary mode)} @r{(GNUS, V19)}
15801: @findex gnus-Summary-sort-by-author @r{(V19)}
15802: @item C-c C-s C-n
15803: @itemx C-c C-s C-s
15804: @itemx C-c C-s C-d
15805: @itemx C-c C-s C-a
15806: In the Summary buffer, sort the list of articles by number, subject,
15807: date, or author.
15808:
15809: @kindex C-M-n @r{(Summary mode)} @r{(GNUS, V19)}
15810: @findex gnus-Summary-next-same-subject @r{(V19)}
15811: @kindex C-M-p @r{(Summary mode)} @r{(GNUS, V19)}
15812: @findex gnus-Summary-prev-same-subject @r{(V19)}
15813: @item C-M-n
15814: @itemx C-M-p
15815: In the Summary buffer, read the next or previous article with the same
15816: subject as the current article.
15817: @end table
15818:
15819: @ignore
15820: @node Where to Look
15821: @subsection Where to Look Further
15822:
15823: @c Too many references to the name of the manual if done with xref in TeX!
15824: @sc{gnus} is powerful and customizable. Here are references to a few
15825: @ifinfo
15826: additional topics:
15827:
15828: @end ifinfo
15829: @iftex
15830: additional topics in @cite{The GNUS Manual}:
15831:
15832: @itemize @bullet
15833: @item
15834: Follow discussions on specific topics.@*
15835: See section ``Thread-based Reading''.
15836:
15837: @item
15838: Read digests. See section ``Digest Articles''
15839:
15840: @item
15841: Refer to and jump to the parent of the current article.@*
15842: See section ``Referencing Articles''.
15843:
15844:
15845: @item
15846: Refer to articles by using Message-IDs included in the messages.@*
15847: See section ``Article Commands''.
15848:
15849: @item
15850: Save articles. See section ``Saving Articles''.
15851:
15852: @item
15853: Create filters that preselect which articles you will see, according to
15854: regular expressions in the articles or their headers.@*
15855: See section ``Kill File''.
15856:
15857: @item
15858: Send an article to a newsgroup.@*
15859: See section ``Posting Articles''.
15860: @end itemize
15861: @end iftex
15862: @ifinfo
15863: @itemize @bullet
15864: @item
15865: Follow discussions on specific topics.@*
15866: @xref{Thread-based Reading, , Reading Based on Conversation Threads,
15867: gnus, The GNUS Manual}.
15868:
15869: @item
15870: Read digests. @xref{Digest Articles, , , gnus, The GNUS Manual}.
15871:
15872: @item
15873: Refer to and jump to the parent of the current article.@*
15874: @xref{Referencing Articles, , , gnus, The GNUS Manual}.
15875:
15876:
15877: @item
15878: Refer to articles by using Message-IDs included in the messages.@*
15879: @xref{Article Commands, , , gnus, The GNUS Manual}.
15880:
15881: @item
15882: Save articles. @xref{Saving Articles, , , gnus, The GNUS Manual}.
15883:
15884: @item
15885: Create filters that preselect which articles you will see, according to
15886: regular expressions in the articles or their headers.@*
15887: @xref{Kill File, , , gnus, The GNUS Manual}.
15888:
15889: @item
15890: Send an article to a newsgroup.@*
15891: @xref{Posting Articles, , , gnus, The GNUS Manual}.
15892: @end itemize
15893: @end ifinfo
15894: @end ignore
15895:
15896: @node Calendar/Diary
15897: @section Calendar and Diary
15898:
15899: The calendar facility in Emacs 19 is almost completely new, and it
15900: comes with a diary feature. You can use the diary to keep track of
15901: appointments, anniversaries, and other events.
15902: @c ??? reference to top node, Diary in GNU Emacs Calendar
15903: @c @xref{diary, , Diary, calendar, The GNU Emacs Calendar}, for more
15904: @c complete information.
15905:
15906: To use the diary, you must write diary entries in a particular file,
15907: called your @dfn{diary file}. Its name is @file{~/diary}. Emacs
15908: displays the entries for particular dates by finding them in the diary
15909: file, formatting them, and displaying them in a diary display buffer.
15910:
15911: @menu
15912: * Calendar:: New features of the calendar proper.
15913: * Entries: Diary Entries. The location and form of a diary entry.
15914: * New Entries:: Inserting diary entries using the calendar.
15915: * Displaying Diary:: How to display diary entries from the calendar.
15916: * European Calendar Style :: Day-month-year style for dates.
15917: * Simple and Fancy:: The diary has two modes for display.
15918: * Other Diary Features:: The diary has many advanced commands.
15919: * Startup Diary:: How to display your diary when you start Emacs.
15920: * Printing Diary:: Print selected entries of the diary.
15921: @end menu
15922:
15923: @node Calendar
15924: @subsection Calendar
15925: @cindex calendar @r{(V19)}
15926:
15927: In Emacs 19 you can use ordinary Emacs cursor commands to move through
15928: the calendar, which scrolls automatically to display different months or
15929: different years. Character motion translates to days, line motion to
15930: weeks, sentence and paragraph motion to months, and page motion to
15931: years. The vertical and horizontal scroll commands also handle the
15932: calendar suitably.
15933:
15934: @c The index entries for the key bindings of Calendar and Diary modes
15935: @c are commented out because they don't seem very useful.
15936: @c @kindex p d (Calendar mode)
15937: @c @kindex g d (Calendar mode)
15938: @c @kindex . (Calendar mode)
15939: @kbd{p d} displays the selected date as a day within the year. @kbd{g
15940: d} selects a date given as month, day, year. Type @kbd{.} to go back
15941: to today's date.
15942:
15943: @c @kindex M-= (Calendar mode)
15944: @findex calendar-count-days-region @r{(V19)}
15945: The command @kbd{M-=}, which normally gives the number of lines in the
15946: region, in Calendar mode gives the number of days in the region
15947: (@code{calendar-count-days-region}).
15948:
15949: The calendar facility also knows about other important calendars. The
15950: commands for these come in pairs; the commands to convert @emph{to}
15951: another calendar start with the @kbd{p} prefix (short for ``print''),
15952: and the commands to convert from another calendar start with the @kbd{g}
15953: prefix (short for ``go to''). Here is a complete list:
15954:
15955: @c !!! Insert line breaks to prevent overfull hboxes.
15956: @table @asis
15957: @item @kbd{g a}, @kbd{p a}
15958: @findex calendar-print-astro-date @r{(V19)}
15959: @findex calendar-goto-astro-date @r{(V19)}
15960: @cindex astronomical calendar
15961: @cindex Julian day number
15962: The astronomical calendar, a simple count of days elapsed since noon,
15963: Monday, January 1, 4713 B.C. on the Julian calendar. The number of days
15964: elapsed is also called the @dfn{Julian day number}
15965: (@code{calendar-goto-astro-date}, @code{calendar-print-astro-date}).
15966:
15967: @item @kbd{g c}, @kbd{p c}
15968: @c @kindex g c (Calendar mode)
15969: @c @kindex p c (Calendar mode)
15970: @findex calendar-print-iso-date @r{(V19)}
15971: @findex calendar-goto-iso-date @r{(V19)}
15972: @cindex ISO commercial calendar
15973: ISO commercial calendar@*
15974: (@code{calendar-goto-iso-date}, @code{calendar-print-iso-date}).
15975:
15976: @item @kbd{g f}, @kbd{p f}
15977: @c @kindex p f (Calendar mode)
15978: @findex calendar-goto-french-date @r{(V19)}
15979: @findex calendar-print-french-date @r{(V19)}
15980: @cindex French revolutionary calendar
15981: @c !!! added @* to prevent overfull hbox
15982: French revolutionary calendar@*
15983: (@code{calendar-goto-french-date},@*
15984: @code{calendar-print-french-date}).
15985:
15986: @item @kbd{g h}, @kbd{p h}
15987: @c @kindex g h (Calendar mode)
15988: @c @kindex p h (Calendar mode)
15989: @findex calendar-print-hebrew-date @r{(V19)}
15990: @findex calendar-goto-hebrew-date @r{(V19)}
15991: @cindex Hebrew calendar
15992: @c !!! added @* to prevent overfull hbox
15993: Hebrew calendar@*
15994: (@code{calendar-goto-hebrew-date},@*
15995: @code{calendar-print-hebrew-date}).
15996:
15997: @item @kbd{g i}, @kbd{p i}
15998: @c @kindex g i (Calendar mode)
15999: @c @kindex p i (Calendar mode)
16000: @findex calendar-print-islamic-date @r{(V19)}
16001: @findex calendar-goto-islamic-date @r{(V19)}
16002: @cindex Islamic calendar
16003: @c !!! added @* to prevent overfull hbox
16004: Islamic calendar@*
16005: (@code{calendar-goto-islamic-date},@*
16006: @code{calendar-print-islamic-date}).
16007:
16008: @item @kbd{g j}, @kbd{p j}
16009: @c @kindex g j (Calendar mode)
16010: @c @kindex p j (Calendar mode)
16011: @findex calendar-print-julian-date @r{(V19)}
16012: @findex calendar-goto-julian-date @r{(V19)}
16013: @cindex Julian calendar
16014: @c !!! added @* to prevent overfull hbox
16015: Julian calendar@*
16016: (@code{calendar-goto-julian-date},@*
16017: @code{calendar-print-julian-date}).
16018:
16019: @item @kbd{p m}
16020: @c @kindex p m (Calendar mode)
16021: @findex calendar-print-mayan-date @r{(V19)}
16022: @cindex Mayan calendar
16023: Mayan calendar (@code{calendar-print-mayan-date}).
16024: @end table
16025:
16026: @ignore
16027: Several commands are needed to handle selecting dates in the Mayan
16028: calendar.
16029:
16030: @table @kbd
16031: @item g m l @var{baktun}.@var{katun}.@var{tun}.@var{uinic}.@var{kin} @key{RET}
16032: @cindex long count @r{(V19)}
16033: Move point to a date specified in the Mayan long count calendar
16034: (@code{calendar-goto-long-count-date}). The argument consists of numbers
16035: separated by periods.
16036: @item g m p t @var{number} @var{name} @key{RET}
16037: @cindex tzolkin @r{(V19)}
16038: Move point to the previous occurrence of a specified date in the Mayan
16039: tzolkin calendar (@code{calendar-previous-tzolkin-date}). Here @var{name}
16040: is one of the twenty tzolkin day names, and @var{number} is between 1 and 13.
16041: @item g m n t @var{number} @var{name} @key{RET}
16042: Move point to the next occurrence of a specified date in the
16043: tzolkin calendar (@code{calendar-next-tzolkin-date}).
16044: @item g m p h @var{kin} @var{uinal} @key{RET}
16045: @cindex haab @r{(V19)}
16046: Move point to the previous occurrence of a specified date in the Mayan
16047: haab calendar (@code{calendar-previous-haab-date}). Here @var{uinal}
16048: is a haab month name, and @var{kin} is a number from 1 to 19 (or 0).
16049: @item g m n h @var{kin} @var{uinal} @key{RET}
16050: Move point to the next occurrence of a specified date in the
16051: haab calendar (@code{calendar-next-haab-date}).
16052: @item g m p c @var{number} @var{name} @var{kin} @var{uinal} @key{RET}
16053: @cindex calendar round @r{(V19)}
16054: Move point to the previous occurrence of a specified date in the Mayan
16055: calendar round (@code{calendar-previous-calendar-round-date}). Specify
16056: a tzolkin date followed by a haab date.
16057: @item g m n c @var{number} @var{name} @var{kin} @var{uinal} @key{RET}
16058: Move point to the next occurrence of a specified date in the
16059: calendar round (@code{calendar-next-calendar-round-date}).
16060: @end table
16061: @end ignore
16062:
16063: @findex calendar-cursor-holidays @r{(V19)}
16064: @findex mark-calendar-holidays @r{(V19)}
16065: @findex calendar-unmark @r{(V19)}
16066: The calendar also knows the dates of standard holidays. Type @kbd{h}
16067: (@code{calendar-cursor-holidays}) to display a list of holidays for the
16068: selected date. This list appears in another window. Type @kbd{x}
16069: (@code{mark-calendar-holidays}) to mark each day that is a holiday with
16070: @samp{*} in the calendar itself. The command @kbd{u}
16071: (@code{calendar-unmark}) turns off this marking.
16072:
16073: @findex holidays @r{(V19)}
16074: At any time, you can use @kbd{M-x holidays} to display a list of
16075: holidays for the present month and the preceding and following months.
16076:
16077: @node Diary Entries
16078: @subsection Diary Entries
16079: @cindex diary entries (V19)
16080:
16081: @vindex diary-file @r{(V19)}
16082: To use the diary feature, you must write @dfn{diary entries} that
16083: describe plans associated with particular dates, and put them in your
16084: @dfn{diary file}, which is normally the file @file{~/diary}. You can
16085: specify a different name for it by setting the variable
16086: @code{diary-file}; you would do this before using any of the commands
16087: that operate on the diary.
16088:
16089: Diary file entries follow a simple convention: begin entries with a date
16090: at the beginning of a line, followed optionally by a time, and then by
16091: the text of the entry:
16092:
16093: @example
16094: @var{date} @var{optional-time-of-day} @var{text-of-entry}
16095: @end example
16096:
16097: @noindent
16098: To continue an entry over two or more lines, indent the second and
16099: subsequent lines. The lines of the entry after the first are called
16100: @dfn{continuation lines}. Other lines in the diary file that are not
16101: part of any entry are comment lines; Emacs does not display these.
16102:
16103: When you make diary entries using Calendar mode, Emacs inserts the date
16104: for you in the appropriate format and places the cursor so you can type
16105: the text of the entry.
16106:
16107: You can write entries in any order and Emacs will display the entries by
16108: date. However, time-of-day entries can be sorted chronologically only
16109: in a diary mode called Fancy mode; in Simple mode, Emacs displays
16110: time-of-day entries in their order in the diary file.
16111:
16112: @node Displaying Diary
16113: @subsection Calendar Commands to Display Diary Entries
16114: @cindex diary display (V19)
16115: @cindex display of diary (V19)
16116:
16117: In Calendar mode, use the following commands to display your diary
16118: entries:
16119:
16120: @table @kbd
16121: @findex view-diary-entries @r{(V19)}
16122: @c @kindex d (Calendar mode) @r{(V19)}
16123: @item d
16124: Display any diary entries for the date under the cursor
16125: (@code{view-diary-entries}).
16126:
16127: With a numeric argument, Emacs shows the diary entries for that many
16128: successive days, starting with and including the date under the cursor.
16129: Thus, @kbd{2 d} displays all the entries for the selected date and for
16130: the following day.
16131:
16132: @findex show-all-diary-entries @r{(V19)}
16133: @c @kindex s (Calendar mode) @r{(V19)}
16134: @item s
16135: Display your entire diary file (@code{show-all-diary-entries}).
16136:
16137: @findex mark-diary-entries @r{(V19)}
16138: @c @kindex m (Calendar mode) @r{(V19)}
16139: @item m
16140: In the calendar, mark all visible dates that have diary entries
16141: (@code{mark-diary-entries}).
16142:
16143: @findex calendar-unmark @r{(V19)}
16144: @c @kindex u (Calendar mode) @r{(V19)}
16145: @item u
16146: Unmark the calendar (@code{calendar-unmark}).
16147: @end table
16148:
16149: At any time, not just in Calendar mode, you can display today's diary
16150: entries by typing:
16151:
16152: @findex diary @r{(V19)}
16153: @example
16154: M-x diary
16155: @end example
16156:
16157: @noindent
16158: With a prefix argument @var{n}, this command displays diary entries for
16159: @var{n} successive days, starting from and including today.
16160:
16161: @node New Entries
16162: @subsection Calendar Commands for Making Diary Entries
16163: @cindex diary entries, inserting (V19)
16164:
16165: Calendar mode provides several commands to help you make diary file
16166: entries. These commands work by visiting the diary file and inserting
16167: the date information; you must finish the job by inserting the text of
16168: the entry, and then save the diary file with @kbd{C-x C-s}. The
16169: commands are:
16170:
16171: @table @kbd
16172: @findex insert-diary-entry @r{(V19)}
16173: @c @kindex i d (Calendar mode) @r{(V19)}
16174: @item i d
16175: Add a diary entry for the selected date in the calendar
16176: (@code{insert-diary-entry}).
16177:
16178: @findex insert-weekly-diary-entry @r{(V19)}
16179: @c @kindex i w (Calendar mode) @r{(V19)}
16180: @item i w
16181: Add a diary entry for the selected day of the week
16182: (@code{insert-weekly-diary-entry}). This entry is displayed each week
16183: on the selected day.
16184:
16185: @findex insert-monthly-diary-entry @r{(V19)}
16186: @c @kindex i m (Calendar mode) @r{(V19)}
16187: @item i m
16188: Add a diary entry for the selected day of the month
16189: (@code{insert-monthly-diary-entry}). This entry is displayed each month
16190: on the selected day.
16191:
16192: @findex insert-yearly-diary-entry @r{(V19)}
16193: @c @kindex i y (Calendar mode) @r{(V19)}
16194: @item i y
16195: Add a diary entry for the selected day of the year
16196: (@code{insert-yearly-diary-entry}). This entry is displayed each year
16197: on the selected day.
16198: @end table
16199:
16200: Here are commands for entering more complex kinds of diary entries in
16201: Calendar mode. These kinds of entries operate properly only in Fancy
16202: Diary Display mode (@pxref{Simple and Fancy}).
16203:
16204: @table @kbd
16205: @findex insert-anniversary-diary-entry @r{(V19)}
16206: @c @kindex i a (Calendar mode diary) @r{(V19)}
16207: @item i a
16208: Add an anniversary diary entry for the selected date
16209: (@code{insert-anniversary-diary-entry}).
16210:
16211: Select the date you want remembered, in the proper year---if it is a
16212: birthday, remember to go to the person's year of birth! Then type
16213: @kbd{i a} and enter the text of the entry.
16214:
16215: In the textual part of the entry you can type @samp{%d}. When Emacs
16216: displays the entry in the diary buffer, the @samp{%d} is replaced by the
16217: number of years since the date. Thus, if you use @samp{%d years old} as
16218: the text of the entry, it will display as @samp{53 years old} on the
16219: 53rd birthday.
16220:
16221: @findex insert-cyclic-diary-entry @r{(V19)}
16222: @c @kindex i c (Calendar mode diary) @r{(V19)}
16223: @item i c
16224: Add a cyclic diary entry starting at the date
16225: (@code{insert-cyclic-diary-entry}). An entry is displayed on a
16226: specified starting date and then is repeatedly displayed at the
16227: specified interval. This is useful for ten day cycles of preventive
16228: maintenance and similar activities.
16229:
16230: To use this command, first select the start date. The command reads the
16231: interval (the number of days between repetitions) using the minibuffer,
16232: then inserts the beginning of the entry.
16233:
16234: @findex insert-block-diary-entry @r{(V19)}
16235: @c @kindex i b (Calendar mode diary) @r{(V19)}
16236: @item i b
16237: Add a block diary entry for the current region
16238: (@code{insert-block-diary-entry}). With a block entry, Emacs
16239: writes the same message in the display for successive days.
16240:
16241: Position point and mark at the beginning and end of the block of days
16242: you want entered and type @kbd{i b}. This sets up the diary entry's
16243: date info and positions point so you can write the text of the entry.
16244: People usually use this command for trips or vacations.
16245: @end table
16246:
16247: @node European Calendar Style
16248: @subsection European Calendar Style
16249: @cindex European date style (Calendar, V19)
16250: @cindex American date style (Calendar, V19)
16251: @cindex dates, style of writing (Calendar, V19)
16252:
16253: By default, Emacs interprets and displays diary dates in civilian
16254: American form, @samp{@var{month}/@var{day}/@var{year}}:
16255: @samp{2/15/1993}, or @samp{February 15, 1993}.
16256:
16257: @vindex european-calendar-style @r{(V19)}
16258: @cindex European calendar style (V19)
16259: Alternatively, you can specify the European calendar style for writing
16260: dates: @samp{@var{day}/@var{month}/@var{year}}, @samp{15/2/1993} or
16261: @samp{15 February 1993}. To do this, set the variable
16262: @code{european-calendar-style} to @code{t}, before using any calendar or
16263: diary command. This also affects display of dates.
16264:
16265: Here's how to do this in your @file{.emacs} file:
16266:
16267: @example
16268: (setq european-calendar-style t)
16269: @end example
16270:
16271: @node Simple and Fancy
16272: @subsection Simple and Fancy Diary Display
16273: @cindex Simple Diary mode (V19)
16274: @cindex Fancy Diary mode (V19)
16275:
16276: There are two modes for displaying a subset of diary entries: Simple
16277: mode and Fancy mode. Fancy mode provides a more dramatic display for
16278: the diary, and can also display the actual matching date for diary
16279: entries that match more than one date.
16280:
16281: @vindex diary-display-hook @r{(V19)}
16282: @findex fancy-diary-display @r{(V19)}
16283: By default, Emacs uses Simple mode, which is quicker than Fancy mode.
16284: Another advantage of Simple mode is that you can edit the displayed
16285: diary entries ``in place'' and save them. When you use Fancy mode, it
16286: is useless to edit the displayed subset of the diary; instead you must
16287: visit the diary file separately. To select Fancy mode, set
16288: @code{diary-display-hook} to @code{fancy-diary-display} like this:
16289:
16290: @example
16291: (setq diary-display-hook 'fancy-diary-display)
16292: @end example
16293:
16294: @node Other Diary Features
16295: @subsection Other Diary Features
16296:
16297: Here are some additional diary features. These will be explained in
16298: full in @cite{The GNU Emacs Extensions Manual}.
16299:
16300: You can schedule meetings on a date such as the first Tuesday of every
16301: month. This is called an @dfn{offset} date. The diary has commands
16302: for specifying such meetings, but not in Calendar mode. To create
16303: such an entry, you need to edit the diary file yourself.
16304: @c !!! reference to diary offset in
16305: @c !!! xref{diary offset, , Offset Events, calendar, The GNU Emacs
16306: @c !!! Calendar}, for more information.
16307:
16308: You can make entries according to Hebrew and Islamic dates. Calendar
16309: mode provides commands of the form @kbd{i h d} to add a diary entry
16310: for the Hebrew date corresponding to the selected date and @kbd{i i d}
16311: to add a diary entry for the Islamic date corresponding to the selected
16312: date. You can make entries that repeat every week, month, or year.
16313: Before using these commands, you must set the
16314: @code{nongregorian-diary-listing-hook} and the
16315: @code{nongregorian-diary-marking-hook} in your @file{.emacs} file.
16316: @c !!! reference to Hebrew/Islamic Entries in The GNU Emacs Calendar
16317: @c !!! @xref{Hebrew/Islamic Entries, , Hebrew- and Islamic-Date Diary
16318: @c !!! Entries, calendar, The GNU Emacs Calendar}.
16319:
16320: You can include other diary files in your diary display. This way, a
16321: group of people can share a common diary file.
16322: @c !!! reference to Including Diary Files in The GNU Emacs Calendar
16323: @c !!! xref{Including Diary Files, , Including Other Diary Files, calendar, The
16324: @c !!! GNU Emacs Calendar}.
16325:
16326: @node Startup Diary
16327: @subsection Displaying your Diary on Emacs Startup
16328: @cindex diary and Emacs startup (V19)
16329:
16330: If you start a new Emacs each day, you might want to display your diary
16331: automatically at that time. To do so, put this in your @file{.emacs}
16332: file:
16333:
16334: @example
16335: (diary)
16336: @end example
16337:
16338: If you want to see both the calendar and your diary at startup, use this
16339: instead:
16340:
16341: @example
16342: @group
16343: (setq view-diary-entries-initially t)
16344: (calendar)
16345: @end group
16346: @end example
16347:
16348: @node Printing Diary
16349: @subsection Printing the Displayed Part of the Diary
16350: @cindex Printing diary (V19)
16351:
16352: @findex print-diary-entries @r{(V19)}
16353: To print the selected diary entries as they appear on the screen, use
16354: @kbd{M-x print-diary-entries}. The same variables that customize
16355: @code{lpr-buffer} also affect this command.
16356:
16357: In Simple mode, the diary display buffer uses selective display
16358: (@pxref{Selective Display}). This means that what you see on the screen
16359: is just part of the text in the Emacs buffer. The diary entries that
16360: don't apply to the dates you asked for are still in the buffer, but
16361: hidden. The ordinary printing commands such as @code{lpr-buffer} would
16362: not do what you want; they print the entire text, including the hidden
16363: parts. This is why we need @code{print-diary-entries}.
16364:
16365: @node Version Control
16366: @section Version Control
16367: @cindex version control
16368:
16369: @dfn{Version control systems} are packages that can record multiple
16370: versions of a source file, usually storing the unchanged parts of the
16371: file just once. Version control systems also record history information
16372: such as the creation time of each version, who created it, and a
16373: description of what was changed in that version.
16374:
16375: The GNU project recommends the version control system known as RCS,
16376: which is free software and available from the Free Software Foundation.
16377: Emacs supports use of either RCS or SCCS (a proprietary, but widely
16378: used, version control system that is not quite as powerful as RCS)
16379: through a facility called VC. The same Emacs commands work with either
16380: RCS or SCCS, so you hardly have to know which one of them you are
16381: using.
16382:
16383: @menu
16384: * Concepts of VC::
16385: * Editing with VC::
16386: * Variables for Check-in/out::
16387: * Comparing Versions::
16388: * VC Status::
16389: * Renaming and VC::
16390: * Snapshots::
16391: * Log Entries::
16392: * Change Logs and VC::
16393: * Version Headers::
16394: @end menu
16395:
16396: @node Concepts of VC
16397: @subsection Concepts of Version Control
16398: @cindex RCS
16399: @cindex SCCS
16400: @cindex master file
16401: @cindex registered file
16402: @cindex work file
16403:
16404: When a file is under version control, we also say that it is
16405: @dfn{registered} in the version control system. Each registered file
16406: has a corresponding @dfn{master file} which represents the file's
16407: present state plus its change history, so that you can reconstruct from
16408: it either the current version or any specified earlier version. Usually
16409: the master file also records a change comment for each version.
16410:
16411: The file that is maintained under version control is sometimes called
16412: the @dfn{work file} corresponding to its master file.
16413:
16414: @cindex checking out files
16415: @cindex checking in files
16416: @cindex locking and version control
16417: To examine a file, you @dfn{check it out}. This extracts a version
16418: of the file (typically, the most recent) from the master. If you want
16419: to edit the file, you must check it out @dfn{locked}. Only one user can
16420: do this at a time for any given source file. When you are done with
16421: your editing, you must @dfn{check in} the new version. This records the
16422: new version in the master file, and unlocks the source file so that
16423: other people can lock it and thus modify it.
16424:
16425: These are the basic operations of version control.
16426: Checking in and checking out both use the single Emacs command
16427: @w{@kbd{C-x C-q}} (@code{vc-toggle-read-only}).
16428:
16429: @node Editing with VC
16430: @subsection Editing with Version Control
16431:
16432: When you visit a file that is maintained using version control, the
16433: mode line displays @samp{RCS} or @samp{SCCS} to inform you that version
16434: control is in use, and also (in case you care) which low-level system
16435: the file is actually stored in. Normally, such a source file is
16436: read-only, and the mode line indicates this with @samp{%%}.)
16437:
16438: These are the commands that you use to edit a file maintained with
16439: version control:
16440:
16441: @table @kbd
16442: @item C-x C-q
16443: Check the visited file in or out.
16444:
16445: @item C-x v u
16446: Revert the buffer and the file to the last checked in version.
16447:
16448: @item C-x v c
16449: Remove the last-entered change from the master for the visited file.
16450: This undoes your last check-in.
16451:
16452: @item C-x v i
16453: Register the visited file in version control.
16454: @end table
16455:
16456: @noindent
16457: (@kbd{C-x v} is the prefix key for version control commands; all of these
16458: commands except for @kbd{C-x C-q} start with @kbd{C-x v}.)
16459:
16460: @kindex C-x C-q @r{(V19)}
16461: @findex vc-toggle-read-only @r{(V19)}
16462: If you want to edit the file, type @kbd{C-x C-q}
16463: (@code{vc-toggle-read-only}). This @dfn{checks out} and locks the file,
16464: so that you can edit it. The file is writable after check-out, but only
16465: for you, not for anyone else.
16466:
16467: @vindex vc-make-backups @r{(V19)}
16468: Emacs does not save backup files for source files that are maintained
16469: with version control. If you want to make backup files despite version
16470: control, set the variable @code{vc-make-backups} to a non-@code{nil} value.
16471:
16472: When you are finished editing the file, type @kbd{C-x C-q} again.
16473: When used on a file that is checked out, this command checks the file
16474: in. But check-in does not start immediately; first, you must enter a
16475: @dfn{log entry}---a description of the changes in the new version.
16476: @kbd{C-x C-q} pops up a buffer for you to enter this in. When you are
16477: finished typing in the log entry, type @kbd{C-c C-c} to terminate it; this is
16478: when actual check-in takes place.
16479:
16480: Once you have checked in your changes, the file is unlocked, so that
16481: other users can lock it and modify it.
16482:
16483: @vindex vc-keep-workfiles @r{(V19)}
16484: Normally the work file exists all the time, whether it is locked or
16485: not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking
16486: in a new version with @kbd{C-x C-q} deletes the work file; but any
16487: attempt to visit the file with Emacs creates it again.
16488:
16489: Actually, it is not impossible to lock a file that someone else has
16490: locked. If you try to check out a file that is locked, @kbd{C-x C-q}
16491: asks you whether you want to ``steal the lock.'' If you say yes, the
16492: file becomes locked by you, but a message is sent to the person who had
16493: formerly locked the file, to inform him or her of what has happened.
16494:
16495: @kindex C-x v u @r{(V19)}
16496: @findex vc-revert-buffer @r{(V19)}
16497: If you want to discard your current set of changes and revert to the
16498: last version checked in, use @kbd{C-x v u} (@code{vc-revert-buffer}).
16499: This cancels your last check-out, leaving the file unlocked. If you want
16500: to make a different set of changes, you must first check the file out
16501: again. @kbd{C-x v u} requies confirmation, unless it sees that
16502: you haven't made any changes since the last checked-in version.
16503:
16504: @kbd{C-x v u} is also the command to use if you lock a file and then
16505: don't actually change it.
16506:
16507: @kindex C-x v c @r{(V19)}
16508: @findex vc-cancel-version @r{(V19)}
16509: You can even cancel a change after checking it in, with @kbd{C-x v c}
16510: (@code{vc-cancel-version}). Normally, @kbd{C-x v c} reverts your
16511: workfile and buffer to the previous version (the one that precedes the
16512: version that is deleted), but you can prevent the reversion by giving
16513: the command a prefix argument. Then the buffer does not change.
16514:
16515: This command with a prefix argument is useful when you have checked in
16516: a change and then discover a trivial error in it; you can cancel the
16517: erroneous check-in, fix the error, and repeat the check-in.
16518:
16519: Be careful when invoking @kbd{C-x v c}, as it is easy to throw away a
16520: lot of work with it. To help you be careful, this command always asks
16521: for confirmation with @samp{yes}.
16522:
16523: @kindex C-x v i @r{(V19)}
16524: @findex vc-register @r{(V19)}
16525: You can register the visited file for version control using
16526: @w{@kbd{C-x v i}} (@code{vc-register}). This uses RCS if RCS
16527: is installed on your system; otherwise, it uses SCCS.
16528:
16529: By default, the initial version number is 1.1. If you want to use a
16530: different number, give @kbd{C-x v i} a prefix argument; then it reads
16531: the initial version number using the minibuffer.
16532:
16533: After @kbd{C-x v i}, the file is unlocked and read-only. Type
16534: @kbd{C-x C-q} if you wish to edit it.
16535:
16536: @vindex vc-initial-comment @r{(V19)}
16537: If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads
16538: an initial comment (much like a log entry) to describe the purpose of
16539: this source file.
16540:
16541: @node Variables for Check-in/out
16542: @subsection Variables Affecting Check-in and Check-out
16543: @c There is no need to tell users about vc-master-templates.
16544:
16545: @vindex vc-suppress-confirm @r{(V19)}
16546: If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x C-q}
16547: and @kbd{C-x v i} can save the current buffer without asking, and
16548: @kbd{C-x v u} also operates without asking for confirmation.
16549: (This variable does not affect @kbd{C-x v c}; that is so drastic
16550: that it should always ask for confirmation.)
16551:
16552: @vindex vc-command-messages @r{(V19)}
16553: VC mode does much of its work by running the shell commands for RCS
16554: and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC displays
16555: messages to indicate which shell commands it runs, and additional
16556: messages when the commands finish.
16557:
16558: Normally, VC assumes that it can deduce the locked/unlocked state of
16559: files by looking at the file permissions of the work file; this is
16560: fast. However, if the @file{RCS} or @file{SCCS} subdirectory is
16561: actually a symbolic link, then VC does not trust the file permissions to
16562: reflect this status.
16563:
16564: @vindex vc-mistrust-permissions @r{(V19)}
16565: You can specify the criterion for whether to trust the file permissions
16566: by setting the variable @code{vc-mistrust-permissions}. Its value may
16567: be @code{t} (always mistrust the file permissions and check the master
16568: file), @code{nil} (always trust the file permissions), or a function of
16569: one argument which makes the decision. The argument is the directory
16570: name of the @file{RCS} or @file{SCCS} subdirectory. A non-@code{nil}
16571: value from the function says to mistrust the file permissions.
16572:
16573: If you find that the file permissions of work files are changed
16574: erroneously, then you can set @code{vc-mistrust-permissions} to @code{t}
16575: so that VC always checks the master file.
16576:
16577: @node Log Entries
16578: @subsection Log Entries
16579:
16580: When you're editing an initial or change comment for inclusion in a
16581: master file, finish your entry by typing @kbd{C-c C-c}.
16582:
16583: @table @kbd
16584: @item C-c C-c
16585: Finish the comment edit normally (@code{vc-finish-logentry}).
16586: This finishes check-in.
16587: @end table
16588:
16589: To abort check-in, just don't type @kbd{C-c C-c} in that buffer. You
16590: can switch buffers and do other editing. As long as you don't try to
16591: check in another file, the comment you were editing remains in its
16592: buffer, and you can go back to that buffer at any time to complete the
16593: check-in.
16594:
16595: If you change several source files for the same reason, it is often
16596: convenient to specify the same log entry for many of the files. To do
16597: this, use the history of previous log entries. The commands
16598: @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just
16599: like the minibuffer history commands (except that they don't use the
16600: minibuffer).
16601:
16602: The history of previous log entries is actually stored in previous pages
16603: of the log entry editing buffer; they are normally hidden by narrowing.
16604:
16605: @vindex vc-log-mode-hook @r{(V19)}
16606: Each time you check in a file, the log entry buffer is put into VC Log
16607: mode, which involves running two hook variables: @code{text-mode-hook}
16608: and @code{vc-log-mode-hook}.
16609:
16610: @node Change Logs and VC
16611: @subsection Change Logs and VC
16612:
16613: Emacs users often record brief summaries of program changes in a file
16614: called @file{ChangeLog}, which is kept in the same directory as the
16615: source files, and is usually meant to be distributed along with the
16616: source files. You can maintain @file{ChangeLog} from the version
16617: control logs with the following command.
16618:
16619: @table @kbd
16620: @item C-x v a
16621: @kindex C-x v a @r{(V19)}
16622: @findex vc-update-change-log @r{(V19)}
16623: Visit the current directory's change log file and create new entries for
16624: versions checked in since the most recent entry in the change log file
16625: (@code{vc-update-change-log}).
16626:
16627: This command works with RCS only; it does not work with SCCS.
16628: @end table
16629:
16630: For example, suppose the first line of @file{ChangeLog} is dated 10
16631: April 1992, and suppose the only check-in since then was by Nathaniel
16632: Bowditch to @file{rcs2log} on 8 May 1992 with log text @samp{Ignore log
16633: messages that start with `#'.}. Then @kbd{C-x v a} visits
16634: @file{ChangeLog} and inserts text like this:
16635:
16636: @example
16637: @group
16638: Fri May 8 21:45:00 1992 Nathaniel Bowditch (nat@@apn.org)
16639:
16640: * rcs2log: Ignore log messages that start with `#'.
16641: @end group
16642: @end example
16643:
16644: @noindent
16645: You can then further edit as you wish.
16646:
16647: A log entry whose text begins with @samp{#} is not copied to
16648: @file{ChangeLog}. For example, if you merely fix some misspellings in
16649: comments, you can log the change with an entry beginning with @samp{#}
16650: to avoid putting such trivia into @file{ChangeLog}.
16651:
16652: When @kbd{C-x v a} adds several change log entries at once, it groups
16653: related log entries together if they all are checked in by the same
16654: author at nearly the same time. If the log entries for several such
16655: files all have the same text, it coalesces them into a single entry.
16656: For example, suppose the most recent check-ins have the following log
16657: entries:
16658:
16659: @example
16660: @exdent For @file{vc.texinfo}:
16661: Fix expansion typos.
16662: @exdent For @file{vc.el}:
16663: Don't call expand-file-name.
16664: @exdent For @file{vc-hooks.el}:
16665: Don't call expand-file-name.
16666: @end example
16667:
16668: They appear like this in @file{ChangeLog}:
16669:
16670: @example
16671: @group
16672: Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@@apn.org)
16673:
16674: * vc.texinfo: Fix expansion typos.
16675:
16676: * vc.el, vc-hooks.el: Don't call expand-file-name.
16677: @end group
16678: @end example
16679:
16680: Normally, @kbd{C-x v a} separates log entries by a blank line, but you
16681: can mark several related log entries to be clumped together (without an
16682: intervening blank line) by starting the text of each related log entry
16683: with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label
16684: itself is not copied to @file{ChangeLog}. For example, suppose the log
16685: entries are:
16686:
16687: @example
16688: @exdent For @file{vc.texinfo}:
16689: @{expand@} Fix expansion typos.
16690: @exdent For @file{vc.el}:
16691: @{expand@} Don't call expand-file-name.
16692: @exdent For @file{vc-hooks.el}:
16693: @{expand@} Don't call expand-file-name.
16694: @end example
16695:
16696: Then the text in @file{ChangeLog} looks like this:
16697:
16698: @example
16699: @group
16700: Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@@apn.org)
16701:
16702: * vc.texinfo: Fix expansion typos.
16703: * vc.el, vc-hooks.el: Don't call expand-file-name.
16704: @end group
16705: @end example
16706:
16707: Normally, the log entry for file @file{foo} is displayed as @samp{* foo:
16708: @var{text of log entry}}. But by convention, the @samp{:} after
16709: @file{foo} is omitted if the text of the log entry starts with
16710: @w{@samp{(@var{functionname}): }}. For example, if the log entry for
16711: @file{vc.el} is @samp{(vc-do-command): Check call-process status.}, then
16712: the text in @file{ChangeLog} looks like this:
16713:
16714: @example
16715: @group
16716: Wed May 6 10:53:00 1992 Nathaniel Bowditch (nat@@apn.org)
16717:
16718: * vc.el (vc-do-command): Check call-process status.
16719: @end group
16720: @end example
16721:
16722: @node Comparing Versions
16723: @subsection Comparing Versions
16724:
16725: @findex vc-diff @r{(V19)}
16726: @kindex C-x v = @r{(V19)}
16727: To compare two versions of a file, use @kbd{C-x v =} (@code{vc-diff}).
16728:
16729: Plain @kbd{C-x v =} compares the current buffer contents (saving them
16730: in the file if necessary) with the last checked-in version of the file.
16731: With a prefix argument, @kbd{C-x v =} reads a filename and two version
16732: numbers, and compares those versions of the file you specify.
16733:
16734: If you supply a directory name instead of the name of a work file,
16735: this command compares the two specified versions of all registered files
16736: in that directory and its subdirectories. You can also specify a
16737: snapshot name (@pxref{Snapshots}) instead of one or both version
16738: numbers.
16739:
16740: You can specify a checked-in version by its number; you can specify
16741: the most recent checked-in version with @samp{-}; and you can specify
16742: the current buffer contents with @samp{+}. Thus, you can compare two
16743: checked-in versions, or compare a checked-in version with the text you
16744: are editing.
16745: @c ??? + and - as args are not implemented yet.
16746:
16747: @c ??? Currently it uses vc-diff-options.
16748: This command works by running the @code{diff} utility, getting the
16749: options from the variable @code{diff-switches}. It displays the output
16750: in a special buffer in another window.
16751:
16752: @node VC Status
16753: @subsection VC Status Commands
16754:
16755: @kindex C-x v l @r{(V19)}
16756: @findex vc-print-log @r{(V19)}
16757: To get the detailed version control status of one file, type @kbd{C-x
16758: v l} (@code{vc-print-log}). It displays the history of changes to the
16759: current file, including the text of the log entries. The output appears
16760: in a separate window.
16761:
16762: When you are working on a large program, it's often useful to find all
16763: the files that are currently locked, or all the files maintained in
16764: version control at all. You can do so using these commands, both of
16765: which operate on the branch of the file system starting at the current
16766: directory.
16767:
16768: @kindex C-x v d @r{(V19)}
16769: @findex vc-directory @r{(V19)}
16770: You can use @kbd{C-x v d} (@code{vc-directory}) to show all the locked
16771: files in or beneath the current directory. This includes all files that
16772: are locked by any user.
16773:
16774: With a prefix argument, @kbd{C-x v d} shows all the version control
16775: activity in the current directory---it lists all files in or beneath the
16776: current directory that are maintained with version control.
16777:
16778: @node Renaming and VC
16779: @subsection Renaming VC Work Files and Master Files
16780:
16781: @findex vc-rename-file @r{(V19)}
16782: When you rename a registered file, you must also rename its master
16783: file correspondingly to get proper results. Use @code{vc-rename-file}
16784: to rename the source file as you specify, and rename its master file
16785: accordingly. It also updates any snapshots (@pxref{Snapshots}) that
16786: mention the file, so that they use the new name; despite this, the
16787: snapshot thus modified may not completely work (@pxref{Snapshot
16788: Caveats}).
16789:
16790: You cannot use @code{vc-rename-file} on a file that is locked by
16791: someone else.
16792:
16793: @code{vc-rename-file} is not bound to a key because it's not likely
16794: to be used frequently.
16795:
16796: @node Snapshots
16797: @subsection Snapshots
16798: @cindex snapshots and version control
16799:
16800: A @dfn{snapshot} is a named set of file versions (one for each
16801: registered file) that you can treat as a unit. One important kind of
16802: snapshot is a @dfn{release}, a (theoretically) stable version of the
16803: system that is ready for distribution to users.
16804:
16805: @menu
16806: * Making Snapshots:: The snapshot facilities.
16807: * Snapshot Caveats:: Things to be careful of, when using snapshots.
16808: @end menu
16809:
16810: @node Making Snapshots
16811: @subsubsection Making and Using Snapshots
16812:
16813: There are two basic commands for snapshots; one makes a
16814: snapshot with a given name, the other retrieves a named snapshot.
16815:
16816: @table @code
16817: @item C-x v s @var{name} @key{RET}
16818: @kindex C-x v s @r{(V19)}
16819: @findex vc-create-snapshot @r{(V19)}
16820: Define the last saved versions of every registered file in or under the
16821: current directory as a snapshot named @var{name}
16822: (@code{vc-create-snapshot}).
16823:
16824: @item C-x v r @var{name} @key{RET}
16825: @kindex C-x v r @r{(V19)}
16826: @findex vc-retrieve-snapshot @r{(V19)}
16827: Check out all registered files at or below the current directory level
16828: using whatever versions correspond to the snapshot @var{name}
16829: (@code{vc-retrieve-snapshot}).
16830:
16831: This function reports an error if any files are locked at or below the
16832: current directory, without changing anything; this is to avoid
16833: overwriting work in progress.
16834: @end table
16835:
16836: You shouldn't need to use @code{vc-retrieve-snapshot} very often; you
16837: can get difference reports between two snapshots without retrieving
16838: either one, using @kbd{C-x =} (@pxref{Comparing Versions}). Thus,
16839: retrieving a snapshot is only necessary if you need to study or compile
16840: portions of the snapshot.
16841:
16842: A snapshot uses a very small amount of resources---just enough to record
16843: the list of file names and which version belongs to the snapshot. Thus,
16844: you need not hesitate to create snapshots whenever they are useful.
16845:
16846: You can give a snapshot name as an argument to @kbd{C-x v =}
16847: (@pxref{Comparing Versions}). Thus, you can use it to compare a
16848: snapshot against the current files, or two snapshots against each other,
16849: or a snapshot against a named version.
16850:
16851: @node Snapshot Caveats
16852: @subsubsection Snapshot Caveats
16853:
16854: @cindex named configurations (RCS)
16855: VC's snapshot facilities are modeled on RCS's named-configuration
16856: support. They use RCS's native facilities for this, so under VC
16857: snapshots made using RCS are visible even when you bypass VC.
16858:
16859: @c !!! worded verbosely to avoid overfull hbox.
16860: For SCCS, VC implements snapshots itself. The files it uses contain
16861: name/file/version-number triples. These snapshots are visible only
16862: through VC.
16863:
16864: File renaming and deletion can create some difficulties with snapshots.
16865: This is not a VC-specific problem, but a general design issue in version
16866: control systems that no one has solved very well yet.
16867:
16868: If you rename a registered file, you need to rename its master along
16869: with it (the function @code{vc-rename-file} does this automatically).
16870: If you are using SCCS, you must also update the records of the snapshot,
16871: to mention the file by its new name (@code{vc-rename-file} does this,
16872: too). This makes the snapshot remain valid for retrieval, but it does
16873: not solve all problems.
16874:
16875: For example, some of the files in the program probably refer to others
16876: by name. At the very least, the makefile probably mentions the file
16877: that you renamed. If you retrieve an old snapshot, the renamed file
16878: is retrieved under its new name, which is not the name that the makefile
16879: expects. So the program won't really work.
16880:
16881: If you use snapshots, don't rename either work files or master files
16882: except by means of @code{vc-rename-file}. It knows how to update
16883: snapshots so that you can still retrieve them. An old snapshot that
16884: refers to a master file that no longer exists under the recorded name is
16885: invalid; VC can no longer retrieve it. It would be beyond the scope of this
16886: manual to explain enough about RCS and SCCS to teach the reader how to
16887: update the snapshots by hand.
16888:
16889: @node Version Headers
16890: @subsection Inserting Version Control Headers
16891:
16892: Sometimes it is convenient to put version identification strings
16893: directly into working files. Certain special strings called
16894: @dfn{version headers} are replaced in each successive version by the
16895: number of that version.
16896:
16897: @kindex C-x v h @r{(V19)}
16898: @findex vc-insert-headers @r{(V19)}
16899: You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
16900: insert a suitable header string.
16901:
16902: @table @kbd
16903: @item C-x v h
16904: Insert headers in a file for use with your version-control system.
16905: @end table
16906:
16907: @vindex vc-header-string @r{(V19)}
16908: @c ??? Currently the name is vc-header-strings
16909: The default header string is @samp{$ld$} for RCS and @samp{%W%} for
16910: SCCS. You can specify other headers to insert by setting the variable
16911: @code{vc-header-string}. Its value (if non-@code{nil}) should be the
16912: string to be inserted. You can also specify a list of strings; then
16913: each string in the list is inserted as a separate header on a line of
16914: its own. (It is often important to use ``superfluous'' backslashes when
16915: writing a Lisp string constant for this use, to prevent the string in
16916: the constant from being interpreted as a header itself if the Emacs Lisp
16917: file containing it is maintained with version control.)
16918:
16919: @vindex vc-comment-alist @r{(V19)}
16920: Each header is inserted surrounded by tabs, inside comment delimiters,
16921: on a new line at the start of the buffer. Normally the ordinary comment
16922: start and comment end strings of the current mode are used, but for
16923: certain modes, there are special comment delimiters for this purpose;
16924: the variable @code{vc-comment-alist} specifies them. Each element of
16925: this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
16926:
16927: @vindex vc-static-header-alist @r{(V19)}
16928: @code{vc-static-header-alist} is consulted to add further strings based
16929: on the name of the buffer. Its value should be a list of
16930: dotted pairs; the @sc{car} of each pair is a regular expression that
16931: should match the buffer name, and the @sc{cdr} is the format to use on
16932: each header. A string is inserted for each file name pattern that
16933: matches the buffer name, and for each header taken from
16934: @code{vc-header-string}. The default value for
16935: @code{vc-static-header-alist} is:
16936:
16937: @example
16938: @group
16939: (("\\.c$" .
16940: "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
16941: #endif /* lint */\n"))
16942: @end group
16943: @end example
16944:
16945: @noindent
16946: which specifies insertion of a string of this form:
16947:
16948: @example
16949: @group
16950:
16951: #ifndef lint
16952: static char vcid[] = "@var{header-string}";
16953: #endif /* lint */
16954: @end group
16955: @end example
16956:
16957: @node Emerge
16958: @section Emerge
16959: @cindex Emerge (V19)
16960: @cindex merging files (V19)
16961:
16962: It's not unusual for programmers to get their signals crossed and modify
16963: the same program in two different directions. To recover from this
16964: confusion, you need to merge the two versions. Emerge makes this
16965: easier.
16966:
16967: @menu
16968: * Overview of Emerge::
16969: * Submodes of Emerge::
16970: * State of Difference::
16971: * Merge Commands::
16972: * Exiting Emerge::
16973: * Combining in Emerge::
16974: * Fine Points of Emerge::
16975: @end menu
16976:
16977: @node Overview of Emerge
16978: @subsection Overview of Emerge
16979:
16980: To start Emerge, run one of these four commands:
16981:
16982: @table @kbd
16983: @item M-x emerge-files
16984: @findex emerge-files @r{(V19)}
16985: Merge two specified files.
16986:
16987: @item M-x emerge-files-with-ancestor
16988: @findex emerge-files-with-ancestor @r{(V19)}
16989: Merge two specified files, with reference to a common ancestor.
16990:
16991: @item M-x emerge-buffers
16992: @findex emerge-buffers @r{(V19)}
16993: Merge two buffers (the currently accessible portions).
16994:
16995: @item M-x emerge-buffers-with-ancestor
16996: @findex emerge-buffers-with-ancestor @r{(V19)}
16997: Merge two buffers (the currently accessible portions) with reference to a
16998: common ancestor in another buffer.
16999: @end table
17000:
17001: @cindex merge buffer (Emerge)
17002: @cindex A and B buffers (Emerge)
17003: The Emerge commands compare two texts, and display the results in three
17004: buffers: one for each input text (the @dfn{A buffer} and the @dfn{B
17005: buffer}), and one (the @dfn{merge buffer}) where merging takes place.
17006: The merge buffer does not show just the differences. Rather, it shows
17007: you the full text, but wherever the input texts differ, you can choose
17008: which one of them to include in the merge buffer.
17009:
17010: If a common ancestor version is available, from which the two texts to
17011: be merged were both derived, Emerge can use it to guess which
17012: alternative is right. Wherever one current version agrees with the
17013: ancestor, Emerge presumes that the other current version is a deliberate
17014: change which should be kept in the merged version. Use the
17015: ``with-ancestor'' commands if you want to specify a common ancestor
17016: text. These commands read three file or buffer names---variant A,
17017: variant B, and the common ancestor.
17018:
17019: After the comparison is done and the buffers are prepared, the actual
17020: merging starts. You control the merging interactively by editing the
17021: merge buffer. The merge buffer shows you a full merged text, not just
17022: differences. For each point where the input texts differ, you can
17023: choose which one of them to include in the merge buffer.
17024:
17025: The merge buffer has a special major mode, Emerge mode, with commands
17026: for making these choices. But you can also edit the buffer with
17027: ordinary Emacs commands.
17028:
17029: At any given time, the attention of Emerge is focused on one particular
17030: difference, called the @dfn{selected} difference. This difference is
17031: marked off in the three buffers by
17032:
17033: @example
17034: vvvvvvvvvvvvvvvvvvvv
17035: @end example
17036:
17037: @noindent
17038: above and
17039:
17040: @example
17041: ^^^^^^^^^^^^^^^^^^^^
17042: @end example
17043:
17044: @noindent
17045: below. Emerge numbers all the differences sequentially and the mode
17046: line always shows the number of the selected difference.
17047:
17048: Normally, the merge buffer starts out with the A version of the text.
17049: But when the A version of a part of the buffer agrees with the common
17050: ancestor, then the B version is preferred for that part.
17051:
17052: Normally, Emerge stores the merged output in place of the first input
17053: text (the A file or buffer). If you give a prefix argument to
17054: @code{emerge-files} or @code{emerge-files-with-ancestor}, it reads the
17055: name of the output file using the minibuffer. (This is the last file
17056: name those commands read.)
17057:
17058: If you abort Emerge with @kbd{C-u q}, the output is not saved.
17059:
17060: @node Submodes of Emerge
17061: @subsection Submodes of Emerge
17062:
17063: You can choose between two modes for giving merge commands: Fast mode
17064: and Edit mode. In Fast mode, basic Emerge commands are single
17065: characters, but ordinary Emacs commands are disabled. This is
17066: convenient if you use only Emerge commands.
17067:
17068: In Edit mode, all Emerge commands start with the prefix character
17069: @kbd{C-c}, and the normal Emacs commands are also available. This
17070: allows editing the merge buffer, but slows down Emerge operations.
17071:
17072: Use @kbd{e} to switch to Edit mode, and @kbd{f} to switch to Fast mode.
17073: The mode line indicates Edit and Fast modes with @samp{E} and @samp{F}.
17074:
17075: Emerge has two additional submodes that affect how particular merge
17076: commands work: Auto Advance mode and Skip Prefers mode.
17077:
17078: If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
17079: advance to the next difference. This lets you go through the merge
17080: faster doing ordinary things. The mode line indicates Auto Advance mode
17081: with @samp{A}.
17082:
17083: If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands skip
17084: over differences in states prefer-A and prefer-B. Thus you will only
17085: see differences for which neither version is presumed ``correct''. The
17086: mode line indicates Skip Prefers mode with @samp{S}.
17087:
17088: @findex emerge-auto-advance-mode @r{(V19)}
17089: @findex emerge-skip-prefers-mode @r{(V19)}
17090: Use the command @code{emerge-auto-advance-mode} to set or clear Auto
17091: Advance mode. Use @code{emerge-skip-prefers-mode} to set or clear Skip
17092: Prefers mode. A positive argument turns the mode on, a nonpositive
17093: argument turns it off, and no argument toggles it.
17094:
17095: @node State of Difference
17096: @subsection State of a Difference
17097:
17098: In the merge buffer, a difference is marked
17099: @samp{vvvvvvvvvvvvvvvvvvvv} above and @samp{^^^^^^^^^^^^^^^^^^^^}
17100: below. Such a difference can have one of seven states:
17101:
17102: @table @asis
17103: @item A
17104: The difference is showing the A version. The @kbd{a} command always
17105: produces this state; the mode line indicates it with @samp{A}.
17106:
17107: @item B
17108: The difference is showing the B version. The @kbd{b} command always
17109: produces this state; the mode line indicates it with @samp{B}.
17110:
17111: @item default-A
17112: @itemx default-B
17113: The difference is showing the A or the B state by default, because you
17114: haven't made a choice. All differences start in the default-A state
17115: (and thus the merge buffer is a copy of the A buffer), except those for
17116: which one alternative is ``preferred'' (see below).
17117:
17118: When you select a difference, its state changes from default-A or
17119: default-B to plain A or B. Thus, the selected difference never has
17120: state default-A or default-B, and these states are never displayed in
17121: the mode line.
17122:
17123: The command @kbd{d a} chooses default-A as the default state, and @kbd{d
17124: b} chooses default-B. This chosen default applies to all differences
17125: which you haven't selected and for which no alternative is preferred.
17126: If you are moving through the merge sequentially, the differences you
17127: haven't selected are those following the selected one. Thus, while
17128: moving sequentially, you can effectively make the A version the default
17129: for some sections of the merge buffer and the B version the default for
17130: others by using @kbd{d a} and @kbd{d b} at the end of each section.
17131:
17132: @item prefer-A
17133: @itemx prefer-B
17134: The difference is showing the A or B state because it is
17135: @dfn{preferred}. This means that you haven't made an explicit choice,
17136: but one alternative seems likely to be right because the other
17137: alternative agrees with the common ancestor. Thus, where the A buffer
17138: agrees with the common ancestor, the B version is preferred, because
17139: chances are it is the one that was actually changed.
17140:
17141: These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
17142:
17143: @item combined
17144: The difference is showing a combination of the A and B states, as a
17145: result of the @kbd{x c} or @kbd{x C} commands.
17146:
17147: Once a difference is in this state, the @kbd{a} and @kbd{b} commands
17148: don't do anything to it unless you give them a prefix argument.
17149:
17150: The mode line displays this state as @samp{comb}.
17151: @end table
17152:
17153: @node Merge Commands
17154: @subsection Merge Commands
17155:
17156: Here are the Merge commands for Fast mode; in Edit mode, precede these with
17157: @kbd{C-c} and turn all the letters into control characters.
17158:
17159: @table @kbd
17160: @item p
17161: Select the previous difference.
17162:
17163: @item n
17164: Select the next difference.
17165:
17166: @item a
17167: Choose the A version of this difference.
17168:
17169: @item b
17170: Choose the B version of this difference.
17171:
17172: @item j
17173: Select a particular difference; specify the sequence number of that
17174: difference as a prefix argument.
17175:
17176: @item M-x emerge-select-difference
17177: @c ??? This isn't true yet.
17178: Select the run of differences containing the current location. You can
17179: use this command in the merge buffer or in the A or B buffer.
17180:
17181: @item q
17182: Quit---finish the merge. With an argument, abort the merge.
17183:
17184: @item f
17185: Go into fast mode.
17186:
17187: @item e
17188: Go into edit mode.
17189:
17190: @item l
17191: Recenter (like @kbd{C-l}) all three windows.
17192:
17193: @item -
17194: Specify part of a prefix numeric argument.
17195: @c Don't use itemx here, it is confusing in printed output!
17196: @itemx @var{digit}
17197: Also specify part of a prefix numeric argument.
17198:
17199: @item d a
17200: Choose the A version as the default from here down in
17201: the merge buffer.
17202:
17203: @item d b
17204: Choose the B version as the default from here down in
17205: the merge buffer.
17206:
17207: @item c a
17208: Copy the A version of this difference into the kill ring.
17209:
17210: @item c b
17211: Copy the B version of this difference into the kill ring.
17212:
17213: @item i a
17214: Insert the A version of this difference at the point.
17215:
17216: @item i b
17217: Insert the B version of this difference at the point.
17218:
17219: @item m
17220: Put the point and mark around the difference region.
17221:
17222: @item ^
17223: Scroll all three windows down (like @kbd{M-v}).
17224:
17225: @item v
17226: Scroll all three windows up (like @kbd{C-v}).
17227:
17228: @item <
17229: Scroll all three windows left (like @kbd{C-x <}).
17230:
17231: @item >
17232: Scroll all three windows right (like @kbd{C-x >}).
17233:
17234: @item |
17235: Reset horizontal scroll on all three windows.
17236:
17237: @item x 1
17238: Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
17239: to full size.)
17240:
17241: @item x c
17242: Combine the two versions of this difference.
17243:
17244: @item x f
17245: Show the files/buffers Emerge is operating on in Help window.
17246: (Use @kbd{C-u l} to restore windows.)
17247:
17248: @item x j
17249: Join this difference with the following one.
17250: (@kbd{C-u x j} joins this difference with the previous one.)
17251:
17252: @item x s
17253: Split this difference into two differences. Before you use this
17254: command, position point in each of the three buffers to the place where
17255: you want to split the difference.
17256:
17257: @item x t
17258: Trim identical lines off top and bottom of the difference.
17259: Such lines occur when the A and B versions are
17260: identical but differ from the ancestor version.
17261: @end table
17262:
17263: @node Exiting Emerge
17264: @subsection Exiting Emerge
17265:
17266: The @kbd{q} (@code{emerge-quit}) command finishes the merge, storing the
17267: results into the output file. It restores the A and B buffers to their
17268: proper contents, or kills them if they were created by Emerge. It also
17269: disables the Emerge commands in the merge buffer, since executing them
17270: later could damage the contents of the various buffers.
17271:
17272: @kbd{C-u q} aborts the merge. Aborting means that Emerge does not write
17273: the output file.
17274:
17275: If Emerge was called from another Lisp program, then its return value
17276: is @code{t} or @code{nil} to indicate success or failure.
17277:
17278: @node Combining in Emerge
17279: @subsection Combining the Two Versions
17280:
17281: Sometimes you want to keep @emph{both} alternatives for a particular
17282: locus. To do this, use @kbd{x c}, which edits the merge buffer like this:
17283:
17284: @example
17285: @group
17286: #ifdef NEW
17287: @var{version from A file}
17288: #else /* NEW */
17289: @var{version from B file}
17290: #endif /* NEW */
17291: @end group
17292: @end example
17293:
17294: @vindex emerge-combine-template @r{(V19)}
17295: While this example shows C preprocessor conditionals delimiting the two
17296: alternative versions, you can specify the strings you want by setting
17297: the variable @code{emerge-combine-template} to a list of three strings.
17298: The default setting, which produces the results shown above, looks like this:
17299:
17300: @example
17301: @group
17302: ("#ifdef NEW\n"
17303: "#else /* NEW */\n"
17304: "#endif /* NEW */\n")
17305: @end group
17306: @end example
17307: @c ??? This is not how it currently works;
17308: @c ??? emerge.el needs to be changed.
17309:
17310: @c ??? Must change the mechanism that disables saving during emerge
17311: @c ??? to use a write-file-function instead.
17312:
17313: @c ??? Emerge should use flag strings that start with # for C programs
17314: @c ??? and with ; for Lisp programs.
17315:
17316: @node Fine Points of Emerge
17317: @subsection Fine Points of Emerge
17318:
17319: You can have any number of merges going at once---just don't use any
17320: one buffer as input to more than one merge at once, since that will
17321: cause the read-only/modified/auto-save status save-and-restore to
17322: screw up.
17323:
17324: Starting Emerge can take a long time because it needs to compare the
17325: files. Emacs can't do anything else until @code{diff} finishes. Perhaps in
17326: the future someone will change Emerge to do the comparison in the
17327: background when the input files are large---then you could keep on doing
17328: other things with Emacs until Emerge gets ready to accept commands.
17329:
17330: @ignore
17331: @c ??? This name hasn't been changed yet.
17332: @vindex emerge-ok-lines-regexp @r{(V19)}
17333: Emerge tests each of the lines that differ against the regular
17334: expression @code{emerge-ok-lines-regexp}. If a line fails to fit the
17335: pattern, then Emerge displays a warning instead of displaying the merge
17336: buffer. After you get the warning, you must switch to the merge buffer
17337: and either continue the merge or abort it.
17338: @end ignore
17339:
17340: @vindex emerge-startup-hook @r{(V19)}
17341: After the merge has been set up, Emerge runs the hooks in
17342: @code{emerge-startup-hook}.
17343:
17344: During the merge, you musn't try to edit the A and B buffers yourself.
17345: Emerge modifies them temporarily, but ultimately puts them back the way
17346: they were.
17347:
17348: @node Debuggers
17349: @section Running Debuggers Under Emacs
17350: @cindex debuggers
17351: @cindex GDB
17352: @cindex DBX
17353: @cindex SDB
17354:
17355: @c Do you believe in GUD?
17356: The GUD (Grand Unified Debugger) library provides an interface to various
17357: symbolic debuggers from within Emacs. We recommend the debugger GDB,
17358: which is free software, but you can also run DBX or SDB if you have them.
17359:
17360: @menu
17361: * Starting GUD:: How to start a debugger subprocess.
17362: * Debugger Operation:: Connection between the debugger and source buffers.
17363: * Commands of GUD:: Keybindings for common commands.
17364: * GUD Customization:: Defining your own commands for GUD.
17365: @end menu
17366:
17367: @node Starting GUD
17368: @subsection Starting GUD
17369:
17370: There are three commands for starting a debugger. Each corresponds to a
17371: particular debugger program.
17372:
17373: @table @kbd
17374: @item M-x gdb @key{RET} @var{file} @key{RET}
17375: @itemx M-x dbx @key{RET} @var{file} @key{RET}
17376: @findex gdb @r{(V19)}
17377: @findex dbx @r{(V19)}
17378: Run GDB or DBX in a subprocess of Emacs. Both of these commands select
17379: the buffer used for input and output to the debugger.
17380:
17381: @item M-x sdb @key{RET} @var{file} @key{RET}
17382: @findex sdb @r{(V19)}
17383: Run SDB in a subprocess of Emacs. SDB's messages do not mention file
17384: names, so the Emacs interface to SDB depends on having a tags table
17385: (@pxref{Tags}) to find which file each function is in. If you have not
17386: visited a tags table or the tags table doesn't list one of the
17387: functions, you get a message saying @samp{The sdb support requires a
17388: valid tags table to work}. If this happens, generate a valid tags table
17389: in the working directory and try again.
17390: @end table
17391:
17392: You can only run one debugger process at a time.
17393:
17394: @node Debugger Operation
17395: @subsection Debugger Operation
17396:
17397: When you run a debugger with GUD, the debugger displays source files
17398: via Emacs---Emacs finds the source file and moves point to the line
17399: where the program is executing. An arrow (@samp{=>}) indicates the
17400: current execution line, and it stays put even if you move the cursor.
17401:
17402: You can start editing the file at any time. The arrow is not part of
17403: the file's text; it appears only on the screen. If you do modify a
17404: source file, keep in mind that inserting or deleting lines will throw
17405: off the arrow's positioning; GUD has no way of figuring out which line
17406: corresponded before your changes to the line number in a debugger
17407: message. Also, you'll typically have to recompile and restart the
17408: program for your changes to be reflected in the debugger's tables.
17409:
17410: If you wish, you can control your debugger process entirely through the
17411: debugger buffer, which uses a variant of Shell mode. All the usual
17412: commands for your debugger are available, and you can use the Shell mode
17413: history commands to repeat them.
17414:
17415: @node Commands of GUD
17416: @subsection Commands of GUD
17417:
17418: GUD provides a command available in all buffers for setting
17419: breakpoints. This command is defined globally because you need to use
17420: it in the source files' buffers.
17421:
17422: @table @kbd
17423: @item C-x @key{SPC}
17424: @kindex C-x @key{SPC} @r{(V19)}
17425: Set a breakpoint on the line that point is on.
17426: @end table
17427:
17428: The debugger buffer has a number of keybindings for invoking common
17429: debugging commands quickly:
17430:
17431: @table @kbd
17432: @item C-c C-l
17433: @kindex C-c C-l @r{(GUD in V19)}
17434: @findex gud-refresh @r{(V19)}
17435: Display in another window the last line referred to in the GUD
17436: buffer (that is, the line indicated in the last location message).
17437: This runs the command @code{gud-refresh}.
17438:
17439: @item C-c C-s
17440: @kindex C-c C-s @r{(GUD in V19)}
17441: @findex gud-step @r{(V19)}
17442: Execute a single line of code (@code{gud-step}). If the code contains
17443: a function call, execution stops after entering the called function.
17444:
17445: @item C-c C-n
17446: @kindex C-c C-n @r{(GUD in V19)}
17447: @findex gud-next @r{(V19)}
17448: Execute a single line of code, stepping across entire function calls
17449: at full speed (@code{gud-next}).
17450:
17451: @item C-c C-i
17452: @kindex C-c C-i @r{(GUD in V19)}
17453: @findex gud-stepi @r{(V19)}
17454: Execute a single machine instruction (@code{gud-stepi}).
17455:
17456: @item C-c C-c
17457: @kindex C-c C-c @r{(GUD in V19)}
17458: @findex gud-cont @r{(V19)}
17459: Continue execution until the next breakpoint, or other event that would
17460: normally stop the program (@code{gud-cont}).
17461: @end table
17462:
17463: The above commands are common to all supported debuggers. If you are
17464: using GDB or (some versions of) DBX, these additional commands are available:
17465:
17466: @table @kbd
17467: @item C-c <
17468: @kindex C-c < @r{(GUD in V19)}
17469: @findex gud-up @r{(V19)}
17470: Select the next enclosing stack frame (@code{gud-up}). This is
17471: equivalent to the @samp{up} command.
17472:
17473: @item C-c >
17474: @kindex C-c > @r{(GUD in V19)}
17475: @findex gud-down @r{(V19)}
17476: Select the next inner stack frame (@code{gud-down}). This is
17477: equivalent to the @samp{down} command.
17478: @end table
17479:
17480: If you are using GDB, two additional keybindings are available:
17481:
17482: @table @kbd
17483: @item C-c C-f
17484: @kindex C-c C-f @r{(GUD in V19)}
17485: @findex gud-finish @r{(V19)}
17486: Run the program until the selected stack frame returns (or until it
17487: stops for some other reason).
17488:
17489: @item @key{TAB}
17490: Complete the symbol in the buffer before point, using the set of all
17491: symbols known to GDB.
17492: @end table
17493:
17494: These commands interpret a prefix argument as a repeat count, when that
17495: makes sense.
17496:
17497: After each command that changes the program counter, GUD displays the
17498: new current source line, and updates the location of the arrow.
17499:
17500: @node GUD Customization
17501: @subsection GUD Customization
17502:
17503: @vindex gdb-mode-hook
17504: @vindex dbx-mode-hook
17505: @vindex sdb-mode-hook
17506: On startup, GUD executes one of the following hooks:
17507: @code{gdb-mode-hook}, if you are using GDB; @code{dbx-mode-hook}, if you
17508: are using DBX; and @code{sdb-mode-hook}, if you are using SDB. You can
17509: use these hooks to define custom keybindings for the debugger
17510: interaction buffer.
17511:
17512: Here is a convenient way to define a command that sends a particular
17513: command string to the debugger, and set up a key binding for it in the
17514: debugger interaction buffer:
17515:
17516: @findex gud-def @r{(V19)}
17517: @example
17518: (gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
17519: @end example
17520:
17521: This defines a command named @var{function} which sends
17522: @var{cmdstring} to the debugger process, with documentation string
17523: @var{docstring}, and binds it to @var{binding} in the debugger buffer's
17524: mode. (If @var{binding} is @code{nil}, this defines the command but
17525: does not make a binding for it; you can make a binding explicitly,
17526: perhaps using one of the above hooks.)
17527:
17528: Commands defined with @code{gud-def} handle prefix arguments by
17529: passing them to the debugger, appended to end of @var{cmdstring} with a
17530: space in between. (This use of prefix arguments works with GDB and DBX,
17531: but not with SDB.)
17532:
17533: You can also set up commands that you can send to the debugger while in
17534: another buffer, such as a source file. Set the variable
17535: @code{gud-commands} to a list of strings containing debugger commands
17536: you might want to send.
17537:
17538: @table @kbd
17539: @item C-x &
17540: @kindex C-x & @r{(GUD in V19)}
17541: @findex send-gud-command @r{(V19)}
17542: Send a custom command to the debugger process
17543: (@code{send-gud-command}). Normally, send the @sc{car} of the
17544: @code{gud-commands} list; a prefix argument specifies which element of
17545: that list to use (counting from 0).
17546:
17547: If the string contains @samp{%s}, @kbd{C-x &} substitutes a numeric
17548: value found in the buffer at or near point. It looks for decimal,
17549: octal, or hexadecimal numbers, with @samp{0x} allowed. This lets you
17550: define commands to chase pointers whose numeric values have been
17551: displayed.
17552: @end table
17553:
17554: @node Other New Modes
17555: @section Other New Modes
17556:
17557: There is now a Perl mode for editing Perl programs and an Icon mode
17558: for editing Icon programs.
17559:
17560: @cindex C++ mode @r{(V19)}
17561: @findex fill-c++-comment @r{(V19)}
17562: C++ mode is like C mode, except that it understands C++ comment syntax
17563: and certain other differences between C and C++. It also has a command
17564: @code{fill-c++-comment} which fills a paragraph made of comment lines.
17565: The command @code{comment-region} is useful in C++ mode for commenting
17566: out several consecutive lines, or removing the commenting out of such
17567: lines.
17568:
17569: @cindex WordStar mode @r{(V19)}
17570: WordStar emulation is available---type @kbd{M-x wordstar-mode}.
17571: For more information, type @kbd{C-h f wordstar-mode @key{RET}}.
17572:
17573: @cindex Buffer Menu mode @r{(V19)}
17574: The command @kbd{C-o} in Buffer Menu mode now displays the current
17575: line's buffer in another window but does not select it. This is like
17576: the existing command @kbd{o} which selects the current line's buffer in
17577: another window.
17578:
17579: @menu
17580: * Asm Mode:: A major mode for editing assembler files.
17581: * Edebug Mode:: A new Lisp debugger.
17582: * Editing Binary Files::Hexl mode lets you edit a binary file as numbers.
17583: @end menu
17584:
17585: @node Asm Mode
17586: @subsection Asm Mode
17587:
17588: @cindex Asm mode @r{(V19)}
17589: Asm mode is a new major mode for editing files of assembler code.
17590: It defines these commands:
17591:
17592: @table @kbd
17593: @item @key{TAB}
17594: @code{tab-to-tab-stop}.
17595: @item @key{LFD}
17596: Insert a newline and then indent using @code{tab-to-tab-stop}.
17597: @item :
17598: Insert a colon and then remove the indentation from before the label
17599: preceding colon. Then do @code{tab-to-tab-stop}.
17600: @item ;
17601: Insert or align a comment.
17602: @end table
17603:
17604: @node Edebug Mode
17605: @subsection Edebug Mode
17606: @cindex Edebug mode @r{(V19)}
17607:
17608: Edebug is a new source-level debugger for Emacs Lisp programs.
17609:
17610: @findex edebug-defun @r{(V19)}
17611: To use Edebug, use the command @kbd{M-x edebug-defun} to ``evaluate'' a
17612: function definition in an Emacs Lisp file. We put ``evaluate'' in
17613: quotation marks because it doesn't just evaluate the function, it also
17614: inserts additional information to support source-level debugging.
17615:
17616: You must also do this:
17617:
17618: @example
17619: (setq debugger 'edebug-debug)
17620: @end example
17621:
17622: @noindent
17623: to cause errors and single-stepping to use Edebug instead of the usual
17624: Emacs Lisp debugger.
17625:
17626: @c ??? Need xref to Edebug manual
17627: For more information, see @cite{The Emacs Extensions Manual}, which
17628: should be included in the Emacs 19 distribution.
17629:
17630: @node Editing Binary Files
17631: @subsection Editing Binary Files
17632:
17633: @cindex Hexl mode @r{(V19)}
17634: @cindex editing binary files @r{(V19)}
17635: There is a new major mode for editing binary files: Hexl mode. To use
17636: it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit the
17637: file. This command converts the file's contents to hexadecimal and lets
17638: you edit the translation. When you save the file, it is converted
17639: automatically back to binary.
17640:
17641: You can also use @kbd{M-x hexl-mode} to translate an existing buffer
17642: into hex. This is useful if you visit a file normally and discover it
17643: is a binary file.
17644:
17645: Hexl mode has a few other commands:
17646:
17647: @c I don't think individual index entries for these commands are useful--RMS.
17648: @table @kbd
17649: @item C-M-d
17650: Insert a byte with a code typed in decimal.
17651:
17652: @item C-M-o
17653: Insert a byte with a code typed in octal.
17654:
17655: @item C-M-x
17656: Insert a byte with a code typed in hex.
17657:
17658: @item C-x [
17659: Move to the beginning of a 1k-byte ``page''.
17660:
17661: @item C-x ]
17662: Move to the end of a 1k-byte ``page''.
17663:
17664: @item M-g
17665: Move to an address specified in hex.
17666:
17667: @item M-j
17668: Move to an address specified in decimal.
17669:
17670: @item C-c C-c
17671: Leave Hexl mode, going back to the major mode this buffer had before you
17672: invoked @code{hexl-mode}.
17673: @end table
17674:
17675: @node Key Sequence Changes
17676: @section Changes in Key Sequences
17677: @cindex function keys (V19)
17678: @cindex mouse buttons (V19)
17679: @cindex key sequence changes (V19)
17680:
17681: In Emacs 18, a key sequence was a sequence of characters, which
17682: represented keyboard input.
17683:
17684: In Emacs 19, you can still use a sequence of characters as a key
17685: sequence, but you aren't limited to characters. You can also use Lisp
17686: symbols which represent terminal function keys or mouse buttons. If the
17687: function key has a word as its label, then that word is also the name of
17688: the symbol which represents the function key. Other function keys
17689: are assigned Lisp names as follows:
17690:
17691: @table @asis
17692: @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
17693: Keypad keys (to the right of the regular keyboard), with names or punctuation
17694: @item @code{kp-0}, @code{kp-1}, @dots{}
17695: Keypad keys with digits
17696: @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
17697: Keypad PF keys
17698: @item @code{left}, @code{up}, @code{right}, @code{down}
17699: Cursor arrow keys
17700: @end table
17701:
17702: A key sequence which contains non-characters must be a vector rather
17703: than a string.
17704:
17705: Thus, to bind function key @samp{f1} to @code{rmail}, write the
17706: following:
17707:
17708: @example
17709: (global-set-key [f1] 'rmail)
17710: @end example
17711:
17712: @noindent
17713: (To find the name of a key, type @kbd{C-h k} and then the key.)
17714:
17715: To bind the right-arrow key to the command @code{forward-char},
17716: you can use this expression:
17717:
17718: @example
17719: (global-set-key [right] 'forward-char)
17720: @end example
17721:
17722: @noindent
17723: using the Lisp syntax for a vector containing the symbol @code{right}.
17724:
17725: And this is how to make @kbd{C-x @key{RIGHTARROW}} move forward a page:
17726:
17727: @example
17728: (global-set-key [?\C-x right] 'forward-page)
17729: @end example
17730:
17731: @noindent
17732: where @code{?\C-x} is the Lisp syntax for an integer whose value is the
17733: code for the character @kbd{C-x}.
17734:
17735: You can use modifier keys such as @key{CTRL}, @key{META} and @key{SHIFT}
17736: with function keys. To represent these modifiers, prepend the strings
17737: @samp{C-}, @samp{M-} and @samp{S-} to the symbol name. Thus, here is
17738: how to make @kbd{M-@key{RIGHTARROW}} move forward a word:
17739:
17740: @example
17741: (global-set-key [M-right] 'forward-word)
17742: @end example
17743:
17744: Emacs uses symbols to designate mouse buttons, too.
17745: The ordinary mouse events in Emacs are @dfn{click} events; these
17746: happen when you press a button and release it without moving the mouse.
17747: You can also get @dfn{drag} events, when you move the mouse while
17748: holding the button down. Drag events happen when you finally let go
17749: of the button.
17750:
17751: The symbols for basic click events are @code{mouse-1} for the leftmost
17752: button, @code{mouse-2} for the next, and so on. Here is how you can
17753: redefine the second mouse button to split the current window:
17754:
17755: @findex global-set-key @r{(V19)}
17756: @example
17757: (global-set-key [mouse-2] 'split-window-vertically)
17758: @end example
17759:
17760: The symbols for drag events are similar, but have the prefix @samp{drag-}
17761: before the word @samp{mouse}. For example, dragging the left button
17762: generates a @code{drag-mouse-1} event.
17763:
17764: You can also request events when the mouse button is pressed down.
17765: These events start with @samp{down-} instead of @samp{drag-}. Such
17766: events are generated only if they have key bindings. When you get a
17767: button-down event, a corresponding click or drag event will always
17768: follow.
17769:
17770: The symbols for mouse events also indicate the status of the modifier
17771: keys, with the usual prefixes @samp{C-}, @samp{M-} and @samp{S-}.
17772: These always follow @samp{drag-} or @samp{down-}.
17773: @c ??? This is a change; currently they precede.
17774:
17775: When mouse events occur in special parts of a frame or window, such as a
17776: mode line or a scroll bar, the event symbol shows nothing special. The
17777: information about the special part is implicit in other data (the screen
17778: location of the event). But @code{read-key-sequence} figures out this
17779: aspect of the event, and encodes it with make-believe prefix keys, all
17780: of which are symbols: @code{mode-line}, @code{vertical-line},
17781: @code{horizontal-scrollbar} and @code{vertical-scrollbar}. Thus, to
17782: define the command for clicking the left button in a mode line, you
17783: could use this key sequence:
17784:
17785: @example
17786: [mode-line mouse-1]
17787: @end example
17788:
17789: You are not limited to defining individual function keys or mouse
17790: buttons; these can appear anywhere in a key sequence, just as characters
17791: can. You can even mix together all three kinds of inputs in one key
17792: sequence---but mixing mouse buttons with keyboard inputs is probably not
17793: convenient for actual use.
17794:
17795: @node Hook Changes
17796: @section Changes Regarding Hooks
17797: @cindex normal hook (V19)
17798: @cindex hook variable (V19)
17799:
17800: A @dfn{hook variable} is a variable that exists so that you can store in
17801: it functions for Emacs to call on certain occasions. (The functions that
17802: you put in hook variables are called @dfn{hook functions}.) Emacs 19
17803: has a new convention for naming hook variables that indicates more
17804: reliably how to use them.
17805:
17806: All the variables whose names end in @samp{-hook} are @dfn{normal
17807: hooks}; their values are lists of functions to be called with no
17808: arguments. You can use @code{add-hook} (see below) to install hook
17809: functions in these hooks. We have made all Emacs hooks into normal
17810: hooks except when there is some reason this won't work.
17811:
17812: A few hook-like variables are @dfn{abnormal}---they don't use the normal
17813: convention. This is either because the user-supplied functions receive
17814: arguments, or because their return values matter. These variables have
17815: names that end in @samp{-function} (if the value is a single function)
17816: or @samp{-functions} (if the value is a list of functions).
17817:
17818: Thus, you can always tell from the variable's name precisely how to
17819: install a new hook function in the variable. If the name indicates a
17820: normal hook, then you also know how to write your hook function.
17821:
17822: @findex add-hook @r{(V19)}
17823: To add a hook function to a normal hook, use @code{add-hook}. It takes
17824: care of adding a new hook function to any functions already installed in
17825: a given hook. It takes two arguments, the hook symbol and the function
17826: to add. For example,
17827:
17828: @example
17829: (add-hook 'text-mode-hook 'my-text-hook-function)
17830: @end example
17831:
17832: @noindent
17833: is how to arrange to call @code{my-text-hook-function} when entering
17834: Text mode or related modes.
17835: @vindex pre-abbrev-expand-hook @r{(V19)}
17836: @vindex kill-buffer-hook @r{(V19)}
17837: Two new hooks are worth noting here. Expansion of an abbrev
17838: first runs the hook @code{pre-abbrev-expand-hook}.
17839: @code{kill-buffer-hook} now runs whenever a buffer is killed.
17840: @c end antenews
17841:
17842: @node Manifesto,, Version 19, Top
17843: @unnumbered The GNU Manifesto
17844:
17845: @b{By Richard M. Stallman, 1986}
17846:
17847: @unnumberedsec What's GNU? Gnu's Not Unix!
17848:
17849: GNU, which stands for Gnu's Not Unix, is the name for the complete
17850: Unix-compatible software system which I am writing so that I can give it
17851: away free to everyone who can use it. Several other volunteers are helping
17852: me. Contributions of time, money, programs and equipment are greatly
17853: needed.
17854:
17855: So far we have an Emacs text editor with Lisp for writing editor commands,
17856: a source level debugger, a yacc-compatible parser generator, a linker, and
17857: around 35 utilities. A shell (command interpreter) is nearly completed. A
17858: new portable optimizing C compiler has compiled itself and may be released
17859: this year. An initial kernel exists but many more features are needed to
17860: emulate Unix. When the kernel and compiler are finished, it will be
17861: possible to distribute a GNU system suitable for program development. We
17862: will use @TeX{} as our text formatter, but an nroff is being worked on. We
17863: will use the free, portable X window system as well. After this we will
17864: add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of
17865: other things, plus on-line documentation. We hope to supply, eventually,
17866: everything useful that normally comes with a Unix system, and more.
17867:
17868: GNU will be able to run Unix programs, but will not be identical to Unix.
17869: We will make all improvements that are convenient, based on our experience
17870: with other operating systems. In particular, we plan to have longer
17871: filenames, file version numbers, a crashproof file system, filename
17872: completion perhaps, terminal-independent display support, and perhaps
17873: eventually a Lisp-based window system through which several Lisp programs
17874: and ordinary Unix programs can share a screen. Both C and Lisp will be
17875: available as system programming languages. We will try to support UUCP,
17876: MIT Chaosnet, and Internet protocols for communication.
17877:
17878: GNU is aimed initially at machines in the 68000/16000 class with virtual
17879: memory, because they are the easiest machines to make it run on. The extra
17880: effort to make it run on smaller machines will be left to someone who wants
17881: to use it on them.
17882:
17883: To avoid horrible confusion, please pronounce the `G' in the word `GNU'
17884: when it is the name of this project.
17885:
17886: @unnumberedsec Why I Must Write GNU
17887:
17888: I consider that the golden rule requires that if I like a program I must
17889: share it with other people who like it. Software sellers want to divide
17890: the users and conquer them, making each user agree not to share with
17891: others. I refuse to break solidarity with other users in this way. I
17892: cannot in good conscience sign a nondisclosure agreement or a software
17893: license agreement. For years I worked within the Artificial Intelligence
17894: Lab to resist such tendencies and other inhospitalities, but eventually
17895: they had gone too far: I could not remain in an institution where such
17896: things are done for me against my will.
17897:
17898: So that I can continue to use computers without dishonor, I have decided to
17899: put together a sufficient body of free software so that I will be able to
17900: get along without any software that is not free. I have resigned from the
17901: AI lab to deny MIT any legal excuse to prevent me from giving GNU away.
17902:
17903: @unnumberedsec Why GNU Will Be Compatible with Unix
17904:
17905: Unix is not my ideal system, but it is not too bad. The essential features
17906: of Unix seem to be good ones, and I think I can fill in what Unix lacks
17907: without spoiling them. And a system compatible with Unix would be
17908: convenient for many other people to adopt.
17909:
17910: @unnumberedsec How GNU Will Be Available
17911:
17912: GNU is not in the public domain. Everyone will be permitted to modify and
17913: redistribute GNU, but no distributor will be allowed to restrict its
17914: further redistribution. That is to say, proprietary modifications will not
17915: be allowed. I want to make sure that all versions of GNU remain free.
17916:
17917: @unnumberedsec Why Many Other Programmers Want to Help
17918:
17919: I have found many other programmers who are excited about GNU and want to
17920: help.
17921:
17922: Many programmers are unhappy about the commercialization of system
17923: software. It may enable them to make more money, but it requires them to
17924: feel in conflict with other programmers in general rather than feel as
17925: comrades. The fundamental act of friendship among programmers is the
17926: sharing of programs; marketing arrangements now typically used essentially
17927: forbid programmers to treat others as friends. The purchaser of software
17928: must choose between friendship and obeying the law. Naturally, many decide
17929: that friendship is more important. But those who believe in law often do
17930: not feel at ease with either choice. They become cynical and think that
17931: programming is just a way of making money.
17932:
17933: By working on and using GNU rather than proprietary programs, we can be
17934: hospitable to everyone and obey the law. In addition, GNU serves as an
17935: example to inspire and a banner to rally others to join us in sharing.
17936: This can give us a feeling of harmony which is impossible if we use
17937: software that is not free. For about half the programmers I talk to, this
17938: is an important happiness that money cannot replace.
17939:
17940: @unnumberedsec How You Can Contribute
17941:
17942: I am asking computer manufacturers for donations of machines and money.
17943: I'm asking individuals for donations of programs and work.
17944:
17945: One consequence you can expect if you donate machines is that GNU will run
17946: on them at an early date. The machines should be complete, ready to use
17947: systems, approved for use in a residential area, and not in need of
17948: sophisticated cooling or power.
17949:
17950: I have found very many programmers eager to contribute part-time work for
17951: GNU. For most projects, such part-time distributed work would be very hard
17952: to coordinate; the independently-written parts would not work together.
17953: But for the particular task of replacing Unix, this problem is absent. A
17954: complete Unix system contains hundreds of utility programs, each of which
17955: is documented separately. Most interface specifications are fixed by Unix
17956: compatibility. If each contributor can write a compatible replacement for
17957: a single Unix utility, and make it work properly in place of the original
17958: on a Unix system, then these utilities will work right when put together.
17959: Even allowing for Murphy to create a few unexpected problems, assembling
17960: these components will be a feasible task. (The kernel will require closer
17961: communication and will be worked on by a small, tight group.)
17962:
17963: If I get donations of money, I may be able to hire a few people full or
17964: part time. The salary won't be high by programmers' standards, but I'm
17965: looking for people for whom building community spirit is as important as
17966: making money. I view this as a way of enabling dedicated people to devote
17967: their full energies to working on GNU by sparing them the need to make a
17968: living in another way.
17969:
17970: @unnumberedsec Why All Computer Users Will Benefit
17971:
17972: Once GNU is written, everyone will be able to obtain good system software
17973: free, just like air.
17974:
17975: This means much more than just saving everyone the price of a Unix license.
17976: It means that much wasteful duplication of system programming effort will
17977: be avoided. This effort can go instead into advancing the state of the
17978: art.
17979:
17980: Complete system sources will be available to everyone. As a result, a user
17981: who needs changes in the system will always be free to make them himself,
17982: or hire any available programmer or company to make them for him. Users
17983: will no longer be at the mercy of one programmer or company which owns the
17984: sources and is in sole position to make changes.
17985:
17986: Schools will be able to provide a much more educational environment by
17987: encouraging all students to study and improve the system code. Harvard's
17988: computer lab used to have the policy that no program could be installed on
17989: the system if its sources were not on public display, and upheld it by
17990: actually refusing to install certain programs. I was very much inspired by
17991: this.
17992:
17993: Finally, the overhead of considering who owns the system software and what
17994: one is or is not entitled to do with it will be lifted.
17995:
17996: Arrangements to make people pay for using a program, including licensing of
17997: copies, always incur a tremendous cost to society through the cumbersome
17998: mechanisms necessary to figure out how much (that is, which programs) a
17999: person must pay for. And only a police state can force everyone to obey
18000: them. Consider a space station where air must be manufactured at great
18001: cost: charging each breather per liter of air may be fair, but wearing the
18002: metered gas mask all day and all night is intolerable even if everyone can
18003: afford to pay the air bill. And the TV cameras everywhere to see if you
18004: ever take the mask off are outrageous. It's better to support the air
18005: plant with a head tax and chuck the masks.
18006:
18007: Copying all or parts of a program is as natural to a programmer as
18008: breathing, and as productive. It ought to be as free.
18009:
18010: @unnumberedsec Some Easily Rebutted Objections to GNU's Goals
18011:
18012: @quotation
18013: ``Nobody will use it if it is free, because that means they can't rely
18014: on any support.''
18015:
18016: ``You have to charge for the program to pay for providing the
18017: support.''
18018: @end quotation
18019:
18020: If people would rather pay for GNU plus service than get GNU free without
18021: service, a company to provide just service to people who have obtained GNU
18022: free ought to be profitable.
18023:
18024: We must distinguish between support in the form of real programming work
18025: and mere handholding. The former is something one cannot rely on from a
18026: software vendor. If your problem is not shared by enough people, the
18027: vendor will tell you to get lost.
18028:
18029: If your business needs to be able to rely on support, the only way is to
18030: have all the necessary sources and tools. Then you can hire any available
18031: person to fix your problem; you are not at the mercy of any individual.
18032: With Unix, the price of sources puts this out of consideration for most
18033: businesses. With GNU this will be easy. It is still possible for there to
18034: be no available competent person, but this problem cannot be blamed on
18035: distribution arrangements. GNU does not eliminate all the world's problems,
18036: only some of them.
18037:
18038: Meanwhile, the users who know nothing about computers need handholding:
18039: doing things for them which they could easily do themselves but don't know
18040: how.
18041:
18042: Such services could be provided by companies that sell just hand-holding
18043: and repair service. If it is true that users would rather spend money and
18044: get a product with service, they will also be willing to buy the service
18045: having got the product free. The service companies will compete in quality
18046: and price; users will not be tied to any particular one. Meanwhile, those
18047: of us who don't need the service should be able to use the program without
18048: paying for the service.
18049:
18050: @quotation
18051: ``You cannot reach many people without advertising,
18052: and you must charge for the program to support that.''
18053:
18054: ``It's no use advertising a program people can get free.''
18055: @end quotation
18056:
18057: There are various forms of free or very cheap publicity that can be used to
18058: inform numbers of computer users about something like GNU. But it may be
18059: true that one can reach more microcomputer users with advertising. If this
18060: is really so, a business which advertises the service of copying and
18061: mailing GNU for a fee ought to be successful enough to pay for its
18062: advertising and more. This way, only the users who benefit from the
18063: advertising pay for it.
18064:
18065: On the other hand, if many people get GNU from their friends, and such
18066: companies don't succeed, this will show that advertising was not really
18067: necessary to spread GNU. Why is it that free market advocates don't want
18068: to let the free market decide this?
18069:
18070: @quotation
18071: ``My company needs a proprietary operating system
18072: to get a competitive edge.''
18073: @end quotation
18074:
18075: GNU will remove operating system software from the realm of competition.
18076: You will not be able to get an edge in this area, but neither will your
18077: competitors be able to get an edge over you. You and they will compete in
18078: other areas, while benefitting mutually in this one. If your business is
18079: selling an operating system, you will not like GNU, but that's tough on
18080: you. If your business is something else, GNU can save you from being
18081: pushed into the expensive business of selling operating systems.
18082:
18083: I would like to see GNU development supported by gifts from many
18084: manufacturers and users, reducing the cost to each.
18085:
18086: @quotation
18087: ``Don't programmers deserve a reward for their creativity?''
18088: @end quotation
18089:
18090: If anything deserves a reward, it is social contribution. Creativity can
18091: be a social contribution, but only in so far as society is free to use the
18092: results. If programmers deserve to be rewarded for creating innovative
18093: programs, by the same token they deserve to be punished if they restrict
18094: the use of these programs.
18095:
18096: @quotation
18097: ``Shouldn't a programmer be able to ask for a reward for his creativity?''
18098: @end quotation
18099:
18100: There is nothing wrong with wanting pay for work, or seeking to maximize
18101: one's income, as long as one does not use means that are destructive. But
18102: the means customary in the field of software today are based on
18103: destruction.
18104:
18105: Extracting money from users of a program by restricting their use of it is
18106: destructive because the restrictions reduce the amount and the ways that
18107: the program can be used. This reduces the amount of wealth that humanity
18108: derives from the program. When there is a deliberate choice to restrict,
18109: the harmful consequences are deliberate destruction.
18110:
18111: The reason a good citizen does not use such destructive means to become
18112: wealthier is that, if everyone did so, we would all become poorer from the
18113: mutual destructiveness. This is Kantian ethics; or, the Golden Rule.
18114: Since I do not like the consequences that result if everyone hoards
18115: information, I am required to consider it wrong for one to do so.
18116: Specifically, the desire to be rewarded for one's creativity does not
18117: justify depriving the world in general of all or part of that creativity.
18118:
18119: @quotation
18120: ``Won't programmers starve?''
18121: @end quotation
18122:
18123: I could answer that nobody is forced to be a programmer. Most of us cannot
18124: manage to get any money for standing on the street and making faces. But
18125: we are not, as a result, condemned to spend our lives standing on the
18126: street making faces, and starving. We do something else.
18127:
18128: But that is the wrong answer because it accepts the questioner's implicit
18129: assumption: that without ownership of software, programmers cannot possibly
18130: be paid a cent. Supposedly it is all or nothing.
18131:
18132: The real reason programmers will not starve is that it will still be
18133: possible for them to get paid for programming; just not paid as much as
18134: now.
18135:
18136: Restricting copying is not the only basis for business in software. It is
18137: the most common basis because it brings in the most money. If it were
18138: prohibited, or rejected by the customer, software business would move to
18139: other bases of organization which are now used less often. There are
18140: always numerous ways to organize any kind of business.
18141:
18142: Probably programming will not be as lucrative on the new basis as it is
18143: now. But that is not an argument against the change. It is not considered
18144: an injustice that sales clerks make the salaries that they now do. If
18145: programmers made the same, that would not be an injustice either. (In
18146: practice they would still make considerably more than that.)
18147:
18148: @quotation
18149: ``Don't people have a right to control how their creativity is used?''
18150: @end quotation
18151:
18152: ``Control over the use of one's ideas'' really constitutes control over
18153: other people's lives; and it is usually used to make their lives more
18154: difficult.
18155:
18156: People who have studied the issue of intellectual property rights carefully
18157: (such as lawyers) say that there is no intrinsic right to intellectual
18158: property. The kinds of supposed intellectual property rights that the
18159: government recognizes were created by specific acts of legislation for
18160: specific purposes.
18161:
18162: For example, the patent system was established to encourage inventors to
18163: disclose the details of their inventions. Its purpose was to help society
18164: rather than to help inventors. At the time, the life span of 17 years for
18165: a patent was short compared with the rate of advance of the state of the
18166: art. Since patents are an issue only among manufacturers, for whom the
18167: cost and effort of a license agreement are small compared with setting up
18168: production, the patents often do not do much harm. They do not obstruct
18169: most individuals who use patented products.
18170:
18171: The idea of copyright did not exist in ancient times, when authors
18172: frequently copied other authors at length in works of non-fiction. This
18173: practice was useful, and is the only way many authors' works have survived
18174: even in part. The copyright system was created expressly for the purpose
18175: of encouraging authorship. In the domain for which it was
18176: invented---books, which could be copied economically only on a printing
18177: press---it did little harm, and did not obstruct most of the individuals
18178: who read the books.
18179:
18180: All intellectual property rights are just licenses granted by society
18181: because it was thought, rightly or wrongly, that society as a whole would
18182: benefit by granting them. But in any particular situation, we have to ask:
18183: are we really better off granting such license? What kind of act are we
18184: licensing a person to do?
18185:
18186: The case of programs today is very different from that of books a hundred
18187: years ago. The fact that the easiest way to copy a program is from one
18188: neighbor to another, the fact that a program has both source code and
18189: object code which are distinct, and the fact that a program is used rather
18190: than read and enjoyed, combine to create a situation in which a person who
18191: enforces a copyright is harming society as a whole both materially and
18192: spiritually; in which a person should not do so regardless of whether the
18193: law enables him to.
18194:
18195: @quotation
18196: ``Competition makes things get done better.''
18197: @end quotation
18198:
18199: The paradigm of competition is a race: by rewarding the winner, we
18200: encourage everyone to run faster. When capitalism really works this way,
18201: it does a good job; but its defenders are wrong in assuming it always works
18202: this way. If the runners forget why the reward is offered and become
18203: intent on winning, no matter how, they may find other strategies---such as,
18204: attacking other runners. If the runners get into a fist fight, they will
18205: all finish late.
18206:
18207: Proprietary and secret software is the moral equivalent of runners in a
18208: fist fight. Sad to say, the only referee we've got does not seem to
18209: object to fights; he just regulates them (``For every ten yards you run,
18210: you can fire one shot''). He really ought to break them up, and penalize
18211: runners for even trying to fight.
18212:
18213: @quotation
18214: ``Won't everyone stop programming without a monetary incentive?''
18215: @end quotation
18216:
18217: Actually, many people will program with absolutely no monetary incentive.
18218: Programming has an irresistible fascination for some people, usually the
18219: people who are best at it. There is no shortage of professional musicians
18220: who keep at it even though they have no hope of making a living that way.
18221:
18222: But really this question, though commonly asked, is not appropriate to the
18223: situation. Pay for programmers will not disappear, only become less. So
18224: the right question is, will anyone program with a reduced monetary
18225: incentive? My experience shows that they will.
18226:
18227: For more than ten years, many of the world's best programmers worked at the
18228: Artificial Intelligence Lab for far less money than they could have had
18229: anywhere else. They got many kinds of non-monetary rewards: fame and
18230: appreciation, for example. And creativity is also fun, a reward in itself.
18231:
18232: Then most of them left when offered a chance to do the same interesting
18233: work for a lot of money.
18234:
18235: What the facts show is that people will program for reasons other than
18236: riches; but if given a chance to make a lot of money as well, they will
18237: come to expect and demand it. Low-paying organizations do poorly in
18238: competition with high-paying ones, but they do not have to do badly if the
18239: high-paying ones are banned.
18240:
18241: @quotation
18242: ``We need the programmers desperately. If they demand that we
18243: stop helping our neighbors, we have to obey.''
18244: @end quotation
18245:
18246: You're never so desperate that you have to obey this sort of demand.
18247: Remember: millions for defense, but not a cent for tribute!
18248:
18249: @quotation
18250: ``Programmers need to make a living somehow.''
18251: @end quotation
18252:
18253: In the short run, this is true. However, there are plenty of ways that
18254: programmers could make a living without selling the right to use a program.
18255: This way is customary now because it brings programmers and businessmen the
18256: most money, not because it is the only way to make a living. It is easy to
18257: find other ways if you want to find them. Here are a number of examples.
18258:
18259: A manufacturer introducing a new computer will pay for the porting of
18260: operating systems onto the new hardware.
18261:
18262: The sale of teaching, hand-holding and maintenance services could also
18263: employ programmers.
18264:
18265: People with new ideas could distribute programs as freeware, asking for
18266: donations from satisfied users, or selling hand-holding services. I have
18267: met people who are already working this way successfully.
18268:
18269: Users with related needs can form users' groups, and pay dues. A group
18270: would contract with programming companies to write programs that the
18271: group's members would like to use.
18272:
18273: All sorts of development can be funded with a Software Tax:
18274:
18275: @quotation
18276: Suppose everyone who buys a computer has to pay x percent of
18277: the price as a software tax. The government gives this to
18278: an agency like the NSF to spend on software development.
18279:
18280: But if the computer buyer makes a donation to software development
18281: himself, he can take a credit against the tax. He can donate to
18282: the project of his own choosing---often, chosen because he hopes to
18283: use the results when it is done. He can take a credit for any amount
18284: of donation up to the total tax he had to pay.
18285:
18286: The total tax rate could be decided by a vote of the payers of
18287: the tax, weighted according to the amount they will be taxed on.
18288:
18289: The consequences:
18290:
18291: @itemize @bullet
18292: @item
18293: The computer-using community supports software development.
18294: @item
18295: This community decides what level of support is needed.
18296: @item
18297: Users who care which projects their share is spent on
18298: can choose this for themselves.
18299: @end itemize
18300: @end quotation
18301:
18302: In the long run, making programs free is a step toward the post-scarcity
18303: world, where nobody will have to work very hard just to make a living.
18304: People will be free to devote themselves to activities that are fun, such
18305: as programming, after spending the necessary ten hours a week on required
18306: tasks such as legislation, family counseling, robot repair and asteroid
18307: prospecting. There will be no need to be able to make a living from
18308: programming.
18309:
18310: We have already greatly reduced the amount of work that the whole society
18311: must do for its actual productivity, but only a little of this has
18312: translated itself into leisure for workers because much nonproductive
18313: activity is required to accompany productive activity. The main causes of
18314: this are bureaucracy and isometric struggles against competition. Free
18315: software will greatly reduce these drains in the area of software
18316: production. We must do this, in order for technical gains in productivity
18317: to translate into less work for us.
18318:
18319: @node Glossary, Key Index, Intro, Top
18320: @unnumbered Glossary
18321:
18322: @table @asis
18323: @need 150
18324: @item Abbrev
18325: An abbrev is a text string which expands into a different text string
18326: when present in the buffer. For example, you might define a short
18327: word as an abbrev for a long phrase that you want to insert
18328: frequently. @xref{Abbrevs}.
18329:
18330: @need 150
18331: @item Aborting
18332: Aborting means getting out of a recursive edit (q.v.@:). The
18333: commands @kbd{C-]} and @kbd{M-x top-level} are used for this.
18334: @xref{Quitting}.
18335:
18336: @need 150
18337: @item Auto Fill mode
18338: Auto Fill mode is a minor mode in which text that you insert is
18339: automatically broken into lines of fixed width. @xref{Filling}.
18340:
18341: @need 150
18342: @item Auto Saving
18343: Auto saving is when Emacs automatically stores the contents of an
18344: Emacs buffer in a specially-named file so that the information will
18345: not be lost if the buffer is lost due to a system error or user error.
18346: @xref{Auto Save}.
18347:
18348: @need 150
18349: @item Backup File
18350: A backup file records the contents that a file had before the current
18351: editing session. Emacs makes backup files automatically to help you
18352: track down or cancel changes you later regret making. @xref{Backup}.
18353:
18354: @need 150
18355: @item Balance Parentheses
18356: Emacs can balance parentheses manually or automatically. Manual
18357: balancing is done by the commands to move over balanced expressions
18358: (@pxref{Lists}). Automatic balancing is done by blinking the
18359: parenthesis that matches one just inserted (@pxref{Matching,,Matching
18360: Parens}).
18361:
18362: @need 150
18363: @item Bind
18364: To bind a key is to change its binding (q.v.@:). @xref{Rebinding}.
18365:
18366: @need 150
18367: @item Binding
18368: A key gets its meaning in Emacs by having a binding which is a
18369: command (q.v.@:), a Lisp function that is run when the key is typed.
18370: @xref{Commands,Binding}. Customization often involves rebinding a
18371: character to a different command function. The bindings of all keys
18372: are recorded in the keymaps (q.v.@:). @xref{Keymaps}.
18373:
18374: @need 150
18375: @item Blank Lines
18376: Blank lines are lines that contain only whitespace. Emacs has several
18377: commands for operating on the blank lines in the buffer.
18378:
18379: @need 150
18380: @item Buffer
18381: The buffer is the basic editing unit; one buffer corresponds to one
18382: piece of text being edited. You can have several buffers, but at any
18383: time you are editing only one, the `selected' buffer, though several
18384: can be visible when you are using multiple windows. @xref{Buffers}.
18385:
18386: @need 150
18387: @item Buffer Selection History
18388: Emacs keeps a buffer selection history which records how recently each
18389: Emacs buffer has been selected. This is used for choosing a buffer to
18390: select. @xref{Buffers}.
18391:
18392: @need 150
18393: @item C-
18394: @samp{C} in the name of a character is an abbreviation for Control.
18395: @xref{Characters,C-}.
18396:
18397: @need 150
18398: @item C-M-
18399: @samp{C-M-} in the name of a character is an abbreviation for
18400: Control-Meta. @xref{Characters,C-M-}.
18401:
18402: @need 150
18403: @item Case Conversion
18404: Case conversion means changing text from upper case to lower case or
18405: vice versa. @xref{Case}, for the commands for case conversion.
18406:
18407: @need 150
18408: @item Characters
18409: Characters form the contents of an Emacs buffer; also, Emacs commands
18410: are invoked by keys (q.v.@:), which are sequences of one or more
18411: characters. @xref{Characters}.
18412:
18413: @need 150
18414: @item Command
18415: A command is a Lisp function specially defined to be able to serve as
18416: a key binding in Emacs. When you type a key (q.v.@:), its binding
18417: (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find the
18418: command to run. @xref{Commands}.
18419:
18420: @need 150
18421: @item Command Name
18422: A command name is the name of a Lisp symbol which is a command
18423: (@pxref{Commands}). You can invoke any command by its name using
18424: @kbd{M-x} (@pxref{M-x}).
18425:
18426: @need 150
18427: @item Comments
18428: A comment is text in a program which is intended only for humans
18429: reading the program, and is marked specially so that it will be
18430: ignored when the program is loaded or compiled. Emacs offers special
18431: commands for creating, aligning and killing comments.
18432: @xref{Comments}.
18433:
18434: @need 150
18435: @item Compilation
18436: Compilation is the process of creating an executable program from
18437: source code. Emacs has commands for compiling files of Emacs Lisp
18438: code (@pxref{Lisp Libraries}) and programs in C and other languages
18439: (@pxref{Compilation}).
18440:
18441: @need 150
18442: @item Complete Key
18443: A complete key is a character or sequence of characters which, when typed
18444: by the user, fully specifies one action to be performed by Emacs. For
18445: example, @kbd{X} and @kbd{Control-f} and @kbd{Control-x m} are keys. Keys
18446: derive their meanings from being bound (q.v.@:) to commands (q.v.@:).
18447: Thus, @kbd{X} is conventionally bound to a command to insert @samp{X} in
18448: the buffer; @kbd{C-x m} is conventionally bound to a command to begin
18449: composing a mail message. @xref{Keys}.
18450:
18451: @need 150
18452: @item Completion
18453: Completion is what Emacs does when it automatically fills out an
18454: abbreviation for a name into the entire name. Completion is done for
18455: minibuffer (q.v.@:) arguments when the set of possible valid inputs
18456: is known; for example, on command names, buffer names, and
18457: file names. Completion occurs when @key{TAB}, @key{SPC} or @key{RET}
18458: is typed. @xref{Completion}.@refill
18459:
18460: @need 150
18461: @item Continuation Line
18462: When a line of text is longer than the width of the screen, it
18463: takes up more than one screen line when displayed. We say that the
18464: text line is continued, and all screen lines used for it after the
18465: first are called continuation lines. @xref{Basic,Continuation,Basic
18466: Editing}.
18467:
18468: @need 150
18469: @item Control-Character
18470: @sc{ascii} characters with octal codes 0 through 037, and also code 0177,
18471: do not have graphic images assigned to them. These are the control
18472: characters. Any control character can be typed by holding down the
18473: @key{CTRL} key and typing some other character; some have special keys
18474: on the keyboard. @key{RET}, @key{TAB}, @key{ESC}, @key{LFD} and
18475: @key{DEL} are all control characters. @xref{Characters}.@refill
18476:
18477: @need 150
18478: @item Copyleft
18479: A copyleft is a notice giving the public legal permission to redistribute
18480: a program or other work of art. Copylefts are used by leftists to enrich
18481: the public just as copyrights are used by rightists to gain power over
18482: the public.
18483:
18484: @need 150
18485: @item Current Buffer
18486: The current buffer in Emacs is the Emacs buffer on which most editing
18487: commands operate. You can select any Emacs buffer as the current one.
18488: @xref{Buffers}.
18489:
18490: @need 150
18491: @item Current Line
18492: The line point is on (@pxref{Point}).
18493:
18494: @need 150
18495: @item Current Paragraph
18496: The paragraph that point is in. If point is between paragraphs, the
18497: current paragraph is the one that follows point. @xref{Paragraphs}.
18498:
18499: @need 150
18500: @item Current Defun
18501: The defun (q.v.@:) that point is in. If point is between defuns, the
18502: current defun is the one that follows point. @xref{Defuns}.
18503:
18504: @need 150
18505: @item Cursor
18506: The cursor is the rectangle on the screen which indicates the position
18507: called point (q.v.@:) at which insertion and deletion takes place.
18508: The cursor is on or under the character that follows point. Often
18509: people speak of `the cursor' when, strictly speaking, they mean
18510: `point'. @xref{Basic,Cursor,Basic Editing}.
18511:
18512: @need 150
18513: @item Customization
18514: Customization is making minor changes in the way Emacs works. It is
18515: often done by setting variables (@pxref{Variables}) or by rebinding
18516: keys (@pxref{Keymaps}).
18517:
18518: @need 150
18519: @item Default Argument
18520: The default for an argument is the value that will be assumed if you
18521: do not specify one. When the minibuffer is used to read an argument,
18522: the default argument is used if you just type @key{RET}.
18523: @xref{Minibuffer}.
18524:
18525: @need 150
18526: @item Default Directory
18527: When you specify a file name that does not start with @samp{/} or @samp{~},
18528: it is interpreted relative to the current buffer's default directory.
18529: @xref{Minibuffer File,Default Directory}.
18530:
18531: @need 150
18532: @item Defun
18533: A defun is a list at the top level of parenthesis or bracket structure
18534: in a program. It is so named because most such lists in Lisp programs
18535: are calls to the Lisp function @code{defun}. @xref{Defuns}.
18536:
18537: @need 150
18538: @item @key{DEL}
18539: @key{DEL} is a character that runs the command to delete one character of
18540: text. @xref{Basic,DEL,Basic Editing}.
18541:
18542: @need 150
18543: @item Deletion
18544: Deletion means erasing text without saving it. Emacs deletes text
18545: only when it is expected not to be worth saving (all whitespace, or
18546: only one character). The alternative is killing (q.v.@:).
18547: @xref{Killing,Deletion}.
18548:
18549: @need 150
18550: @item Deletion of Files
18551: Deleting a file means erasing it from the file system.
18552: @xref{Misc File Ops}.
18553:
18554: @need 150
18555: @item Deletion of Messages
18556: Deleting a message means flagging it to be eliminated from your mail
18557: file. This can be undone by undeletion until the mail file is expunged.
18558: @xref{Rmail Deletion}.
18559:
18560: @need 150
18561: @item Deletion of Windows
18562: Deleting a window means eliminating it from the screen. Other windows
18563: expand to use up the space. The deleted window can never come back,
18564: but no actual text is thereby lost. @xref{Windows}.
18565:
18566: @need 150
18567: @item Directory
18568: Files in the Unix file system are grouped into file directories.
18569: @xref{ListDir,,Directories}.
18570:
18571: @need 150
18572: @item Dired
18573: Dired is the Emacs facility that displays the contents of a file
18574: directory and allows you to ``edit the directory'', performing
18575: operations on the files in the directory. @xref{Dired}.
18576:
18577: @need 150
18578: @item Disabled Command
18579: A disabled command is one that you may not run without special
18580: confirmation. The usual reason for disabling a command is that it is
18581: confusing for beginning users. @xref{Disabling}.
18582:
18583: @need 150
18584: @item Dribble File
18585: A file into which Emacs writes all the characters that the user types
18586: on the keyboard. Dribble files are used to make a record for
18587: debugging Emacs bugs. Emacs does not make a dribble file unless you
18588: tell it to. @xref{Bugs}.
18589:
18590: @need 150
18591: @item Echo Area
18592: The echo area is the bottom line of the screen, used for echoing the
18593: arguments to commands, for asking questions, and printing brief
18594: messages (including error messages). @xref{Echo Area}.
18595:
18596: @need 150
18597: @item Echoing
18598: Echoing is acknowledging the receipt of commands by displaying them
18599: (in the echo area). Emacs never echoes single-character keys; longer
18600: keys echo only if you pause while typing them.
18601:
18602: @need 150
18603: @item Error
18604: An error occurs when an Emacs command cannot execute in the current
18605: circumstances. When an error occurs, execution of the command stops
18606: (unless the command has been programmed to do otherwise) and Emacs
18607: reports the error by printing an error message (q.v.). Type-ahead
18608: is discarded. Then Emacs is ready to read another editing command.
18609:
18610: @need 150
18611: @item Error Messages
18612: Error messages are single lines of output printed by Emacs when the
18613: user asks for something impossible to do (such as, killing text
18614: forward when point is at the end of the buffer). They appear in the
18615: echo area, accompanied by a beep.
18616:
18617: @need 150
18618: @item @key{ESC}
18619: @key{ESC} is a character, used to end incremental searches and as a
18620: prefix for typing Meta characters on keyboards lacking a @key{META}
18621: key. Unlike the @key{META} key (which, like the @key{SHIFT} key, is held
18622: down while another character is typed), the @key{ESC} key is pressed
18623: once and applies to the next character typed.
18624:
18625: @need 150
18626: @item Fill Prefix
18627: The fill prefix is a string that should be expected at the beginning
18628: of each line when filling is done. It is not regarded as part of the
18629: text to be filled. @xref{Filling}.
18630:
18631: @need 150
18632: @item Filling
18633: Filling text means moving text from line to line so that all the lines
18634: are approximately the same length. @xref{Filling}.
18635:
18636: @need 150
18637: @item Global
18638: Global means `independent of the current environment; in effect
18639: throughout Emacs'. It is the opposite of local (q.v.@:). Particular
18640: examples of the use of `global' appear below.
18641:
18642: @need 150
18643: @item Global Abbrev
18644: A global definition of an abbrev (q.v.@:) is effective in all major
18645: modes that do not have local (q.v.@:) definitions for the same abbrev.
18646: @xref{Abbrevs}.
18647:
18648: @need 150
18649: @item Global Keymap
18650: The global keymap (q.v.@:) contains key bindings that are in effect
18651: except when overridden by local key bindings in a major mode's local
18652: keymap (q.v.@:). @xref{Keymaps}.
18653:
18654: @need 150
18655: @item Global Substitution
18656: Global substitution means replacing each occurrence of one string by
18657: another string through a large amount of text. @xref{Replace}.
18658:
18659: @need 150
18660: @item Global Variable
18661: The global value of a variable (q.v.@:) takes effect in all buffers
18662: that do not have their own local (q.v.@:) values for the variable.
18663: @xref{Variables}.
18664:
18665: @need 150
18666: @item Graphic Character
18667: Graphic characters are those assigned pictorial images rather than
18668: just names. All the non-Meta (q.v.@:) characters except for the
18669: Control (q.v.@:) characters are graphic characters. These include
18670: letters, digits, punctuation, and spaces; they do not include
18671: @key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts
18672: that character (in ordinary editing modes). @xref{Basic,,Basic Editing}.
18673:
18674: @need 150
18675: @item Grinding
18676: Grinding means adjusting the indentation in a program to fit the
18677: nesting structure. @xref{Indentation,Grinding}.
18678:
18679: @need 150
18680: @item Hardcopy
18681: Hardcopy means printed output. Emacs has commands for making printed
18682: listings of text in Emacs buffers. @xref{Hardcopy}.
18683:
18684: @need 150
18685: @item @key{HELP}
18686: You can type @key{HELP} at any time to ask what options you have, or
18687: to ask what any command does. @key{HELP} is really @kbd{Control-h}.
18688: @xref{Help}.
18689:
18690: @need 150
18691: @item Inbox
18692: An inbox is a file in which mail is delivered by the operating system.
18693: Rmail transfers mail from inboxes to mail files (q.v.) in which the
18694: mail is then stored permanently or until explicitly deleted.
18695: @xref{Rmail Inbox}.
18696:
18697: @need 150
18698: @item Indentation
18699: Indentation means blank space at the beginning of a line. Most
18700: programming languages have conventions for using indentation to
18701: illuminate the structure of the program, and Emacs has special
18702: features to help you set up the correct indentation.
18703: @xref{Indentation}.
18704:
18705: @need 150
18706: @item Insertion
18707: Insertion means copying text into the buffer, either from the keyboard
18708: or from some other place in Emacs.
18709:
18710: @need 150
18711: @item Justification
18712: Justification means adding extra spaces to lines of text to make them
18713: come exactly to a specified width. @xref{Filling,Justification}.
18714:
18715: @need 150
18716: @item Keyboard Macros
18717: Keyboard macros are a way of defining new Emacs commands from
18718: sequences of existing ones, with no need to write a Lisp program.
18719: @xref{Keyboard Macros}.
18720:
18721: @need 150
18722: @item Key
18723: A key is a sequence of characters that, when input to Emacs, specify
18724: or begin to specify a single action for Emacs to perform. That is,
18725: the sequence is not more than a single unit. If the key is enough to
18726: specify one action, it is a complete key (q.v.); if it is less than
18727: enough, it is a prefix key (q.v.). @xref{Keys}.
18728:
18729: @need 150
18730: @item Keymap
18731: The keymap is the data structure that records the bindings (q.v.@:) of
18732: keys to the commands that they run. For example, the keymap binds the
18733: character @kbd{C-n} to the command function @code{next-line}.
18734: @xref{Keymaps}.
18735:
18736: @need 150
18737: @item Kill Ring
18738: The kill ring is where all text you have killed recently is saved.
18739: You can reinsert any of the killed text still in the ring; this is
18740: called yanking (q.v.@:). @xref{Yanking}.
18741:
18742: @need 150
18743: @item Killing
18744: Killing means erasing text and saving it on the kill ring so it can be
18745: yanked (q.v.@:) later. Some other systems call this ``cutting''.
18746: Most Emacs commands to erase text do killing, as opposed to deletion
18747: (q.v.@:). @xref{Killing}.
18748:
18749: @need 150
18750: @item Killing Jobs
18751: Killing a job (such as, an invocation of Emacs) means making it cease
18752: to exist. Any data within it, if not saved in a file, is lost.
18753: @xref{Exiting}.
18754:
18755: @need 150
18756: @item List
18757: A list is, approximately, a text string beginning with an open
18758: parenthesis and ending with the matching close parenthesis. In C mode
18759: and other non-Lisp modes, groupings surrounded by other kinds of matched
18760: delimiters appropriate to the language, such as braces, are also
18761: considered lists. Emacs has special commands for many operations on
18762: lists. @xref{Lists}.
18763:
18764: @need 150
18765: @item Local
18766: Local means `in effect only in a particular context'; the relevant
18767: kind of context is a particular function execution, a particular
18768: buffer, or a particular major mode. It is the opposite of `global'
18769: (q.v.@:). Specific uses of `local' in Emacs terminology appear below.
18770:
18771: @need 150
18772: @item Local Abbrev
18773: A local abbrev definition is effective only if a particular major mode
18774: is selected. In that major mode, it overrides any global definition
18775: for the same abbrev. @xref{Abbrevs}.
18776:
18777: @need 150
18778: @item Local Keymap
18779: A local keymap is used in a particular major mode; the key bindings
18780: (q.v.@:) in the current local keymap override global bindings of the
18781: same keys. @xref{Keymaps}.
18782:
18783: @need 150
18784: @item Local Variable
18785: A local value of a variable (q.v.@:) applies to only one buffer.
18786: @xref{Locals}.
18787:
18788: @need 150
18789: @item M-
18790: @kbd{M-} in the name of a character is an abbreviation for @key{META},
18791: one of the modifier keys that can accompany any character.
18792: @xref{Characters}.
18793:
18794: @need 150
18795: @item M-C-
18796: @samp{M-C-} in the name of a character is an abbreviation for
18797: Control-Meta; it means the same thing as @samp{C-M-}. If your
18798: terminal lacks a real @key{META} key, you type a Control-Meta character by
18799: typing @key{ESC} and then typing the corresponding Control character.
18800: @xref{Characters,C-M-}.
18801:
18802: @need 150
18803: @item M-x
18804: @kbd{M-x} is the key which is used to call an Emacs command by name.
18805: This is how commands that are not bound to keys are called.
18806: @xref{M-x}.
18807:
18808: @need 150
18809: @item Mail
18810: Mail means messages sent from one user to another through the computer
18811: system, to be read at the recipient's convenience. Emacs has commands for
18812: composing and sending mail, and for reading and editing the mail you have
18813: received. @xref{Sending Mail}. @xref{Rmail}, for how to read mail.
18814:
18815: @need 150
18816: @item Mail File
18817: A mail file is a file which is edited using Rmail and in which Rmail
18818: stores mail. @xref{Rmail}.
18819:
18820: @need 150
18821: @item Major Mode
18822: The major modes are a mutually exclusive set of options each of which
18823: configures Emacs for editing a certain sort of text. Ideally, each
18824: programming language has its own major mode. @xref{Major Modes}.
18825:
18826: @need 150
18827: @item Mark
18828: The mark points to a position in the text. It specifies one end of
18829: the region (q.v.@:), point being the other end. Many commands operate
18830: on all the text from point to the mark. @xref{Mark}.
18831:
18832: @need 150
18833: @item Mark Ring
18834: The mark ring is used to hold several recent previous locations of the
18835: mark, just in case you want to move back to them. @xref{Mark Ring}.
18836:
18837: @need 150
18838: @item Message
18839: See `mail'.
18840:
18841: @need 150
18842: @item Meta
18843: Meta is the name of a modifier bit which a command character may have.
18844: It is present in a character if the character is typed with the
18845: @key{META} key held down. Such characters are given names that start
18846: with @kbd{Meta-}. For example, @kbd{Meta-<} is typed by holding down
18847: @key{META} and at the same time typing @kbd{<} (which itself is done,
18848: on most terminals, by holding down @key{SHIFT} and typing @kbd{,}).
18849: @xref{Characters,Meta}.
18850:
18851: @need 150
18852: @item Meta Character
18853: A Meta character is one whose character code includes the Meta bit.
18854:
18855: @need 150
18856: @item Minibuffer
18857: The minibuffer is the window that appears when necessary inside the
18858: echo area (q.v.@:), used for reading arguments to commands.
18859: @xref{Minibuffer}.
18860:
18861: @need 150
18862: @item Minor Mode
18863: A minor mode is an optional feature of Emacs which can be switched on
18864: or off independently of all other features. Each minor mode has a
18865: command to turn it on or off. @xref{Minor Modes}.
18866:
18867: @need 150
18868: @item Mode Line
18869: The mode line is the line at the bottom of each text window (q.v.@:),
18870: which gives status information on the buffer displayed in that window.
18871: @xref{Mode Line}.
18872:
18873: @need 150
18874: @item Modified Buffer
18875: A buffer (q.v.@:) is modified if its text has been changed since the
18876: last time the buffer was saved (or since when it was created, if it
18877: has never been saved). @xref{Saving}.
18878:
18879: @need 150
18880: @item Moving Text
18881: Moving text means erasing it from one place and inserting it in
18882: another. This is done by killing (q.v.@:) and then yanking (q.v.@:).
18883: @xref{Killing}.
18884:
18885: @need 150
18886: @item Named Mark
18887: A named mark is a register (q.v.@:) in its role of recording a
18888: location in text so that you can move point to that location.
18889: @xref{Registers}.
18890:
18891: @need 150
18892: @item Narrowing
18893: Narrowing means creating a restriction (q.v.@:) that limits editing in
18894: the current buffer to only a part of the text in the buffer. Text
18895: outside that part is inaccessible to the user until the boundaries are
18896: widened again, but it is still there, and saving the file saves it
18897: all. @xref{Narrowing}.
18898:
18899: @need 150
18900: @item Newline
18901: @key{LFD} characters in the buffer terminate lines of text and are
18902: called newlines. @xref{Characters,Newline}.
18903:
18904: @need 150
18905: @item Numeric Argument
18906: A numeric argument is a number, specified before a command, to change
18907: the effect of the command. Often the numeric argument serves as a
18908: repeat count. @xref{Arguments}.
18909:
18910: @need 150
18911: @item Option
18912: An option is a variable (q.v.@:) that exists so that you can customize
18913: Emacs by giving it a new value. @xref{Variables}.
18914:
18915: @need 150
18916: @item Overwrite Mode
18917: Overwrite mode is a minor mode. When it is enabled, ordinary text
18918: characters replace the existing text after point rather than pushing
18919: it to the right. @xref{Minor Modes}.
18920:
18921: @need 150
18922: @item Page
18923: A page is a unit of text, delimited by formfeed characters (@sc{ascii}
18924: Control-L, code 014) coming at the beginning of a line. Some Emacs
18925: commands are provided for moving over and operating on pages.
18926: @xref{Pages}.
18927:
18928: @need 150
18929: @item Paragraphs
18930: Paragraphs are the medium-size unit of English text. There are
18931: special Emacs commands for moving over and operating on paragraphs.
18932: @xref{Paragraphs}.
18933:
18934: @need 150
18935: @item Parsing
18936: We say that Emacs parses words or expressions in the text being
18937: edited. Really, all it knows how to do is find the other end of a
18938: word or expression. @xref{Syntax}.
18939:
18940: @need 150
18941: @item Point
18942: Point is the place in the buffer at which insertion and deletion
18943: occur. Point is considered to be between two characters, not at one
18944: character. The terminal's cursor (q.v.@:) indicates the location of
18945: point. @xref{Basic,Point}.
18946:
18947: @need 150
18948: @item Prefix Key
18949: A prefix key is a key (q.v.@:) whose sole function is to introduce a
18950: set of multi-character keys. @kbd{Control-x} is an example of prefix
18951: key; thus, any two-character sequence starting with @kbd{C-x} is also
18952: a legitimate key. @xref{Keys}.
18953:
18954: @need 150
18955: @item Primary Mail File
18956: Your primary mail file is the file named @samp{RMAIL} in your home
18957: directory, where all mail that you receive is stored by Rmail unless you
18958: make arrangements to do otherwise. @xref{Rmail}.
18959:
18960: @need 150
18961: @item Prompt
18962: A prompt is text printed to ask the user for input. Printing a prompt
18963: is called prompting. Emacs prompts always appear in the echo area
18964: (q.v.@:). One kind of prompting happens when the minibuffer is used
18965: to read an argument (@pxref{Minibuffer}); the echoing which happens
18966: when you pause in the middle of typing a multicharacter key is also a
18967: kind of prompting (@pxref{Echo Area}).
18968:
18969: @need 150
18970: @item Quitting
18971: Quitting means cancelling a partially typed command or a running
18972: command, using @kbd{C-g}. @xref{Quitting}.
18973:
18974: @need 150
18975: @item Quoting
18976: Quoting means depriving a character of its usual special significance.
18977: In Emacs this is usually done with @kbd{Control-q}. What constitutes special
18978: significance depends on the context and on convention. For example,
18979: an ``ordinary'' character as an Emacs command inserts itself; so in
18980: this context, a special character is any character that does not
18981: normally insert itself (such as @key{DEL}, for example), and quoting
18982: it makes it insert itself as if it were not special. Not all contexts
18983: allow quoting. @xref{Basic,Quoting,Basic Editing}.
18984:
18985: @need 150
18986: @item Read-only Buffer
18987: A read-only buffer is one whose text you are not allowed to change.
18988: Normally Emacs makes buffers read-only when they contain text which
18989: has a special significance to Emacs; for example, Dired buffers.
18990: Visiting a file that is write protected also makes a read-only buffer.
18991: @xref{Buffers}.
18992:
18993: @need 150
18994: @item Recursive Editing Level
18995: A recursive editing level is a state in which part of the execution of
18996: a command involves asking the user to edit some text. This text may
18997: or may not be the same as the text to which the command was applied.
18998: The mode line indicates recursive editing levels with square brackets
18999: (@samp{[} and @samp{]}). @xref{Recursive Edit}.
19000:
19001: @need 150
19002: @item Redisplay
19003: Redisplay is the process of correcting the image on the screen to
19004: correspond to changes that have been made in the text being edited.
19005: @xref{Screen,Redisplay}.
19006:
19007: @need 150
19008: @item Regexp
19009: See `regular expression'.
19010:
19011: @need 150
19012: @item Region
19013: The region is the text between point (q.v.@:) and the mark (q.v.@:).
19014: Many commands operate on the text of the region. @xref{Mark,Region}.
19015:
19016: @need 150
19017: @item Registers
19018: Registers are named slots in which text or buffer positions or
19019: rectangles can be saved for later use. @xref{Registers}.
19020:
19021: @need 150
19022: @item Regular Expression
19023: A regular expression is a pattern that can match various text strings;
19024: for example, @samp{l[0-9]+} matches @samp{l} followed by one or more
19025: digits. @xref{Regexps}.
19026:
19027: @need 150
19028: @item Replacement
19029: See `global substitution'.
19030:
19031: @need 150
19032: @item Restriction
19033: A buffer's restriction is the amount of text, at the beginning or the
19034: end of the buffer, that is temporarily invisible and inaccessible.
19035: Giving a buffer a nonzero amount of restriction is called narrowing
19036: (q.v.). @xref{Narrowing}.
19037:
19038: @need 150
19039: @item @key{RET}
19040: @key{RET} is a character that in Emacs runs the command to insert a
19041: newline into the text. It is also used to terminate most arguments
19042: read in the minibuffer (q.v.@:). @xref{Characters,Return}.
19043:
19044: @need 150
19045: @item Saving
19046: Saving a buffer means copying its text into the file that was visited
19047: (q.v.@:) in that buffer. This is the way text in files actually gets
19048: changed by your Emacs editing. @xref{Saving}.
19049:
19050: @need 150
19051: @item Scrolling
19052: Scrolling means shifting the text in the Emacs window so as to see a
19053: different part of the buffer. @xref{Display,Scrolling}.
19054:
19055: @need 150
19056: @item Searching
19057: Searching means moving point to the next occurrence of a specified
19058: string. @xref{Search}.
19059:
19060: @need 150
19061: @item Selecting
19062: Selecting a buffer means making it the current (q.v.@:) buffer.
19063: @xref{Buffers,Selecting}.
19064:
19065: @need 150
19066: @item Self-documentation
19067: Self-documentation is the feature of Emacs which can tell you what any
19068: command does, or give you a list of all commands related to a topic
19069: you specify. You ask for self-documentation with the help character,
19070: @kbd{C-h}. @xref{Help}.
19071:
19072: @need 150
19073: @item Sentences
19074: Emacs has commands for moving by or killing by sentences.
19075: @xref{Sentences}.
19076:
19077: @need 150
19078: @item Sexp
19079: A sexp (short for `s-expression') is the basic syntactic unit of Lisp
19080: in its textual form: either a list, or Lisp atom. Many Emacs commands
19081: operate on sexps. The term `sexp' is generalized to languages other
19082: than Lisp, to mean a syntactically recognizable expression.
19083: @xref{Lists,Sexps}.
19084:
19085: @need 150
19086: @item Simultaneous Editing
19087: Simultaneous editing means two users modifying the same file at once.
19088: Simultaneous editing if not detected can cause one user to lose his
19089: work. Emacs detects all cases of simultaneous editing and warns the
19090: user to investigate them. @xref{Interlocking,,Simultaneous Editing}.
19091:
19092: @need 150
19093: @item String
19094: A string is a kind of Lisp data object which contains a sequence of
19095: characters. Many Emacs variables are intended to have strings as
19096: values. The Lisp syntax for a string consists of the characters in
19097: the string with a @samp{"} before and another @samp{"} after. A
19098: @samp{"} that is part of the string must be written as @samp{\"} and a
19099: @samp{\} that is part of the string must be written as @samp{\\}. All
19100: other characters, including newline, can be included just by writing
19101: them inside the string; however, escape sequences as in C, such as
19102: @samp{\n} for newline or @samp{\241} using an octal character code,
19103: are allowed as well.
19104:
19105: @need 150
19106: @item String Substitution
19107: See `global substitution'.
19108:
19109: @need 150
19110: @item Syntax Table
19111: The syntax table tells Emacs which characters are part of a word,
19112: which characters balance each other like parentheses, etc.
19113: @xref{Syntax}.
19114:
19115: @need 150
19116: @item Tag Table
19117: A tag table is a file that serves as an index to the function
19118: definitions in one or more other files. @xref{Tags}.
19119:
19120: @need 150
19121: @item Termscript File
19122: A termscript file contains a record of all characters sent by Emacs to
19123: the terminal. It is used for tracking down bugs in Emacs redisplay.
19124: Emacs does not make a termscript file unless you tell it to.
19125: @xref{Bugs}.
19126:
19127: @need 150
19128: @item Text
19129: Two meanings (@pxref{Text}):
19130:
19131: @need 150
19132: @itemize @bullet
19133: @need 150
19134: @item
19135: Data consisting of a sequence of characters, as opposed to binary
19136: numbers, images, graphics commands, executable programs, and the like.
19137: The contents of an Emacs buffer are always text in this sense.
19138: @need 150
19139: @item
19140: Data consisting of written human language, as opposed to programs,
19141: or following the stylistic conventions of human language.
19142: @end itemize
19143:
19144: @need 150
19145: @item Top Level
19146: Top level is the normal state of Emacs, in which you are editing the
19147: text of the file you have visited. You are at top level whenever you
19148: are not in a recursive editing level (q.v.@:) or the minibuffer
19149: (q.v.@:), and not in the middle of a command. You can get back to top
19150: level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}.
19151:
19152: @need 150
19153: @item Transposition
19154: Transposing two units of text means putting each one into the place
19155: formerly occupied by the other. There are Emacs commands to transpose
19156: two adjacent characters, words, sexps (q.v.@:) or lines
19157: (@pxref{Transpose}).
19158:
19159: @need 150
19160: @item Truncation
19161: Truncating text lines in the display means leaving out any text on a
19162: line that does not fit within the right margin of the window
19163: displaying it. See also `continuation line'.
19164: @xref{Basic,Truncation,Basic Editing}.
19165:
19166: @need 150
19167: @item Undoing
19168: Undoing means making your previous editing go in reverse, bringing
19169: back the text that existed earlier in the editing session.
19170: @xref{Undo}.
19171:
19172: @need 150
19173: @item Variable
19174: A variable is an object in Lisp that can store an arbitrary value.
19175: Emacs uses some variables for internal purposes, and has others (known
19176: as `options' (q.v.@:)) just so that you can set their values to
19177: control the behavior of Emacs. The variables used in Emacs that you
19178: are likely to be interested in are listed in the Variables Index in
19179: this manual. @xref{Variables}, for information on variables.
19180:
19181: @need 150
19182: @item Visiting
19183: Visiting a file means loading its contents into a buffer (q.v.@:)
19184: where they can be edited. @xref{Visiting}.
19185:
19186: @need 150
19187: @item Whitespace
19188: Whitespace is any run of consecutive formatting characters (space,
19189: tab, newline, and backspace).
19190:
19191: @need 150
19192: @item Widening
19193: Widening is removing any restriction (q.v.@:) on the current buffer;
19194: it is the opposite of narrowing (q.v.@:). @xref{Narrowing}.
19195:
19196: @need 150
19197: @item Window
19198: Emacs divides the screen into one or more windows, each of which can
19199: display the contents of one buffer (q.v.@:) at any time.
19200: @xref{Screen}, for basic information on how Emacs uses the screen.
19201: @xref{Windows}, for commands to control the use of windows.
19202:
19203: @need 150
19204: @item Word Abbrev
19205: Synonymous with `abbrev'.
19206:
19207: @need 150
19208: @item Word Search
19209: Word search is searching for a sequence of words, considering the
19210: punctuation between them as insignificant. @xref{Word Search}.
19211:
19212: @need 150
19213: @item Yanking
19214: Yanking means reinserting text previously killed. It can be used to
19215: undo a mistaken kill, or for copying or moving text. Some other
19216: systems call this ``pasting''. @xref{Yanking}.
19217: @end table
19218:
19219: @node Key Index, Command Index, Glossary, Top
19220: @unnumbered Key (Character) Index
19221: @printindex ky
19222:
19223: @node Command Index, Variable Index, Key Index, Top
19224: @unnumbered Command and Function Index
19225: @printindex fn
19226:
19227: @node Variable Index, Concept Index, Command Index, Top
19228: @unnumbered Variable Index
19229: @printindex vr
19230:
19231: @node Concept Index, Screen, Variable Index, Top
19232: @unnumbered Concept Index
19233: @printindex cp
19234:
19235: @tex
19236: \global\baselineskip 11.5pt
19237: @end tex
19238:
19239: @summarycontents
19240: @contents
19241: @bye

unix.superglobalmegacorp.com

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